README

一个简单的 API 服务，用于支持 FilamentPHP

安装

您可以通过 composer 安装此包

composer require rupadana/filament-api-service

将其注册到您的 filament 提供程序

use Rupadana\ApiService\ApiServicePlugin;

$panel->plugins([
    ApiServicePlugin::make()
])

配置

php artisan vendor:publish --tag=api-service-config

return [
    'navigation' => [
        'token' => [
            'cluster' => null,
            'group' => 'User',
            'sort' => -1,
            'icon' => 'heroicon-o-key'
        ]
    ],
    'models' => [
        'token' => [
            'enable_policy' => true,
        ],
    ],
    'route' => [
        'panel_prefix' => true,
        'use_resource_middlewares' => false,
    ],
    'tenancy' => [
        'enabled' => false,
        'awareness' => false,
    ]
];

用法

php artisan make:filament-api-service BlogResource

从版本 3.0 开始，路由会自动注册。它们将按 '/api/admin' 分组。 admin 是面板 ID。要禁用面板 ID 前缀，请将 route.panel_prefix 设置为 false

因此，您无需手动注册路由。

路由将是

在 CreateHandler 中，您需要创建自己的自定义请求验证。

令牌资源

默认情况下，令牌资源只显示在 super_admin 角色。您也可以将权限修改为其他权限。

令牌资源受 TokenPolicy 保护。您可以通过发布配置并更改此行来禁用它。

'models' => [
        'token' => [
            'enable_policy' => false // default: true
        ]
    ],

重要

如果您使用 Laravel 11，不要忘记运行 php artisan install:api 发布个人访问令牌迁移，然后运行 php artisan migrate 迁移迁移，但默认情况下，如果您运行 php artisan install:api，它将提示您迁移迁移。

过滤 & 允许字段

我们使用了 "spatie/laravel-query-builder": "^5.3" 来处理查询选择、排序和过滤。有关更多信息，请参阅 spatie/laravel-query-builder 文档。

为了允许修改模型查询，您可以在模型中实现 HasAllowedFields、HasAllowedSorts 和 HasAllowedFilters 接口。

class User extends Model implements HasAllowedFields, HasAllowedSorts, HasAllowedFilters {
    // Which fields can be selected from the database through the query string
    public function getAllowedFields(): array
    {
        // Your implementation here
    }

    // Which fields can be used to sort the results through the query string
    public function getAllowedSorts(): array
    {
        // Your implementation here
    }

    // Which fields can be used to filter the results through the query string
    public function getAllowedFilters(): array
    {
        // Your implementation here
    }
}

创建处理器

要创建处理器，您可以使用此命令。默认情况下，我使用 CreateHandler

php artisan make:filament-api-handler BlogResource

或

php artisan make:filament-api-handler Blog

转换 API 响应

php artisan make:filament-api-transformer Blog

它将在 App\Filament\Resources\BlogResource\Api\Transformers 中创建 BlogTransformer

<?php
namespace App\Filament\Resources\BlogResource\Api\Transformers;

use Illuminate\Http\Resources\Json\JsonResource;

class BlogTransformer extends JsonResource
{

    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return $this->resource->toArray();

        // or

        return md5(json_encode($this->resource->toArray()));
    }
}

下一步，您需要编辑并将其添加到您的资源中

    use App\Filament\Resources\BlogResource\Api\Transformers\BlogTransformer;

    class BlogResource extends Resource
    {
        ...
        public static function getApiTransformer()
        {
            return BlogTransformer::class;
        }
        ...
    }

分组名称 & 前缀

您可以编辑前缀和分组路由名称，默认情况下此插件使用模型的单数标签；

    class BlogApiService extends ApiService
    {
        ...
        protected static string | null $groupRouteName = 'myblog';
        ...
    }

中间件

您可以在两个特定位置添加或覆盖中间件。通过 Filament 面板提供程序和/或通过 Resources $routeMiddleware。

如果您将 route.use_resource_middlewares 设置为 true，则该包将为该特定资源注册中间件，如

class BlogResource extends Resource
    {
        ...
        protected static string | array $routeMiddleware = []; // <-- your specific resource middlewares
        ...
    }

然后您的 API 资源端点将首先通过这些中间件。

添加/覆盖中间件的另一种方法是通过对您的面板提供程序中插件的初始化添加 middleware() 方法

use Rupadana\ApiService\ApiServicePlugin;

$panel->plugins([
    ApiServicePlugin::make()
        ->middleware([
        // ... add your middlewares
        ])
])

租户

当您想在此包上启用租户时，可以通过将配置 tenancy.enabled 设置为 true 来启用此功能。这确保您的 API 响仅检索用户可以访问的数据。因此，如果您已配置了 5 个租户，并且用户可以访问 2 个租户。然后启用此功能将仅返回这 2 个租户的数据。

如果您已在此包上启用了租户，但在特定资源中已定义 protected static bool $isScopedToTenant = false;，则 API 将为此特定资源遵守此设置并返回所有记录。

如果您想使 API 路由租户感知，您可以在发布的 api-service.php 中将 tenancy.awareness 设置为 true。这样，此包将注册额外的 API 路由，这些路由将仅在 API 响应中返回特定租户的数据。

现在，当 tenancy.awareness 设置为 true 时，您的 API 端点将具有 {tenant} 的 URI 前缀。

它看起来是这样的：

  POST      api/admin/{tenant}/blog
  GET|HEAD  api/admin/{tenant}/blog
  PUT       api/admin/{tenant}/blog/{id}
  DELETE    api/admin/{tenant}/blog/{id}
  GET|HEAD  api/admin/{tenant}/blog/{id}

通过在处理器中添加此属性来覆盖租户所有权关系名称：protected static ?string $tenantOwnershipRelationshipName = null;

如何确保其安全性？

从版本 3.0 开始，它将自动检测路由并使用 sanctum 进行保护。

要生成令牌，您只需从管理面板创建它。它将成为令牌资源。

公开 API

通过在您的 API 处理器上覆盖此属性来将 API 设置为公开。假设我们有一个 PaginationHandler

class PaginationHandler extends Handlers {
    public static bool $public = true;
}

许可证

MIT 许可证 (MIT)。

支持者