smokescreen laravel php

Дымовая завеса Laravel

Обзор

Laravel Smokescreen — это пакет для преобразования ваших моделей Laravel и других объектов.

• Преобразование ответов API
• Преобразование полезных данных заданий и событий
• Минимальный шаблон и начальная загрузка
• Поддерживает сложные связи для встроенных данных.
• Поддерживает активную загрузку отношений
• Позволяет трансформировать различные типы ресурсов.
• Может обрабатывать сериализацию в настраиваемые форматы.

Этот пакет тесно интегрирует пакет rexlabs/smokescreen (Vanilla PHP) с платформой Laravel, чтобы обеспечить удобство и минимальный набор шаблонов при работе с приложениями Laravel.

Использование

 <?php
class MyController extends Controller
{
    public function index ()
    {
        return Smokescreen:: transform (Post:: paginate ());
    }
    
     public function show ( Post $ post )
     {
        return Smokescreen:: transform ( $ post );
     }
}

• laravel-smokescreen загружается в контейнер приложения Laravel, поэтому вы также можете ввести подсказку для его внедрения в конструктор или методы вашего контроллера.
• Использование фасада (как указано выше) рекомендуется в методах контроллера, используйте подсказки типов в классах обслуживания (при необходимости).
• Вы также можете использовать его непосредственно из контейнера через app('smokescreen') как показано выше.
• Поскольку мы реализуем интерфейс Responsable , вы можете просто вернуть дымовую завесу из любого метода контроллера.

Требования

• PHP >= 7.0
• Ларавел >= 5,5

Установка

Этот пакет в настоящее время размещен в частном репозитории RexSoftware. Сначала убедитесь, что вы настроили ваш composer.json для использования этого репозитория.

Установить пакет

composer require rexlabs/laravel-smokescreen

Этот пакет будет обнаружен автоматически, и дополнительная настройка не потребуется.

Конфигурация

Чтобы опубликовать файл конфигурации в папке app/config , выполните следующую команду:

php artisan vendor:publish --provider= ' RexlabsLaravelSmokescreenProvidersServiceProvider --tag=config '

Это создаст config/smokescreen.php :

 <?php
return [
    // Set the default namespace for resolving transformers when
    // they are not explicitly provided.
    ' transformer_namespace ' => ' AppTransformers ' ,
    
    // Override the default serializer to be used.
    // If not specified - the Smokescreen DefaultSerializer will be used.
    ' default_serializer ' => null ,

    // Set the default request parameter key which is parsed for
    // the list of includes.
    ' include_key ' => ' include ' ,
];

API

Transform(): установить ресурс для преобразования

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

 <?php
$ smokescreen -> transform (Post:: find ( 1 ));
$ smokescreen -> transform (Post:: all ());
$ smokescreen -> transform (Post:: paginate ());
$ smokescreen -> transform (Post:: find ( 1 ), new SomeOtherTransformer );

• Smokescreen автоматически определит тип преобразуемого ресурса.
• Он также выведет класс Transformer, который будет использоваться, если он не указан.

item(): установить один ресурс элемента для преобразования.

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

 <?php
$ smokescreen -> item (Post:: find ( 1 ));
$ smokescreen -> item (Post:: find ( 1 ), new SomeOtherTransformer );

• Аналогично transform() но принимает только элемент.

Collection(): установить ресурс коллекции для преобразования.

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

 <?php
$ smokescreen -> collection (Post:: all ());
$ smokescreen -> collection (Post:: paginate ());
$ smokescreen -> collection (Post:: paginate (), new SomeOtherTransformer );

• Аналогично transform() , но принимает только коллекцию.

TransformWith(): установите преобразователь для использования с ранее установленным ресурсом.

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

 <?php
$ smokescreen -> transform (Post:: find ( 1 ))
    -> transformWith ( new SomeOtherTransformer );

• Это альтернатива передаче преобразователя непосредственно методам ресурсов.

SerializeWith(): переопределить используемый сериализатор.

 <?php
$ smokescreen -> serializeWith ( new MyCustomSerializer );

• Вам нужно установить это только в том случае, если вы планируете использовать сериализацию, отличную от стандартной.
• Мы предоставляем DefaultSerializer по умолчанию, он возвращает коллекции, вложенные в узел "data" , и ресурс элемента без какой-либо вложенности.
• Ваш собственный сериализатор должен реализовывать интерфейс SerializerInterface .

loadRelationsVia(): переопределить загрузчик отношений Laravel по умолчанию.

$smokescreen->loadRelationsVia(RelationsLoaderInterface $loader);

 <?php
$ smokescreen -> loadRelationsVia ( new MyRelationsLoader );

• Вам нужно установить это только в том случае, если вы планируете использовать другой загрузчик, отличный от загрузчика по умолчанию.
• Мы предоставляем RelationsLoader по умолчанию, который активно загружает связи для ресурсов коллекции.
• Ваш пользовательский загрузчик должен реализовать интерфейс RelationsLoaderInterface и предоставить метод load() .

solveTransformerVia(): переопределить преобразователь преобразователя по умолчанию.

