Download the PHP package rexlabs/laravel-smokescreen without Composer

Laravel Smokescreen

Overview

Laravel Smokescreen is a package for transforming your Laravel models, and other entities.

• Transform API responses
• Transform Job and Event payloads
• Minimal boiler-plate and bootstrap
• Supports complex relationships for embedded data
• Supports eager loading of relationships
• Allows transforming different types of resources
• Can handle serializing to customisable formats

This package tightly integrates the rexlabs/smokescreen (Vanilla PHP) package with the Laravel framework, to provide the convenience and minimal boilerplate when working with Laravel applications.

Usage

• laravel-smokescreen is bootstrapped into Laravel's app container, so you can also type-hint it to be injected into your controller's constructor or methods.
• Using the facade (as above) is recommended within controller methods, use type-hinting in service classes (if needed)
• You can also use it directly from the container via app('smokescreen') as shown above.
• Since we implement the Responsable interface, you can simply return smokescreen from any controller method.

Requirements

• PHP >= 7.0
• Laravel >= 5.5

Installation

This package is currently hosted on RexSoftware's private packagist repository. First ensure you have configured your composer.json to use this repository.

Install package

composer require rexlabs/laravel-smokescreen

This package will be auto-discovered, and no additional configuration is necessary.

Configuration

To publish the configuration file to your app/config folder, run the following command:

This will create config/smokescreen.php:

API

transform(): Set resource to be transformed

$smokescreen->transform(mixed $resource, mixed $transformer = null);

• Smokescreen will automatically determine the type of resource being transformed.
• It will also infer the Transformer class to use if not provided.

item(): Set single item resource to be transformed

$smokescreen->item(mixed $item, mixed $transformer = null);

• Similar to transform() but only accepts a item.

collection(): Set collection resource to be transformed

$smokescreen->collection(mixed $collection, mixed $transformer = null);

• Similar to transform() but only accepts a collection.

transformWith(): Set the transformer to use on the previously set resource

$smokescreen->transformWith(TransformerInterface|callable $transformer);

• It's an alternative to passing the transformer directly to resource methods.

serializeWith(): Override the serializer to be used

• You only need to set this if you plan to use a different serialize than the default.
• We provide DefaultSerializer as the default, it returns collections nested under a "data" node, and an item resource without any nesting.
• Your custom serializer should implement the SerializerInterface interface.

loadRelationsVia(): Override the default Laravel relations loader

$smokescreen->loadRelationsVia(RelationsLoaderInterface $loader);

• You only need to set this if you plan to use a different loader than the default,
• We provide RelationsLoader as the default which eager-loads relationships for collection resources.
• Your custom loader should implement the RelationsLoaderInterface interface and provide a load() method.

resolveTransformerVia(): Override the default transformer resolver

$smokescreen->loadTransformersVia(TransformerResolverInterface $loader);

• The resolver is used when a transformer is not explicitly defined on a resource.
• The default resolver in this package tries to find a matching transformer class within the path defined in smokescreen.transformer_namespace path, and instantiates it via the app container.
• You only need to set this if you plan to use a different resolver than the default.
• Your custom resolver should implement the TransformersLoaderInterface interface and provide a resolve(ResourceInterface) method.

response(): Access the generated response object

$response = $smokescreen->response(int $statusCode = 200, array $headers = [], int $options = 0);

• This method returns an \Illuminate\Http\JsonResponse object so it is not chainable.
• All supported JsonResponse methods can be applied.
• You can still return response() directly from your controller since it is a JsonResponse object.
• You can alternatively use withResponse($callback) to apply changes, and still support chainability.
• Note: the first call to response() caches the result so that the entire data set is not re-generated every time, this means passing any parameters on subsequent calls will be ignored. You can use clearResponse() or manipulate the JsonResponse object directly.

freshResponse(): Generate a fresh Response object

$response = $smokescreen->freshResponse(int $statusCode = 200, array $headers = [], int $options = 0);

• Unlike response() this method returns a fresh non-cached JsonResponse object (by calling clearResponse() first).
• This method returns an \Illuminate\Http\JsonResponse object so it is not chainable. See withResponse() for a chainable method.
• All supported JsonResponse methods can be applied.

withResponse(): Apply changes to the generated response object

$smokescreen->withResponse(callable $apply);

• Provide a callback that accepts a JsonResponse object and manipulates the response
• This method is chainable unlike response()

clearResponse(): Clear any cached response

$smokescreen->clearResponse();

• Reset's any cached response object

Transformers

Example Transformer

• You declare your available includes via the $includes array
• Each include accepts 0 or more of the following directives:
  • default: This include is always enabled regardless of the requested includes
  • relation: Indicates that a relation should be eager-loaded. If the relation name is different specify it as relation:othername
  • method: By default the include key is mapped to include{IncludeKey} you can provide the method to be used instead
• Your transform() method should return an array.
• Define your include methods in the format include{IncludeKey}(Model) - they should return either a collection() or an item()
• when() is a simple helper method which accepts a condition and returns either the given value when true, or null (by default) when false. In the above example the "user" node will be null if there is no user_id set on the $post object.

Contributing

Pull-requests are welcome. Please ensure code is PSR compliant. Github Repository

About

• Author: Jodie Dunlop
• License: MIT
• Copyright (c) 2018 Rex Software Pty Ltd