From 34bc5a6736d43013037ab4d980dcf627f31b4951 Mon Sep 17 00:00:00 2001 From: Robin Chalas Date: Mon, 6 Jun 2016 23:11:06 +0200 Subject: [PATCH] Document isReadable/getValue with Fix spelling typos Formatting/Spelling fixes Document features enabling from createPropertyAccessor() wording --- components/property_access/introduction.rst | 63 ++++++++++++--------- 1 file changed, 35 insertions(+), 28 deletions(-) diff --git a/components/property_access/introduction.rst b/components/property_access/introduction.rst index 041f7543b89..3895b454b76 100644 --- a/components/property_access/introduction.rst +++ b/components/property_access/introduction.rst @@ -24,8 +24,7 @@ Usage The entry point of this component is the :method:`PropertyAccess::createPropertyAccessor` factory. This factory will create a new instance of the -:class:`Symfony\\Component\\PropertyAccess\\PropertyAccessor` class with the -default configuration:: +:class:`Symfony\\Component\\PropertyAccess\\PropertyAccessor` class:: use Symfony\Component\PropertyAccess\PropertyAccess; @@ -46,7 +45,12 @@ method. This is done using the index notation that is used in PHP:: var_dump($accessor->getValue($person, '[first_name]')); // 'Wouter' var_dump($accessor->getValue($person, '[age]')); // null -As you can see, the method will return ``null`` if the index does not exists. +.. caution:: + + As you can see, the method return ``null`` if the index does not exist. + To make it throw an exception, you need to enable the feature by setting the second argument of + :method:`PropertyAccess::createPropertyAccessor` + to ``true``. You can also use multi dimensional arrays:: @@ -179,7 +183,7 @@ Magic ``__call()`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~ At last, ``getValue`` can use the magic ``__call`` method, but you need to -enable this feature by using :class:`Symfony\\Component\\PropertyAccess\\PropertyAccessorBuilder`:: +enable this feature by setting the first argument of :method:`PropertyAccess::createPropertyAccessor`:: // ... class Person @@ -205,17 +209,10 @@ enable this feature by using :class:`Symfony\\Component\\PropertyAccess\\Propert $person = new Person(); // Enable magic __call - $accessor = PropertyAccess::createPropertyAccessorBuilder() - ->enableMagicCall() - ->getPropertyAccessor(); + $accessor = PropertyAccess::createPropertyAccessor(true); var_dump($accessor->getValue($person, 'wouter')); // array(...) -.. caution:: - - The ``__call`` feature is disabled by default, you can enable it by calling - :method:`PropertyAccessorBuilder::enableMagicCall` - see `Enable other Features`_. Writing to Arrays ----------------- @@ -270,10 +267,7 @@ can use setters, the magic ``__set`` method or properties to set values:: var_dump($person->getLastName()); // 'de Jong' var_dump($person->children); // array(Person()); -You can also use ``__call`` to set values but you need to enable the feature, -see `Enable other Features`_. - -.. code-block:: php +You can also use ``__call`` to set values but you need to enable the feature by setting the first argument of :method:`PropertyAccess::createPropertyAccessor`:: // ... class Person @@ -298,9 +292,7 @@ see `Enable other Features`_. $person = new Person(); // Enable magic __call - $accessor = PropertyAccess::createPropertyAccessorBuilder() - ->enableMagicCall() - ->getPropertyAccessor(); + $accessor = PropertyAccess::createPropertyAccessor(true) $accessor->setValue($person, 'wouter', array(...)); @@ -321,6 +313,12 @@ instead:: // ... } +.. caution:: + + Calling :method:`PropertyAccess::createPropertyAccessor` + with an array for an invalid index would always return ``true``. + To make it return ``false``, set the second argument (``$throwExceptionOnInvalidIndex``) argument to ``true``. + The same is possible for :method:`PropertyAccessor::setValue`: Call the :method:`PropertyAccessor::isWritable` @@ -365,11 +363,13 @@ You can also mix objects and arrays:: var_dump('Hello '.$accessor->getValue($person, 'children[0].firstName')); // 'Wouter' // equal to $person->getChildren()[0]->firstName -Enable other Features -~~~~~~~~~~~~~~~~~~~~~ +Using multiple configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :method:`PropertyAccess::createPropertyAccessor` +method allows you to get a property accessor configured from the passed arguments. -The :class:`Symfony\\Component\\PropertyAccess\\PropertyAccessor` can be -configured to enable extra features. To do that you could use the +For using several property accessor configured independently, use the :class:`Symfony\\Component\\PropertyAccess\\PropertyAccessorBuilder`:: // ... @@ -378,13 +378,10 @@ configured to enable extra features. To do that you could use the // Enable magic __call $accessorBuilder->enableMagicCall(); - // Disable magic __call - $accessorBuilder->disableMagicCall(); - // Check if magic __call handling is enabled - $accessorBuilder->isMagicCallEnabled(); // true or false + $accessorBuilder->isMagicCallEnabled(); // true - // At the end get the configured property accessor + // Get the property accessor with magic __call enabled $accessor = $accessorBuilder->getPropertyAccessor(); // Or all in one @@ -392,6 +389,16 @@ configured to enable extra features. To do that you could use the ->enableMagicCall() ->getPropertyAccessor(); + // Disable magic __call + $accessorBuilder->disableMagicCall(); + + // Enable exception on invalid indexes + $accessorBuilder->enableExceptionOnInvalidIndex(); + + // Get the newly configured property accessor + $accessor = $accessorBuilder->getPropertyAccessor(); + + Or you can pass parameters directly to the constructor (not the recommended way):: // ...