Transform arrays

Transform arrays are typical PHP arrays both associative and numerical indexed arrays. Associative arrays will be turned into JSON objects and numerical indexed arrays will be turned into JSON arrays.

For example:

$transformation = [
  "type" => "example",
  "links" => [
    [
      "url": "",
      "title": "Kino.dk"
    ]
  ]
]

turns into this JSON

{
  "type": "example",
  "links": [
    {
      "url": "",
      "title": "Kino.dk"
    }
  ]
}

Controls

The next thing to know is that any associative key that starts with “#“ are used to control aspects of the transformation or used to provide information about the transformation to any alter hooks or post processors.

Here are some globally available transformation controls that you can supply in a transformation array

#access

This decides whether the user has access to view this transform. Defaults to TRUE. If FALSE will return an empty array.

#access_callback

Provides a callback to determine whether the user has access to view this transform.

#cache

This controls the caching of the transformation. This follows the standard CacheableMetadata from Drupal core.

#collapse

This is a boolean that tells the transformer that if this array only has one member, it can be collapsed into a single value. This is particularly useful if the transformation is just a value that needs to be returned.

#lazy_transformer

This allows you to add a callback that will be called after caching but before the response has been sent. This is equivalent to lazy builders in render arrays.
This can be useful if your transformation includes some very dynamic content that cannot be cached.

#pre_transform

This provides a callback that alters the transform before transformation takes place.

Any key that starts with “#“ will not be in the final JSON response, but can be accessed in alter hooks and lazy transformers.

Nested transforms

It is also possible for transform arrays to nest other transforms within it. To do so, simply include it in the array as such:

$transformation = [
  "type" => "example",
  "media" => new EntityTransform('media', $media_id, 'teaser')
]

This will tell the transformer to transform the nested transform inside it and include it in it’s output.

However, it should be noted that while you can directly add the transformation of a transform, like this:

$media_transform = new EntityTransform('media', $media_id, 'teaser')
$transformation = [
  "type" => "example",
  "media" => $media_transform->transform()
]

this is bad practice as instead of nested transforms this turns into one big transform and this does not effectively utilize caching and re-usability.

Alter hooks

All transform arrays from transforms can be altered by alter hooks before they are final.

hook_transform_alter()

This hook will be called for all transforms that the transformer processes.

hook_HOOK_transform_alter()

Is a more targeted alter hook for a certain type of transformations. The transforms themselves supply what identifies each transform allowing for instance entity transforms to target the specific entity type.