minor #13754 [PropertyAccess] unify and fix doc (Tobion)

This PR was merged into the 2.6 branch.

Discussion
----------

[PropertyAccess] unify and fix doc

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets |
| License       | MIT
| Doc PR        | -

Commits
-------

d1c8c5d [PropertyAccess] unify and fix doc

Author: fabpot

src/Symfony/Component/PropertyAccess/PropertyAccessor.php

@@ -200,17 +200,19 @@ private function &readPropertiesUntil(&$objectOrArray, PropertyPathInterface $pr
                     if (!is_array($objectOrArray)) {
                         if (!$objectOrArray instanceof \Traversable) {
                             throw new NoSuchIndexException(sprintf(
-                                'Cannot read property "%s".',
-                                $property
+                                'Cannot read index "%s" while trying to traverse path "%s".',
+                                $property,
+                                (string) $propertyPath
                             ));
                         }
 
                         $objectOrArray = iterator_to_array($objectOrArray);
                     }
 
                     throw new NoSuchIndexException(sprintf(
-                        'Cannot read property "%s". Available properties are "%s"',
+                        'Cannot read index "%s" while trying to traverse path "%s". Available indices are "%s".',
                         $property,
+                        (string) $propertyPath,
                         print_r(array_keys($objectOrArray), true)
                     ));
                 }
@@ -250,7 +252,7 @@ private function &readPropertiesUntil(&$objectOrArray, PropertyPathInterface $pr
     private function &readIndex(&$array, $index)
     {
         if (!$array instanceof \ArrayAccess && !is_array($array)) {
-            throw new NoSuchIndexException(sprintf('Index "%s" cannot be read from object of type "%s" because it doesn\'t implement \ArrayAccess', $index, get_class($array)));
+            throw new NoSuchIndexException(sprintf('Cannot read index "%s" from object of type "%s" because it doesn\'t implement \ArrayAccess.', $index, get_class($array)));
         }
 
         // Use an array instead of an object since performance is very crucial here
@@ -294,7 +296,7 @@ private function &readProperty(&$object, $property)
         );
 
         if (!is_object($object)) {
-            throw new NoSuchPropertyException(sprintf('Cannot read property "%s" from an array. Maybe you should write the property path as "[%s]" instead?', $property, $property));
+            throw new NoSuchPropertyException(sprintf('Cannot read property "%s" from an array. Maybe you intended to write the property path as "[%s]" instead.', $property, $property));
         }
 
         $camelized = $this->camelize($property);
@@ -364,7 +366,7 @@ private function &readProperty(&$object, $property)
     private function writeIndex(&$array, $index, $value)
     {
         if (!$array instanceof \ArrayAccess && !is_array($array)) {
-            throw new NoSuchIndexException(sprintf('Index "%s" cannot be modified in object of type "%s" because it doesn\'t implement \ArrayAccess', $index, get_class($array)));
+            throw new NoSuchIndexException(sprintf('Cannot modify index "%s" in object of type "%s" because it doesn\'t implement \ArrayAccess', $index, get_class($array)));
         }
 
         $array[$index] = $value;

src/Symfony/Component/PropertyAccess/PropertyAccessorBuilder.php

@@ -12,7 +12,7 @@
 namespace Symfony\Component\PropertyAccess;
 
 /**
- * A configurable builder for PropertyAccessorInterface objects.
+ * A configurable builder to create a PropertyAccessor.
  *
  * @author Jérémie Augustin <[email protected]>
  */
@@ -53,15 +53,18 @@ public function disableMagicCall()
     }
 
     /**
-     * @return bool true if the use of "__call" by the PropertyAccessor is enabled
+     * @return bool whether the use of "__call" by the PropertyAccessor is enabled
      */
     public function isMagicCallEnabled()
     {
         return $this->magicCall;
     }
 
     /**
-     * Enables exceptions in read context for array by PropertyAccessor
+     * Enables exceptions when reading a non-existing index.
+     *
+     * This has no influence on writing non-existing indices with PropertyAccessorInterface::setValue()
+     * which are always created on-the-fly.
      *
      * @return PropertyAccessorBuilder The builder object
      */
@@ -73,7 +76,9 @@ public function enableExceptionOnInvalidIndex()
     }
 
     /**
-     * Disables exceptions in read context for array by PropertyAccessor
+     * Disables exceptions when reading a non-existing index.
+     *
+     * Instead, null is returned when calling PropertyAccessorInterface::getValue() on a non-existing index.
      *
      * @return PropertyAccessorBuilder The builder object
      */
@@ -85,17 +90,17 @@ public function disableExceptionOnInvalidIndex()
     }
 
     /**
-     * @return bool true is exceptions in read context for array is enabled
+     * @return bool whether an exception is thrown or null is returned when reading a non-existing index
      */
     public function isExceptionOnInvalidIndexEnabled()
     {
         return $this->throwExceptionOnInvalidIndex;
     }
 
     /**
-     * Builds and returns a new propertyAccessor object.
+     * Builds and returns a new PropertyAccessor object.
      *
-     * @return PropertyAccessorInterface The built propertyAccessor
+     * @return PropertyAccessorInterface The built PropertyAccessor
      */
     public function getPropertyAccessor()
     {