From 5e5c93d6932f48239ea05ec9c9e6c0181e654e5e Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 14 Jan 2013 20:11:31 +0100 Subject: [PATCH] Created PropertyAccess component docs --- components/map.rst.inc | 4 + components/property_access/index.rst | 7 + components/property_access/introduction.rst | 264 ++++++++++++++++++++ 3 files changed, 275 insertions(+) create mode 100644 components/property_access/index.rst create mode 100644 components/property_access/introduction.rst diff --git a/components/map.rst.inc b/components/map.rst.inc index 930f87ee83f..61f858fd3a5 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -71,6 +71,10 @@ * :doc:`/components/process` +* :doc:`/components/property_access/index + + * :doc:`/components/property_access/introduction` + * :doc:`/components/routing/index` * :doc:`/components/routing/introduction` diff --git a/components/property_access/index.rst b/components/property_access/index.rst new file mode 100644 index 00000000000..c40373aaac1 --- /dev/null +++ b/components/property_access/index.rst @@ -0,0 +1,7 @@ +Property Access +=============== + +.. toctree:: + :maxdepth: 2 + + introduction diff --git a/components/property_access/introduction.rst b/components/property_access/introduction.rst new file mode 100644 index 00000000000..0b24c3401e3 --- /dev/null +++ b/components/property_access/introduction.rst @@ -0,0 +1,264 @@ +.. index:: + single: PropertyAccess + single: Components; PropertyAccess + +The PropertyAccess Component +============================ + + PropertyAccess component provides function to read and write from/to an + object or array using a simple string notation. + +.. versionadded:: 2.2 + The PropertyAccess Component is new to Symfony 2.2. Previously, the + ``PropertyPath`` class was located in the ``Form`` component. + +Installation +------------ + +You can install the component in two different ways: + +* Use the official Git repository (https://github.com/symfony/PropertyAccess); +* :doc:`Install it via Composer` * (``symfony/property-access`` on `Packagist`_). + +Usage +----- + +The entry point of this component is the +:method:`Symfony\\Component\\PropertyAccess\\PropertyAccess::getPropertyAccessor` +factory. This factory will create a new instance of the +:class:`Symfony\\Component\\PropertyAccess\PropertyAccessor` class with the +default configuration:: + + use Symfony\Component\PropertyAccess\PropertyAccess; + + $accessor = PropertyAccess:getPropertyAccessor(); + +Reading from arrays +------------------- + +You can read an array with the +:method:`Symfony\\Component\\PropertyAccess\PropertyAccessor::getValue` +method. This is done using the index notation that is used in PHP:: + + // ... + $person = array( + 'first_name' => 'Wouter', + ); + + echo $accessor->getValue($persons, '[first_name]'); // 'Wouter' + echo $accessor->getValue($person, '[age]'); // null + +As you can see, the method will return ``null`` if the index does not exists. + +You can also use multi dimensional arrays:: + + // ... + $persons = array( + array( + 'first_name' => 'Wouter', + ), + array( + 'first_name' => 'Ryan', + ) + ); + + echo $accessor->getValue($persons, '[0][first_name]'); // 'Wouter' + echo $accessor->getValue($persons, '[1][first_name]'); // 'Ryan' + +Reading from objects +-------------------- + +The ``getValue`` method is a very robust method. You can see all features if +you are working with objects. + +Using properties +~~~~~~~~~~~~~~~~ + +We can read properties without the index notation, instead we use the dot +notation:: + + // ... + $person = new Person(); + $person->firstName = 'Wouter'; + + echo $accessor->getValue($person, 'first_name'); // 'Wouter' + + $child = new Person(); + $child->firstName = 'Bar'; + $person->children = array($child); + + echo $accessor->getValue($person, 'children[0].first_name'); // 'Bar' + +.. caution:: + + This option is the last option used by the ``PropertyAccessor``. It tries + to find the other options before using the property. If you have a public + property that have a getter to, it will use the getter. + +Using getters +~~~~~~~~~~~~~ + +The ``getValue`` method also supports reading using getters. The method will +be created using common naming conventions for getters. It camelizes the +property name (``first_name`` becomes ``FirstName``) and prefixes it with +``get``. So the actual method becomes ``getFirstName``:: + + // ... + class Person + { + private $firstName = 'Wouter'; + + public function getFirstName() + { + return $this->firstName; + } + } + + $person = new Person(); + + echo $accessor->getValue($person, 'first_name'); // 'Wouter' + +Using hassers/issers +~~~~~~~~~~~~~~~~~~~~ + +And it doesn't even stop there. If there is no getter found, the accessor will +look for a isser or hasser. This method is created using the same way as +getters, this means that you can do something like this:: + + // ... + class Person + { + private $author = true; + private $children = array(); + + public function isAuthor() + { + return $this->author; + } + + public function hasChildren() + { + return 0 !== count($this->children); + } + } + + $person = new Person(); + + if ($accessor->getValue($person, 'author')) { + echo 'He is an author'; + } + if ($accessor->getValue($person, 'children')) { + echo 'He has children'; + } + +This will produce: ``He is an author`` + +Magic Methods +~~~~~~~~~~~~~ + +At last, the ``getValue`` can use the magic ``__get`` too:: + + // ... + class Person + { + private $children = array( + 'wouter' => array(...), + ); + + public function __get($id) + { + return $this->children[$id]; + } + } + + $person = new Person(); + + echo $accessor->getValue($person, 'Wouter'); // array(...) + +Writing to arrays +----------------- + +The ``PropertyAccessor`` class can do more than just reading an array, it can +also write to an array. This can be achieved using the +:method:`Symfony\\Component\\PropertyAccess\\PropertyAccessor::setValue` +method:: + + // ... + $person = array(); + + $accessor->setValue($person, '[first_name]', 'Wouter'); + + echo $accessor->getValue($person, '[first_name]'); // 'Wouter' + // or + // echo $person['first_name']; // 'Wouter' + +Writing to objects +------------------ + +The ``setValue`` method has the same features as the ``getValue`` method. You +can use setters, the magic ``__set`` or properties to set values:: + + // ... + class Person + { + public $firstName; + private $lastName; + private $children = array(); + + public function setLastName($name) + { + $this->lastName = $name; + } + + public function __set($property, $value) + { + $this->$property = $value; + } + + // ... + } + + $person = new Person(); + + $accessor->setValue($person, 'firstName', 'Wouter'); + $accessor->setValue($person, 'lastName', 'de Jong'); + $accessor->setValue($person, 'children', array(new Person())); + + echo $person->firstName; // 'Wouter' + echo $person->getLastName(); // 'de Jong' + echo $person->children; // array(Person()); + +Mixing objects and arrays +------------------------- + +You can also mix objects and arrays:: + + // ... + class Person + { + public $firstName; + private $children = array(); + + public function setChildren($children) + { + return $this->children; + } + + public function getChildren() + { + return $this->children; + } + } + + $person = new Person(); + + $accessor->setValue($person, 'children[0]', new Person); + // equal to $person->getChildren()[0] = new Person() + + $accessor->setValue($person, 'children[0].firstName', 'Wouter'); + // equal to $person->getChildren()[0]->firstName = 'Wouter' + + echo 'Hello '.$accessor->getValue($person, 'children[0].firstName'); // 'Wouter' + // equal to $person->getChildren()[0]->firstName + +.. _Packagist: https://packagist.org/packages/symfony/property-access