README

Laravel的一次性操作

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

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

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

如果您...

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

安装

使用composer安装此包

composer require timokoerber/laravel-one-time-operations

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

php artisan migrate

现在您已经准备好了！

命令

创建操作文件

创建新的操作文件

php artisan operations:make <operation_name>

创建没有属性的文件

php artisan operations:make <operation_name> -e|--essential

处理操作

处理所有新的操作文件

php artisan operations:process

强制同步执行

php artisan operations:process --sync

强制异步执行

php artisan operations:process --async

测试模式（不要标记操作为已处理）

php artisan operations:process --test

运行独立的命令

php artisan operations:process --isolated

强制特定队列的作业

php artisan operations:process --queue=<name>

仅处理具有特定标签的操作

php artisan operations:process --tag=<tagname>

重新运行特定的操作

php artisan operations:process <operation_name>

显示操作

显示所有操作

php artisan operations:show

显示挂起的操作

php artisan operations:show pending

显示已处理操作

php artisan operations:show processed

显示已丢弃操作

php artisan operations:show disposed

使用多个过滤器显示操作

php artisan operations:show pending processed disposed

教程

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表中找到所有处理过的操作。

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

同步或异步分发作业

对于每个操作，将根据操作文件中的$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 Isolatable Commands）。

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

“Laravel的一次性操作”是开源软件，根据MIT许可证授权。