Added documentation for the new PropertyAccessor::isReadable() and isWritable() methods

webmozart · webmozart · commit bb8e3ed3ee2e · 2014-03-28T17:33:52.000+01:00
diff --git a/components/property_access/introduction.rst b/components/property_access/introduction.rst
@@ -309,6 +309,39 @@ see `Enable other Features`_.
 
     echo $person->getWouter(); // array(...)
 
+Checking Property Paths
+-----------------------
+
+.. versionadded:: 2.5
+    The methods
+    :method:`PropertyAccessor::isReadable<Symfony\\Component\\PropertyAccess\\PropertyAccessor::isReadable>`
+    and
+    :method:`PropertyAccessor::isWritable<Symfony\\Component\\PropertyAccess\\PropertyAccessor::isWritable>`
+    methods were added in Symfony 2.5.
+
+When you want to check whether :method:`PropertyAccessor::getValue<Symfony\\Component\\PropertyAccess\\PropertyAccessor::getValue>`
+can safely be called without actually calling that method, you can use
+:method:`PropertyAccessor::isReadable<Symfony\\Component\\PropertyAccess\\PropertyAccessor::isReadable>`
+instead::
+
+    $person = new Person();
+
+    if ($accessor->isReadable($person, 'firstName') {
+        // ...
+    }
+
+The same is possible for :method:`PropertyAccessor::setValue<Symfony\\Component\\PropertyAccess\\PropertyAccessor::setValue>`:
+Call the
+:method:`PropertyAccessor::isWritable<Symfony\\Component\\PropertyAccess\\PropertyAccessor::isWritable>`
+method to find out whether a property path can be updated. In the third
+argument, you should pass the value that you want to write::
+
+    $person = new Person();
+
+    if ($accessor->isWritable($person, 'firstName', 'Wouter') {
+        // ...
+    }
+
 Mixing Objects and Arrays
 -------------------------
 
