README

Laravel的一次性操作

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

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

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

如果您...

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

安装

使用composer安装此包

composer require timokoerber/laravel-one-time-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="TimoKoerber\LaravelOneTimeOperations\Providers\OneTimeOperationsServiceProvider"

这将创建一个包含以下内容的 config/one-time-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 TimoKoerber\LaravelOneTimeOperations\OneTimeOperation;

return new class extends OneTimeOperation
{
    /**
     * 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 作业异步处理（基于您的配置）。默认情况下，操作被调度到项目的 default 队列。根据需要更改 $queue。

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

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

创建更简洁的操作文件

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

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

自定义操作文件

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

处理操作

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

php artisan operations:process

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

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

同步或异步调度任务

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

通过在 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

许可证

版权所有 © Timo Körber | www.timokoerber.com

"One-Time Operations for Laravel" 是开源软件，根据 MIT 许可证 许可。