README

概述

一个Laravel包，简化了在安装或更新Web应用程序时运行代码和命令。

安装

需求

该包已开发和测试，以与以下最低要求兼容

PHP 7.2
Laravel 6

安装包

您可以通过Composer安装此包

composer require ashallendesign/laravel-executor

使用方法

创建执行器

创建新的执行器

要创建新的执行器，您可以使用以下命令

php artisan make:executor YourExecutorNameHere

上述命令将创建一个名为YourExecutorNameHere的执行器，该执行器位于app/Executor文件夹中。

使用命令创建执行器

通常，执行器预期在控制台中运行。因此，当创建新的执行器时，如果您打算在控制台中运行它，您可以使用以下命令

php artisan make:executor YourExecutorNameHere -c

上述命令将为您的新执行器创建与创建新的执行器中相同的模板。但是，它将在您的app/Commands文件夹中创建一个名为RunYourExecutorNameHereExecutor的新命令。这意味着您不需要手动创建新命令来运行您的执行器。

在通过控制台运行中了解更多信息，以了解如何在命令中运行执行器。

更新执行器

添加Artisan命令

要通过您的执行器类运行Artisan命令，您可以将runArtisan()方法添加到您的执行器的run()方法中。以下代码示例展示了如何设置执行器来运行内置的Laravel php artisan cache:clear命令

<?php

namespace App\Executor;

use AshAllenDesign\LaravelExecutor\Classes\Executor;

class AppUpdate extends Executor
{
    public function run(): Executor
    {
        return $this->runArtisan('cache:clear');
    }
}

在某些情况下，您可能需要运行需要您输入的命令。例如，您可能有一个创建数据库中新用户的命令，需要您输入一些详细信息。在这种情况下，您可以将true作为->runArtisan()方法的第二个参数传递，指定它是一个交互式命令。

要确定命令的进程超时时间，您还可以将秒数作为->runArtisan()方法的第三个参数传递。

添加命令

要使用您的执行器类运行命令（无法使用Artisan运行），您可以将runExternal()方法添加到您的执行器的run()方法中。以下代码示例展示了如何设置执行器来运行内置的Composer composer install命令

<?php

namespace App\Executor;

use AshAllenDesign\LaravelExecutor\Classes\Executor;

class AppUpdate extends Executor
{
    public function run(): Executor
    {
        return $this->runExternal('composer install');
    }
}

在某些情况下，您可能需要运行需要您输入的命令。例如，您可能有一个创建数据库中新用户的命令，需要您输入一些详细信息。在这种情况下，您可以将true作为->runExternal()方法的第二个参数传递，指定它是一个交互式命令。

要确定命令的进程超时时间，您还可以将秒数作为->runExternal()方法的第三个参数传递。

添加闭包

有时你可能需要运行一些无法适应现有命令的代码。在这种情况下，你可以向你的Executor添加一个闭包。以下示例展示了如何向你的Executor类传递一个简单的闭包。

<?php

namespace App\Executor;

use AshAllenDesign\LaravelExecutor\Classes\Executor;

class AppUpdate extends Executor
{
    public function run(): Executor
    {
        return $this->runClosure(function () {
            return 'I am running inside a closure.';
        });
    }
}

添加桌面通知

如果你通过控制台运行Executor，你可能在某些步骤之间想显示桌面通知。要显示桌面通知，你可以使用->simpleDesktopNotification()或->desktopNotification()。

使用->simpleDesktopNotification()，你可以传递一个标题和应显示的正文。以下示例展示了如何创建一个简单的桌面通知。

<?php

namespace App\Executor;

use AshAllenDesign\LaravelExecutor\Classes\Executor;

class AppUpdate extends Executor
{
    public function run(): Executor
    {
        return $this->simpleDesktopNotification('Notification title', 'Notification body');
    }
}

如果你想自定义通知，可以使用->desktopNotification()并将一个Joli\JoliNotif\Notification对象作为参数传递。有关构建此类通知的更多信息，请参阅Joli\JoliNotif文档。

你还可以向Executor添加->completeNotification()，以便在类内所有代码运行完成后显示桌面通知。

ping URL

如果你使用Executor在实时服务器上更新应用程序，你可能希望在完成后ping一个URL。这可以用于发送webhook以提醒脚本已成功运行。要ping一个URL，你可以简单地使用->ping()方法。

以下示例展示了如何ping一个网站。

<?php

namespace App\Executor;

use AshAllenDesign\LaravelExecutor\Classes\Executor;

class AppUpdate extends Executor
{
    public function run(): Executor
    {
        return $this->ping('https://ashallendesign.co.uk/executor-webhook-route');
    }
}

如果你想在ping()中发送头信息，可以将它们作为第二个参数传递。这对于你想在webhook请求中添加签名以确认它们来自授权发送者非常有用。

以下示例展示了如何带有头信息的ping一个网站。

<?php

namespace App\Executor;

use AshAllenDesign\LaravelExecutor\Classes\Executor;

class AppUpdate extends Executor
{
    public function run(): Executor
    {
        return $this->ping('https://ashallendesign.co.uk/executor-webhook-route', [
            'X-Webhook-Signature' => 'secret-signature-to-go-here'
        ]);
    }
}

运行执行器

通过控制台运行

如上所述，Executors主要设计为从控制台运行。这使得它们非常适合添加到部署脚本中，例如可以在Laravel Forge和Runcloud中找到的脚本。

如果你同时创建了一个命令和Executor类，使用了创建带有命令的Executor中找到的命令，你的命令已经分配了一个签名。签名是通过将Executor的类名转换为短横线命名法来创建的。例如，名为AppInstall的Executor将获得命令签名executor:app-install。

以下示例展示了如何运行（未修改的）命令的AppInstall Executor。

php artisan executor:app-install

注意：要将命令注册到Laravel应用程序中，你需要在app/Console/Kernel.php文件中将命令类名添加到$commands数组中。

手动运行

有时你可能希望在命令行之外运行Executor类。为此，你只需在类上调用->run()方法。以下示例展示了如何手动运行名为AppInstall的Executor。

<?php

namespace App\Http\Controllers;

use App\Executor\AppInstall;

class Controller
{
    public function index()
    {
        (new AppInstall())->run();
    }
}

示例

以下示例展示了如何创建一个Executor类，该类可以在从远程仓库拉取项目的新分支后运行。

<?php

namespace App\Executor;

use AshAllenDesign\LaravelExecutor\Classes\Executor;

class AppUpdate extends Executor
{
    public function run(): Executor
    {
        return $this->simpleDesktopNotification('Starting Executor', 'Starting the AppUpdate Executor.')
                    ->runExternal('composer install')
                    ->runArtisan('migrate')
                    ->runArtisan('cache:clear')
                    ->completeNotification();
    }
}

假设上述Executor类仍然使用默认的命令签名，每次拉取分支时，都可以运行以下命令：php artisan executor:app-update。

以下图像展示了如何运行一个简单的Executor命令。它只执行composer du -o，但展示了Laravel Executor如何提供实时输出和桌面通知。

安全性

如果你发现任何安全问题，请直接通过mail@ashallendesign.co.uk联系我报告。

贡献

如果你希望对包进行任何更改或改进，请随时提交一个pull request。

注意：即将添加贡献指南。

鸣谢

变更日志

查看变更日志以获取有关最新更改的更多信息。

许可证

MIT许可（MIT）。有关更多信息，请参阅许可文件。

ashallendesign / laravel-executor

维护者

详细信息