README

Laravel 的通信层

Transmit 的创建是为了加快实现 REST API 的过程。

安装

通过 Composer

$ composer require NavJobs/Transmit

在您的 config/app.php 中注册服务提供者

'providers' => [
    ...
    NavJobs\Transmit\TransmitServiceProvider::class,
];

该包有一个可发布的配置文件，允许您更改默认序列化器。要发布

php artisan vendor:publish --provider="NavJobs\Transmit\TransmitServiceProvider"

API

Transmit 提供了一个抽象控制器类，您应该从它扩展

use NavJobs\Transmit\Controller as ApiController;

class BookController extends ApiController
{
...

控制器类提供了一些方法，使得 API 响应变得简单

//Return the specified item, transformed
$this->respondWithItem($item, $optionalTransformer);

//Sets the status code to 201 and return the specified item, transformed
$this->respondWithItemCreated($item, $optionalTransformer);

//Return the specified collection, transformed
$this->respondWithCollection($collection, $optionalTransformer);

//Paginate the specified collection
$this->respondWithPaginatedCollection($collection, $optionalTransformer, $perPage = 10);

//Set the status code to 204, and return no content
$this->respondWithNoContent();

还提供了一些错误方法。这些方法返回错误响应并设置状态码

//Sets the status code to 403
$this->errorForbidden($optionalMessage);

//Sets the status code to 500
$this->errorInternalError($optionalMessage);

//Sets the status code to 404
$this->errorNotFound($optionalMessage);

//Sets the status code to 401
$this->errorUnauthorized($optionalMessage);

//Sets the status code to 400
$this->errorWrongArgs($optionalMessage);

控制器还使用 QueryHelperTrait，它有助于将查询字符串参数应用于 Eloquent 模型和查询构建器实例

//Eager loads the specified includes on the model
$this->eagerLoadIncludes($eloquentModel, $includes);

//Applies sort, limit, and offset to the provided query Builder
$this->applyParameters($queryBuilder, $parameters);

转换器

Transmit 提供了一个抽象转换器类，您的转换器应该从它扩展

use NavJobs\LaravelApi\Transformer as BaseTransformer;

class BookTransformer extends BaseTransformer
...

转换器允许您轻松确定哪些关系应该允许预加载。这是通过将请求的包含项与可用和默认包含项匹配来确定的。

//Pass in either an array or csv string
//Returns an array of includes that should be eager loaded
$this->getEagerLoads($requestedIncludes);

实现示例

可以将这些方法组合起来快速创建表达式的 API 控制器。以下是一个实现示例

<?php

namespace App\Book\Http\Books\Controllers;

use Exception;
use Illuminate\Http\Request;
use App\Book\Domain\Books\Entities\Book;
use App\Book\Transformers\BookTransformer;
use App\Book\Http\Books\Requests\BookRequest;
use NavJobs\Transmit\Controller as ApiController;
use Illuminate\Database\Eloquent\ModelNotFoundException;

class BookController extends ApiController
{
    protected $bookModel;
    protected $transformer;
    protected $fractal;

    /**
     * @param Book $bookModel
     * @param BookTransformer $transformer
     */
    public function __construct(Book $bookModel, BookTransformer $transformer)
    {
        parent::__construct();

        $this->transformer = $transformer;
        $this->bookModel = $bookModel;
    }

    /**
     * Show a list of Books.
     *
     * @param Request $request
     * @return mixed
     */
    public function index(Request $request)
    {
        $includes = $this->transformer->getEagerLoads($this->fractal->getRequestedIncludes());
        $books = $this->eagerLoadIncludes($this->bookModel, $includes);
        $books = $this->applyParameters($books, $request->query);

        return $this->respondWithPaginatedCollection($books, $this->transformer);
    }

    /**
     * Show a book by the specified id.
     *
     * @param $bookId
     * @return mixed
     */
    public function show($bookId)
    {
        try {
            $includes = $this->transformer->getEagerLoads($this->fractal->getRequestedIncludes());
            $books = $this->eagerLoadIncludes($this->bookModel, $includes);

            $book = $books->findOrFail($bookId);
        } catch (ModelNotFoundException $e) {
            return $this->errorNotFound();
        }

        return $this->respondWithItem($book, $this->transformer);
    }

    /**
     * Handle the request to persist a Book.
     *
     * @param bookRequest $request
     * @return array
     */
    public function store(BookRequest $request)
    {
        $book = $this->bookModel->create($request->all());

        return $this->respondWithItemCreated($book, $this->transformer);
    }


    /**
     * Handle the request to update a Book.
     *
     * @param BookRequest $request
     * @param $bookId
     * @return mixed
     */
    public function update(BookRequest $request, $bookId)
    {
        try {
            $book = $this->bookModel->findOrFail($bookId);
        } catch (ModelNotFoundException $e) {
            return $this->errorNotFound();
        }

        $book->update($request->all());

        return $this->respondWithNoContent();
    }

    /**
     * Handle the request to delete a Book.
     *
     * @param $bookId
     * @return mixed
     */
    public function destroy($bookId)
    {
        try {
            $book = $this->bookModel->findOrFail($bookId);
        } catch (ModelNotFoundException $e) {
            return $this->errorNotFound();
        }

        try {
            $book->delete();
        } catch (Exception $e) {
            return $this->errorInternalError();
        }

        return $this->respondWithNoContent();
    }
}

使用

此实现允许端点接受包含项以及查询字符串参数。要将参数应用于当前资源

http://www.example.com/books?limit=5&sort=name,-created_at

包含项如下所示

http://www.example.com/books?include=authors,publisher

包含项也可以通过查询参数进行排序，URL 格式如下

http://www.example.com/books?include=authors:sort(name|-created_at),publisher

Fractal

Transmit 是建立在两个出色的 PHP 包之上的。

• fractal
• laravel-fractal.

控制器通过以下方式提供 laravel-fractal 的实例

$this->fractal;

可以通过此实例直接访问 laravel-fractal 中的任何方法。任何在实例上调用未知方法都会传递到 fractal 管理器类。请参阅这些包的文档以获取更多功能。

测试

$ composer test

致谢

• 非凡包联盟
• Spatie

许可

MIT 许可证 (MIT)。有关更多信息，请参阅 许可文件。