The PropertyAccess Component

Note

If you install this component outside of a Symfony application, you mustrequire the file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Usage

The entry point of this component is thePropertyAccess::createPropertyAccessorfactory. This factory will create a new instance of the class with thedefault configuration:

use Symfony\Component\PropertyAccess\PropertyAccess;
 
$propertyAccessor = PropertyAccess::createPropertyAccessor();

You can read an array with thePropertyAccessor::getValuemethod. This is done using the index notation that is used in PHP:

// ...
$person = [
    'first_name' => 'Wouter',
];
 
var_dump($propertyAccessor->getValue($person, '[first_name]')); // 'Wouter'
var_dump($propertyAccessor->getValue($person, '[age]')); // null

As you can see, the method will return null if the index does not exist.But you can change this behavior with themethod:

// ...
$propertyAccessor = PropertyAccess::createPropertyAccessorBuilder()
    ->enableExceptionOnInvalidIndex()
    ->getPropertyAccessor();
 
$person = [
    'first_name' => 'Wouter',
];
 
// instead of returning null, the code now throws an exception of type
// Symfony\Component\PropertyAccess\Exception\NoSuchIndexException
$value = $propertyAccessor->getValue($person, '[age]');

You can also use multi dimensional arrays:

// ...
$persons = [
    [
        'first_name' => 'Wouter',
    ],
    [
        'first_name' => 'Ryan',
    ]
];
 
var_dump($propertyAccessor->getValue($persons, '[0][first_name]')); // 'Wouter'
var_dump($propertyAccessor->getValue($persons, '[1][first_name]')); // 'Ryan'

Reading from Objects

The getValue() method is a very robust method, and you can see all of itsfeatures when working with objects.

To read from properties, use the "dot" notation:

// ...
$person = new Person();
$person->firstName = 'Wouter';
 
var_dump($propertyAccessor->getValue($person, 'firstName')); // 'Wouter'
 
$child = new Person();
$child->firstName = 'Bar';
$person->children = [$child];
 
var_dump($propertyAccessor->getValue($person, 'children[0].firstName')); // 'Bar'

Caution

Accessing public properties is the last option used by PropertyAccessor.It tries to access the value using the below methods first before usingthe property directly. For example, if you have a public property thathas a getter method, it will use the getter.

Using Getters

The getValue() method also supports reading using getters. The method willbe created using common naming conventions for getters. It camelizes theproperty name (first_name becomes FirstName) and prefixes it withget. So the actual method becomes getFirstName():

And it doesn't even stop there. If there is no getter found, the accessor willlook for an isser or hasser. This method is created using the same way asgetters, this means that you can do something like this:

// ...
class Person
{
    private $author = true;
    private $children = [];
 
    public function isAuthor()
    {
        return $this->author;
    }
 
    public function hasChildren()
    {
        return 0 !== count($this->children);
    }
}
 
$person = new Person();
 
