Transformation

This boilerplate contains a very rich transformation layer, containing a lot of useful functionality.

The transformation of a single response is done by an individual transformer class (found in App\Transformers), and by default it contains a "BaseTransformer" class, which you can use to override the default logic of the boilerplate's transformer.

Making your own transformer

It is possible to specify a different transformer than the base transformer to be used for a given response. This is very useful if you need something extra done for a specific request or resource.

I recommend you use the following strategy for overriding transformers;

1. Call the base transformer's transform() method
2. Modify the result to suit your purposes

For example -

class UserTransformer extends BaseTransformer
{
    public function transform(Object $object)
    {
        $transformed =  parent::transform($object);

        // Your own added logic

        return $transformed;
    }

}

Using Custom Transformers

More often than not you will not need to override the default transformer. In the cases that you do, likely it will be most logical to override it at the model level (for very complex resources), and only in rare cases at the controller level (for example, dashboards).

Specify on model

You can specify a transformer to be used for a specific resource in it's model's class in the $transformer attribute. This model will then always use this transformer - no matter which controller is responsible for the request.

Specify on controller

You can specify a transformer to be used for a specific controller (ie. endpoint), in the controller's $transformer attribute. This will transform all responses coming out of this controller (regardless of whatever models it spits out) using this transformer.

Example

If you wanted to add a custom transformer to the User model;

   public static $transformer = UserTransformer::class;

Transformation Hierarchy

You may be wondering which transformers take precedence. Consider this hierarchy;

1. Transformer specified in the controller always takes precedence
2. Transformer specified in the model takes precedence otherwise
3. Base Transformer is used when no special transformer is defined for the controller, and model

If you have nested models which need to be transformed, they will be transformed using the same hierarchy, minus the controller transformer as it's not applicable in this situation.

Relations Transformation

All relations which have been loaded in the model(s) which are being transformed for response, themselves will get transformed using their own transformers. This works recursively. All related models will appear as nested objects in the response.

Case Type

One of the features of this boilerplate is to allow for configuring which case type you would like in your responses. Currently the options "camel-case" and "snake-case" are supported.

Change through config

You can change this setting in your config/api.php file, the setting is under the name "formatsOptions.caseType".

Change through request headers

This boilerplate also accepts a special header named "X-Accept-Case-Type", which will override any configuration (as specified above) and allow the request caller to specify the case type they would prefer.

This is especially useful if you have multiple API consumers, and they have different preferences for case type.

PHP Guzzle Example:

$api->get('http://your-api.com/resource', [
    'headers'         => ['X-Accept-Case-Type' => 'snake-case'],
]);