feature #3729 Added documentation for the new PropertyAccessor::isReadable() and isWritable() methods (webmozart)

weaverryan · weaverryan · commit be4b9d3b8e3d · 2014-04-12T10:34:15.000-04:00
This PR was merged into the master branch. Discussion ---------- Added documentation for the new PropertyAccessor::isReadable() and isWritable() methods | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes (symfony/symfony#10570) | Applies to | 2.5+ | Fixed tickets | - Commits ------- bb8e3ed Added documentation for the new PropertyAccessor::isReadable() and isWritable() methods
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
 -------------------------
 