if ($propertyAccessor->getValue($person, 'author')) {
    var_dump('He is an author');
if ($propertyAccessor->getValue($person, 'children')) {
    var_dump('He has children');
}

This will produce: He is an author

Accessing a non Existing Property Path

New in version 4.3: The method was introduced inSymfony 4.3.

By default a is thrown if the property path passed to PropertyAccessor::getValuedoes not exist. You can change this behavior using themethod:

// ...
class Person
{
    public $name;
}
 
$person = new Person();
 
$propertyAccessor = PropertyAccess::createPropertyAccessorBuilder()
    ->disableExceptionOnInvalidPropertyPath()
    ->getPropertyAccessor();
 
// instead of throwing an exception the following code returns null
$value = $propertyAccessor->getValue($person, 'birthday');

The getValue() method can also use the magic __get() method:

// ...
class Person
{
    private $children = [
        'Wouter' => [...],
    ];
 
    public function __get($id)
    {
        return $this->children[$id];
    }
}
 
$person = new Person();
 
var_dump($propertyAccessor->getValue($person, 'Wouter')); // [...]

Magic __call() Method

At last, getValue() can use the magic __call() method, but you need toenable this feature by using :

// ...
class Person
{
    private $children = [
        'wouter' => [...],
    ];
 
    public function __call($name, $args)
    {
        $property = lcfirst(substr($name, 3));
        if ('get' === substr($name, 0, 3)) {
            return isset($this->children[$property])
                ? $this->children[$property]
                : null;
        } elseif ('set' === substr($name, 0, 3)) {
            $value = 1 == count($args) ? $args[0] : null;
            $this->children[$property] = $value;
        }
    }
}
 
$person = new Person();
 
// enables PHP __call() magic method
$propertyAccessor = PropertyAccess::createPropertyAccessorBuilder()
    ->enableMagicCall()
    ->getPropertyAccessor();
 
var_dump($propertyAccessor->getValue($person, 'wouter')); // [...]

Caution

The __call() feature is disabled by default, you can enable it by callingPropertyAccessorBuilder::enableMagicCallsee .

The PropertyAccessor class can do more than just read an array, it canalso write to an array. This can be achieved using thePropertyAccessor::setValuemethod:

// ...
$person = [];
 
$propertyAccessor->setValue($person, '[first_name]', 'Wouter');
 
var_dump($propertyAccessor->getValue($person, '[first_name]')); // 'Wouter'
// or
// var_dump($person['first_name']); // 'Wouter'

Writing to Objects

The setValue() method has the same features as the method. Youcan use setters, the magic __set() method or properties to set values:

You can also use __call() to set values but you need to enable the feature,see Enable other Features:

// ...
class Person
{
    private $children = [];
 
    public function __call($name, $args)
    {
        $property = lcfirst(substr($name, 3));
        if ('get' === substr($name, 0, 3)) {
            return isset($this->children[$property])
                ? $this->children[$property]
                : null;
            $value = 1 == count($args) ? $args[0] : null;
            $this->children[$property] = $value;
        }
    }
 
}
 
$person = new Person();
 
// Enable magic __call
$propertyAccessor = PropertyAccess::createPropertyAccessorBuilder()
    ->enableMagicCall()
    ->getPropertyAccessor();
 
$propertyAccessor->setValue($person, 'wouter', [...]);
 
var_dump($person->getWouter()); // [...]

The PropertyAccessor class allows to update the content of arrays stored inproperties through adder and remover methods:

// ...
class Person
{
    /**
     * @var string[]
     */
    private $children = [];
 
    public function getChildren(): array
    {
        return $this->children;
    }
 
    public function addChild(string $name): void
    {
        $this->children[$name] = $name;
    }
 
    public function removeChild(string $name): void
    {
        unset($this->children[$name]);
    }
}
 
$person = new Person();
$propertyAccessor->setValue($person, 'children', ['kevin', 'wouter']);
 
var_dump($person->getChildren()); // ['kevin', 'wouter']

The PropertyAccess component checks for methods called add<SingularOfThePropertyName>()and remove<SingularOfThePropertyName>(). Both methods must be defined.For instance, in the previous example, the component looks for the addChild()and removeChild() methods to access to the children property. is used to find the singular of a property name.

If available, adder and remover methods have priority over a setter method.

When you want to check whetherPropertyAccessor::getValuecan safely be called without actually calling that method, you can useinstead:

$person = new Person();
 
if ($propertyAccessor->isReadable($person, 'firstName')) {
    // ...
}

The same is possible for PropertyAccessor::setValue:Call themethod to find out whether a property path can be updated:

$person = new Person();
 
if ($propertyAccessor->isWritable($person, 'firstName')) {
    // ...
}

Mixing Objects and Arrays

You can also mix objects and arrays:

// ...
class Person
{
    public $firstName;
    private $children = [];
 
    public function setChildren($children)
    {
        $this->children = $children;
    }
 
    public function getChildren()
    {
        return $this->children;
    }
}
 
$person = new Person();
 
$propertyAccessor->setValue($person, 'children[0]', new Person);
// equal to $person->getChildren()[0] = new Person()
 
$propertyAccessor->setValue($person, 'children[0].firstName', 'Wouter');
// equal to $person->getChildren()[0]->firstName = 'Wouter'
 
var_dump('Hello '.$propertyAccessor->getValue($person, 'children[0].firstName')); // 'Wouter'
// equal to $person->getChildren()[0]->firstName

Enable other Features

The PropertyAccessor can beconfigured to enable extra features. To do that you could use the:

Or you can pass parameters directly to the constructor (not the recommended way):

$propertyAccessor = new PropertyAccessor(true); // this enables handling of magic __call