README

一个库，可轻松通过JSON Rest API处理BREAD（浏览、读取、编辑、添加、删除）操作。定义模型定义、执行验证并提供默认控制器路由。

此包使用了来自https://github.com/jesperbjerke/laravel-api-query-builder的API查询构建器。

安装

composer require bjerke/laravel-bread

配置

没有太多配置项，但可以配置用于您的模型（在控制器中尝试查找模型时使用）的命名空间。它预先配置为使用\App\Models\。如果您不需要更改任何默认配置选项，则不需要发布此配置。

但是，如果您想更改默认命名空间，则需要发布此库的配置文件，以便您可以在自己的应用程序中更改它。为此，请运行以下Artisan命令

php artisan vendor:publish --provider="Bjerke\Bread\BreadServiceProvider"

现在您将在/config中有一个bread.php配置文件，您可以在此处更改配置值。

其他配置项包括所有模型可用的默认字段组以及一些与TUS上传相关的选项。

用法

要开始使用此包，您需要创建自己的控制器类，名称以单数形式命名，与受影响的模型匹配。例如，UserController将自动查找User模型。如果您不遵循此模式，可以在控制器上定义$modelName属性。

从此包扩展BreadController。然后在您的模型中，使用QueryBuilderModelTrait和BreadModelTrait。

最后，在您的路由器中定义API端点。

Route::get('definition', [UserController::class, 'definition']); // Fetch model field definitions

Route::get('', [UserController::class, 'index']); // Query multiple users, uses ApiQueryBuilder
Route::post('', [UserController::class, 'create']); // Create new user
Route::get('{id}', [UserController::class, 'view']); // Fetch single user
Route::patch('{id}', [UserController::class, 'update']); // Update user
Route::delete('{id}', [UserController::class, 'delete']); // Delete user
Route::delete('{id}/detach/{relatedModel}', [UserController::class, 'detach']); // Attach an existing model to be related to user
Route::put('{id}/attach/{relatedModel}', [UserController::class, 'attach']); // Detach an existing related model from user

// If you want to use TUS uploads add this route
Route::any('tus/{chunkId?}', [UserController::class, 'tus']); // Handle TUS uploads

请记住，只定义您实际想要使用的端点，并设置适当的身份验证和授权规则。

如果您想要提供字段定义和自动验证等，则需要使用FieldDefinition属性并在您的模型上定义字段。

class User
{
    use FieldDefinition;
    use QueryBuilderModelTrait;
    use BreadModelTrait;

    protected function define(DefinitionBuilder $definition): DefinitionBuilder
    {
        $definition->addFields([
            (new TextField('first_name'))->label(Lang::get('fields.first_name'))->required(true),

            (new TextField('last_name'))->label(Lang::get('fields.last_name'))->required(true),

            (new EmailField('email'))
                ->label(Lang::get('fields.email'))
                ->required(true)
                ->addValidation('unique:users,email' . (($this->exists) ? (',' . $this->id) : ''))
        ]);
        return $definition;
    }
}

上面的定义与路由结合，允许您将以下内容发送到/users以创建新用户

{
  "data" : {
    "first_name" : "John",
    "last_name" : "Doe",
    "email" : "john.doe@test.com"
  }
}

注意，您发送的数据应在data属性内。

有关可用的字段类型及其工作方式的更多信息，请参阅src/Traits/FieldDefinition.php中每个字段的docblock。

在BREAD控制器端点中修改查询

您可以在查询构建器中挂钩并为您从数据库中获取数据的端点添加自己的规则。

示例

class ProductController extends BreadController
{
    public function index(Request $request, $applyQuery = null)
    {
        return parent::index($request, static function (Builder $query) {
            $query->where('distributor_id', \Auth::user()->distributor_id);
        });
    }
}

在更新/删除/附加/分离之前/之后运行逻辑

breadcontroller提供了挂钩，允许您在实际保存之前运行自定义逻辑。如果您想停止执行，则抛出适当的异常。通过在控制器中实现端点方法并将闭包传递给父方法来使用挂钩。这适用于所有端点方法。

示例

class ProductController extends BreadController
{
    public function update(Request $request, $id, $with = [], $applyQuery = null, $beforeSave = null)
    {
        /* @var Product $product */
        $product = parent::update($request, $id, $with, $applyQuery, static function (Product $product) {
            // Set a custom property on the model before saving
            $product->last_updated_by = \Auth::id();
        });

        return $product;
    }
}

保存文件/图片

为了使用内置的存储文件和/或图片的功能，此包需要安装并配置https://github.com/spatie/laravel-medialibrary。

添加文件/图片

{
  "data" : {
    "files" : [{
      "base64" : "base64 encoded string representation of the image/file",
      "name" : "Filename",
      "add" : true
    }]
  }
}

删除文件/图片

{
  "data" : {
    "files" : [{
      "id" : 1,
      "remove" : true
    }]
  }
}

TUS上传

存在内置功能以支持使用TUS协议进行上传。要启用TUS上传，您需要安装https://github.com/ankitpokhrel/tus-php包以及上面指定的媒体库包。

您可以使用类似于https://github.com/tus/tus-js-client或https://uppy.io/的TUS客户端。

在提交文件时，您发送从TUS服务器收到的唯一上传密钥（一个UUID4字符串），而不是base64。请注意，预期文件已经通过TUS上传并且存在于服务器上，在发送此请求之前。

{
  "data" : {
    "files" : [{
      "tusKey" : "002f12d4-6949-4266-af06-675f653c0bdc",
      "name" : "Filename",
      "add" : true
    }]
  }
}

清理孤儿TUS文件

将$schedule->command('bread:clean-tus --force')->daily()添加到您的调度器中，以自动清理孤儿/中止的文件。

bjerke / laravel-bread

维护者

详细信息