README

Laravel Operations

部署后运行一次操作 - 就像您运行迁移一样！

使用Laravel的单次操作将您的CI/CD提升到下一个层次！🚀

创建用于一次性使用的特定类，这些类可以在每次部署后自动执行。与迁移相同，它们只处理一次然后不再处理。非常适合在数据库更改或功能更新后立即播种或更新某些数据。

如果您...

• 经常需要在部署新代码后更新特定数据
• 您经常在部署后仅执行一次作业
• 有时您会忘记执行那个特定的作业，然后事情变得一团糟
• 您的代码中充满了不再使用的作业
• 您的同事总是需要被提醒在数据库更改后执行那个特定的作业
• 您经常在迁移文件中播种或处理数据（这绝对是大忌！）

安装

使用Composer安装此包

composer require encoredigitalgroup/laravel-operations

在您的数据库中创建所需的表

php artisan migrate

现在您已经准备好了！

命令

创建操作文件

php artisan operations:make <operation_name>                // create new operation file
php artisan operations:make <operation_name> -e|--essential // create file without any attributes

处理操作

php artisan operations:process                   // process all new operation files

php artisan operations:process --sync            // force synchronous execution
php artisan operations:process --async           // force asynchronous execution
php artisan operations:process --test            // dont flag operations as processed
php artisan operations:process --isolated        // run command isolated

php artisan operations:process --queue=<name>    // force queue, that the job will be dispatched to
php artisan operations:process --tag=<tagname>   // only process operations, that have the given tag

php artisan operations:process <operation_name>  // re-run one specific operation

显示操作

php artisan operations:show            // show all operations
php artisan operations:show pending    // show pending operations
php artisan operations:show processed  // show processed operations
php artisan operations:show disposed   // show disposed operations

php artisan operations:show pending processed disposed  // use multiple filters

教程

CI/CD & 部署流程

单次操作的工作方式与Laravel迁移完全相同。只需在代码部署和迁移迁移之后处理操作。您可以将其作为部署脚本的组成部分，如下所示

...
 - php artisan migrate
 - php artisan operations:process
...

编辑配置

默认情况下，以下元素将在您的项目中创建

• 数据库中的operations表
• 项目根目录中的operations目录

如果您想使用不同的设置，请发布并编辑配置文件

php artisan vendor:publish --provider="EncoreDigitalGroup\LaravelOperations\Providers\LaravelOperationsServiceProvider"

这将创建包含以下内容的config/operations.php文件。

// config/one-time-operation.php

return [
    'directory' => 'operations',
    'table' => 'operations',
];

按需进行更改。

创建单次操作文件

要创建新的操作文件，请执行以下命令

php artisan operations:make AwesomeOperation

这将创建一个类似于operations/XXXX_XX_XX_XXXXXX_awesome_operation.php的文件，并包含以下内容。

<?php
// operations/XXXX_XX_XX_XXXXXX_awesome_operation.php

use EncoreDigitalGroup\LaravelOperations\LaravelOperation;

return new class extends LaravelOperation
{
    /**
     * Determine if the operation is being processed asynchronously.
     */
    protected bool $async = true;

    /**
     * The queue that the job will be dispatched to.
     */
    protected string $queue = 'default';

    /**
     * A tag name, that this operation can be filtered by.
     */
    protected ?string $tag = null;

    /**
     * Process the operation.
     */
    public function process(): void
    {
        //
    }
};

在process()方法中提供您的代码，例如

// operations/XXXX_XX_XX_XXXXXX_awesome_operation.php

public function process(): void
{
    User::where('active', 1)->update(['status' => 'awesome']) // make active users awesome
}

默认情况下，操作通过派发作业OneTimeOperationProcessJob以异步方式（基于您的配置）处理。默认情况下，操作将被派发到项目默认队列。根据您的需要更改$queue。

您还可以通过将$async标志设置为false来同步执行代码。（这仅适用于小型操作，因为这些操作的处理应作为部署过程的一部分）

提示：如果您使用同步处理，则将忽略$queue属性。

创建更简洁的操作文件

如果您不需要为您的操作使用所有可用属性，您可以使用--essential或-e选项创建一个更简洁的操作文件

php artisan operations:make AwesomeOperation --essential
php artisan operations:make AwesomeOperation -e

自定义操作文件

您可以在/stubs/one-time-operation.stub中提供自定义类布局，这将用于创建新的操作文件。

处理操作

使用以下调用处理所有新的操作文件。

php artisan operations:process

您的代码将被执行，您将在 operations 表中找到所有已处理的操作。

之后，此操作将不再被处理。

同步或异步调度任务

对于每个操作，将根据操作文件中的 $async 属性使用 dispatch() 或 dispatchSync() 来调度 OneTimeOperationProcessJob。

通过在 operations:process 命令中提供 --sync 或 --async 选项，您可以强制同步/异步执行并忽略属性。

php artisan operations:process --async  // force dispatch()
php artisan operations:process --sync   // force dispatchSync()

提示！ 如果 operation:process 是您部署过程的一部分，不推荐 同步处理操作，因为操作中的错误可能导致整个部署失败。

为所有操作强制不同的队列

您可以在 artisan 调用中提供 --queue 选项。给定的队列将用于所有操作，忽略类中的 $queue 属性。

php artisan operations:process --queue=redis  // force redis queue

在多服务器架构上独立运行命令

如果您在使用多服务器架构，可以使用 --isolated 选项来确保只运行一个命令实例（Laravel 可隔离命令）。

php artisan operations:process --isolated

仅运行具有给定标签的操作

您可以在操作文件中提供 $tag 属性。

<?php
// operations/XXXX_XX_XX_XXXXXX_awesome_operation.php

    protected ?string $tag = "awesome";
};

这样，在处理操作时就可以过滤具有此特定标签的操作

php artisan operations:process --tag=awesome  // run only operations with "awesome" tag

这在例如，您想在迁移前后处理一些操作时非常有用。

 - php artisan operations:process --tag=before-migrations
 - php artisan migrate
 - php artisan operations:process

您也可以提供多个标签

php artisan operations:process --tag=awesome --tag=foobar // run only operations with "awesome" or "foobar" tag

提示！ operations:process（不带标签）仍然处理所有操作，即使它们有标签。

重新运行操作

如果出现错误（或者您只是想这么做），您可以再次处理操作，通过在 operations:process 中提供 操作的名称 作为参数。

php artisan operations:process XXXX_XX_XX_XXXXXX_awesome_operation

测试操作

在将操作标记为“已处理”之前，您可能想多次测试您的代码。提供 --test 标志可以反复运行命令。

php artisan operations:process --test

显示所有操作

因此，您不必检查数据库或目录来查找现有操作，您可以使用 operations:show 显示列表。使用可用的筛选器 pending、processed 和 disposed 过滤列表。

• pending - 尚未处理的操作
• processed - 已处理的操作
• disposed - 已处理且文件已被删除的操作

php artisan operations:show pending           // show only pending operations
php artisan operations:show pending disposed  // show only pending and disposed operations

删除操作

此包的整个想法是，一旦执行了操作，就可以将其丢弃，这样您的项目就不会因不再使用的文件和代码而变得杂乱。

因此，您只需从您的存储库中删除文件。

当您调用 operations:show 时，已删除的操作将显示为 DISPOSED，这样您仍然对所有已处理的操作有历史记录。

测试

composer test

许可证

"Laravel Operations" 是开源软件，使用 MIT 许可证 许可。

对代码库的贡献受 Encore Digital Group 贡献条款 管辖。

注意：这是 timokoerber/laravel-one-time-operations 的分支。