$smokescreen->loadTransformersVia(TransformerResolverInterface $loader);

 <?php
$ smokescreen -> loadTransformersVia ( new MyTransformerResolver );

• Резолвер используется, когда преобразователь явно не определен для ресурса.
• Резолвер по умолчанию в этом пакете пытается найти соответствующий класс преобразователя по пути, определенному в пути smokescreen.transformer_namespace , и создает его экземпляр через контейнер приложения.
• Вам нужно установить это значение только в том случае, если вы планируете использовать преобразователь, отличный от используемого по умолчанию.
• Ваш собственный преобразователь должен реализовать интерфейс TransformersLoaderInterface и предоставить resolve(ResourceInterface) .

response(): доступ к сгенерированному объекту ответа.

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

 <?php
$ smokescreen -> response ()
    -> header ( ' X-Custom-Header ' , ' boo ' )
    -> setStatusCode ( 405 );

• Этот метод возвращает объект IlluminateHttpJsonResponse поэтому его невозможно объединить в цепочку.
• Могут быть применены все поддерживаемые методы JsonResponse .
• Вы по-прежнему можете вернуть response() непосредственно из вашего контроллера, поскольку это объект JsonResponse .
• Альтернативно вы можете использовать withResponse($callback) для применения изменений и при этом поддерживать возможность цепочки.
• Примечание: первый вызов функции response() кэширует результат, поэтому весь набор данных не генерируется заново каждый раз. Это означает, что передача любых параметров при последующих вызовах будет игнорироваться. Вы можете использоватьclearResponse clearResponse() или напрямую манипулировать объектом JsonResponse .

FreshResponse(): создать новый объект Response.

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

• В отличие от response() этот метод возвращает свежий некэшированный объект JsonResponse (сначала вызывая clearResponse() ).
• Этот метод возвращает объект IlluminateHttpJsonResponse поэтому его невозможно объединить в цепочку. См. withResponse() для цепного метода.
• Могут быть применены все поддерживаемые методы JsonResponse .

withResponse(): применить изменения к сгенерированному объекту ответа.

$smokescreen->withResponse(callable $apply);

 <?php
$ smokescreen -> withResponse ( function ( JsonResponse $ response ) {
    $ response -> header ( ' X-Crypto-Alert ' , ' all your coins are worthless! ' );
});

• Предоставьте обратный вызов, который принимает объект JsonResponse и управляет ответом.
• Этот метод можно использовать в цепочке, в отличие от response()

ClearResponse(): очистить любой кэшированный ответ.

$smokescreen->clearResponse();

 <?php
$ smokescreen -> response ();       // Data is generated, response object is built and cached
$ smokescreen -> response ( 500 );    // NOPE - Cached, wont be changed!
$ smokescreen -> clearResponse ();
$ smokescreen -> response ( 500 );    // Response is re-generated

• Сбросить любой кэшированный объект ответа

Трансформеры

Пример трансформатора

 <?php
class PostTransformer extends AbstractTransformer
{
    protected $ includes = [
        ' user ' => ' default|relation:user|method:includeTheDamnUser ' ,
        ' comments ' => ' relation ' ,
    ];

    public function transform ( Post $ post ): array
    {
        return [
            ' id ' => $ post -> id ,
            ' user ' => $ this -> when ( $ post -> user_id , [
                ' id ' => $ post -> user_id ,
            ]),
            ' title ' => $ post -> title ,
            ' summary ' => $ post -> summary ,
            ' body ' => $ post -> body ,
            ' created_at ' => utc_datetime ( $ post -> created_at ),
            ' updated_at ' => utc_datetime ( $ post -> updated_at ),
        ];
    }

    public function includeTheDamnUser ( Post $ post )
    {
        return $ this -> item ( $ post -> user ); // Infer Transformer
    }

    public function includeComments ( Post $ post )
    {
        return $ this -> collection ( $ post -> comments , new CommentTransformer );
    }
}

• Вы объявляете доступные включения через массив $includes .
• Каждый include принимает 0 или более из следующих директив:
  • default : это включение всегда включено независимо от запрошенных включений.
  • relation : указывает, что отношение должно быть быстро загружено. Если имя отношения отличается, укажите его как relation:othername
  • method : по умолчанию ключ включения сопоставлен с include{IncludeKey} вместо этого вы можете указать метод, который будет использоваться.
• Ваш метод transform() должен возвращать массив.
• Определите методы включения в формате include{IncludeKey}(Model) — они должны возвращать либо collection() , либо item()
• when() — это простой вспомогательный метод, который принимает условие и возвращает либо заданное значение, если оно истинно, либо значение null (по умолчанию), если оно ложно. В приведенном выше примере узел "user" будет null если для объекта $post не установлен user_id .

Содействие

Pull-запросы приветствуются. Убедитесь, что код соответствует PSR. Репозиторий на Гитхабе

О

• Автор: Джоди Данлоп
• Лицензия: Массачусетский технологический институт
• Авторские права (c) 2018 г. Rex Software Pty Ltd.