Merge pull request timber#2846 from timber/2811-v2x-acf-post-object-f…

…ield-group

docs: Documented transform_value filter/parameter

docs/v2/integrations/advanced-custom-fields.md

@@ -20,6 +20,51 @@ If you’ve worked with ACF before, you’re use to use `get_field( 'my_acf_fiel
 $meta = $post->meta('my_acf_field');
 ```
 
+### Transform values to Timber/PHP objects  
+Timber by default returns all field values as is based on the return type set in your ACF field setting.
+
+But sometimes you might want to transform values directly into Timber/PHP objects. For example, if you have a relationship field, you might want to transform the values directly into `Timber\Post` objects.
+
+You can do so using the `timber/meta/transform_value` filter:
+
+**functions.php**
+```php
+add_filter('timber/meta/transform_value', '__return__true');
+```
+
+Or you can use the `transform_value` parameter to transform values on a field by field basis:
+
+**Twig**
+
+```twig
+{{ post.meta('my_acf_field', { transform_value: true }) }}
+```
+
+**PHP**
+
+```php
+$meta = $post->meta('my_meta_field', ['transform_value' => true]);
+```
+
+You can also use both the filter and parameter options at the same time to globally transform values and then opt-out on a field by field basis by setting `transform_value` to `false`.
+
+The values of the following field types will be transformed into Timber/PHP objects when using transforms:
+
+| Field type | Returns  |
+|---------|---------|
+| File    | `Timber\Attachment`         |
+| Image    | `Timber\Image`         |
+| Gallery    | array of `Timber\Post` objects         |
+| Date picker     |  `DateTimeImmutable`       |
+| Date time picker     |  `DateTimeImmutable`       |
+| Post object     | array of `Timber\Post` objects         |
+| Relationship     | array of `Timber\Post` objects         |
+| Taxonomy     | array of `Timber\Term` objects         |
+| User     | array of `Timber\User` objects         |
+
+
+
+
 ### Unformatted values
 
 In ACF, all values are filtered. If you want to use unfiltered, raw values from the database, you’re probably used to using the third parameter for `get_field()`, which is called `$format_value`. This defaults to true. In Timber, you’d pass it like so: