Merge pull request #1188 from arneee/master

[Docs] Improve documentation on dynamic exclusion strategy
schmittjoh · Apr 21, 2020 · 3a811f7 · 3a811f7
2 parents a7f3490 + ce0ccad
commit 3a811f7
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 5 deletions.
diff --git a/doc/cookbook/exclusion_strategies.rst b/doc/cookbook/exclusion_strategies.rst
@@ -334,3 +334,29 @@ By default the serializer exposes three variables (`object`, `context` and `prop
     }
 
 .. _GroupExclusionStrategy: https://github.com/schmittjoh/serializer/blob/master/src/Exclusion/GroupsExclusionStrategy.php
+
+Using dynamic excludes on class level is also handy when you need to filter out certain objects in a collection, for example based on user permissions.
+The following example shows how to exclude `Account` objects when serializing the `Person` object, if the `Account` is either expired or the user does not have the permission to view the account by calling `is_granted` with the `Account` object.
+
+.. code-block :: php
+
+    <?php
+
+    class Person
+    {
+        /**
+         * @Type("array<Account>")
+         */
+        public $accounts;
+    }
+
+    /**
+     * @Exclude(if="object.expired || !is_granted('view',object)")
+     */
+    class Account
+    {
+        /**
+         * @Type("boolean")
+         */
+        public $expired;
+    }
diff --git a/doc/reference/annotations.rst b/doc/reference/annotations.rst
@@ -18,11 +18,12 @@ that should be used for the class.
 
 @Exclude
 ~~~~~~~~
-This annotation can be defined on a property to indicate that the property should
-not be serialized/unserialized. Works only in combination with NoneExclusionPolicy.
+This annotation can be defined on a property or a class to indicate that the property or class
+should not be serialized/unserialized. Works only in combination with NoneExclusionPolicy.
 
-If the ``ExpressionLanguageExclusionStrategy`` exclusion strategy is enabled, will
-be possible to use ``@Exclude(if="expression")`` to exclude dynamically a property.
+If the ``ExpressionLanguageExclusionStrategy`` exclusion strategy is enabled, it will
+be possible to use ``@Exclude(if="expression")`` to exclude dynamically a property
+or an object if used on class level.
 
 @Expose
 ~~~~~~~

diff --git a/doc/reference/xml_reference.rst b/doc/reference/xml_reference.rst
@@ -6,7 +6,7 @@ XML Reference
     <?xml version="1.0" encoding="UTF-8" ?>
     <serializer>
         <class name="Fully\Qualified\ClassName" exclusion-policy="ALL" xml-root-name="foo-bar" exclude="true"
-            accessor-order="custom" custom-accessor-order="propertyName1,propertyName2,...,propertyNameN"
+            exclude-if="expr" accessor-order="custom" custom-accessor-order="propertyName1,propertyName2,...,propertyNameN"
             access-type="public_method" discriminator-field-name="type" discriminator-disabled="false" read-only="false">
             <xml-namespace prefix="atom" uri="http://www.w3.org/2005/Atom"/>
             <xml-discriminator attribute="true" cdata="false" namespace=""/>

diff --git a/doc/reference/yml_reference.rst b/doc/reference/yml_reference.rst
@@ -8,6 +8,7 @@ YAML Reference
         xml_root_name: foobar
         xml_root_namespace: http://your.default.namespace
         exclude: true
+        exclude_if: expr
         read_only: false
         access_type: public_method # defaults to property
         accessor_order: custom