README

通过维护API版本来管理资源。使用简单的中间件根据API版本分离路由，并根据此版本智能实例化Http\Resources。

在您的api/v2组上添加中间件 'api.v:2'。

然后 api_resource('App\User')->make($user) 与 new App\Http\Resources\App\v2\User($user) 相同，但无需指定版本。

App\Http\Resources\
  |- App\
    |- v1\
      |- User.php
    |- v2\
      |- Rank.php
      |- User.php

安装

您可以通过composer使用以下命令安装此包

composer require adelynx/laravel-api-resources

该包将自动注册自己。

配置

要发布配置文件到 config/api.php，请运行

php artisan vendor:publish --provider="Adelynx\APIResources\APIResourcesServiceProvider"

这将发布一个包含以下内容的文件 api.php 到您的配置目录中

return [
  /*
  |--------------------------------------------------------------------------
  | API Version
  |--------------------------------------------------------------------------
  |
  | This value is the latest version of your api. This is used when
  | there's no specified version on the routes, so it will take this as the
  | default, or latest.
   */
   'version' => '1',

   /*
   |--------------------------------------------------------------------------
   | Resources home path
   |--------------------------------------------------------------------------
   |
   | This value is the base folder where your resources are stored.
   | When using multiple APIs, you can leave it as a string if every
   | api is in the same folder, or as an array with the APIs as keys.
    */
    'resources_path' => 'App\Http\Resources',
    
    /*
    |--------------------------------------------------------------------------
    | Resources
    |--------------------------------------------------------------------------
    |
    | Here is the folder that has versioned resources. If you store them
    | in the root of 'resources_path', leave this empty or null.
     */
    'resources' => 'App'
 ];

中间件

在您的 Http/Kernel.php 下的 $routeMiddleware 中安装此中间件

  protected $routeMiddleware = [
    ...
    'api.v'           => \Adelynx\APIResources\Middleware\APIversion::class,
    ...
  ];

正确配置

为此包正常工作，您需要了解它如何请求资源。

如果我们有以下配置

[
  'version' => '2',
  'resources_path' => 'App\Http\Resources',
  'resources' => 'Api'
]

这意味着如果您包含 Api\User 资源，它将实例化 App\Http\Resources\Api\v2\User。

Api 适用于对结构进行子组织，但您可以将版本化的资源文件夹放在根目录中，如下所示

[
  'version' => '2',
  'resources_path' => 'App\Http\Resources',
  'resources' => ''
]

现在如果我们包含 User，它将实例化 App\Http\Resources\v2\User。

回退

当您使用一个不是最新版本的版本时，如果您尝试包含在该版本目录内未定义的资源，这将自动回退到最新的版本。

这样您就不必在先前版本中重复创建新资源。

用法

中间件

当您分组API路由时，现在应在分组中应用中间件 api.v，如下所示

// App v1 API
Route::group([
    'middleware' => ['app', 'api.v:1'],
    'prefix'     => 'api/v1',
], function ($router) {
    require base_path('routes/app_api.v1.php');
});

// App v2 API
Route::group([
    'middleware' => ['app', 'api.v:2'],
    'prefix'     => 'api/v2',
], function ($router) {
    require base_path('routes/app_api.v2.php');
});

这样，如果您使用外观，您可以通过执行 APIResource::getVersion() 来检查当前版本，并将返回中间件上指定的版本。

外观

有多种创建资源的方法。您可以使用外观访问器

use Adelynx\APIResources\Facades\APIResource;

class SomethingController extends Controller {
    ...

    public function show(Something $model)
    {
      return APIResource::resolve('App\Something')->make($model);
    }
}

全局助手

class SomethingController extends Controller {
    ...

    public function show(Something $model)
    {
      return api_resource('App\Something')->make($model);
    }
}

集合

与 make 相反，对于数组，使用 collection，就像Laravel文档中那样。

class SomethingController extends Controller {
    ...

    public function index()
    {
      $models = Something::all();
      return api_resource('App\Something')->collection($models);
    }
}

嵌套资源

为了利用回退功能，建议在资源内部使用 api_resource。这样，您可以保留正确的版本，如果没有定义，则为最新版本。

class Post extends Resource {
    public function toArray($request)
    {
      return [
        'title' => $this->title,
          ...
        'user' => api_resource('App\User')->make($this->user);
      ];
    }
}

多个API

可能存在这种情况，即同一个项目中有多个API存在，但使用不同的版本。此应用程序支持这一点。首先，是 config/api.php

return [
  'default' => 'api',
  'version' => [
    'api'     => '2',
    'desktop' => '3'
  ],
  'resources_path' => 'App\Http\Resources'
  // Or one path each
  'resources_path' => [
    'api'     => 'App\Http\Resources',
    'desktop' => 'Vendorname\ExternalPackage\Resources'
  ],
  'resources' => [
    'api'     => 'Api',
    'desktop' => ''
  ],
];

然后，您需要配置 中间件。与使用 api.v:1 相反，您现在必须指定名称：api.v:3,desktop。

然后其余部分按照之前所述进行。

测试

使用以下命令运行测试

vendor/bin/phpunit

致谢

许可协议

MIT许可协议（MIT）。请参阅许可文件以获取更多信息。

adelynx / laravel-api-resources

维护者

详细信息