[ Laravel 5.7 文档 ] 进阶系列 —— 扩展包开发

简介

扩展包是添加额外功能到 Laravel 的主要方式。扩展包可以提供任何功能，小到处理日期如 Carbon ，大到整个 BDD 测试框架如 Behat 。

当然，有很多不同类型的扩展包。有些扩展包是独立于 Laravel 的，意味着可以在任何框架中使用，而不仅是 Laravel。比如 Carbon 和 Behat 都是独立的扩展包。所有这些扩展包都可以通过在 composer.json 文件中声明以便被 Laravel 使用。

另一方面，其它非独立扩展包只能和 Laravel 一起使用，这些包可能有特定的路由、控制器、视图和配置用于增强 Laravel 的功能，本文档主要讨论只能在 Laravel 中使用的扩展包。

关于门面的注意点

编写 Laravel 应用时，不管你使用契约还是门面，通常并没有什么关系，因为两者都提供了基本同等级别的可测试性。不过，编写扩展包时，在扩展包里不能访问所有的 Laravel 测试辅助函数。如果你想要像在扩展包中自如编写扩展包测试，就像在Laravel应用中一样，可以使用 Orchestral Testbench 扩展包。

包自动发现

在 Laravel 应用的配置文件 config/app.php 中， providers 配置项定义了一个会被 Laravel 加载的服务提供者列表。当安装完新的扩展包后，在老版本中需要将扩展包的服务提供者添加到这个列表以便被 Laravel 使用。从 Laravel 5.5 开始，我们不必再手动添加服务提供者到该列表，而是将提供者定义到扩展包下 composer.json 文件的 extra 选项中，除了服务提供者之外，我们还可以以这种方式注册门面：

"extra": {
    "laravel": {
        "providers": [
            "Barryvdh\\Debugbar\\ServiceProvider"
        ],
        "aliases": {
            "Debugbar": "Barryvdh\\Debugbar\\Facade"
        }
    }
},

定义好之后，在安装扩展包之后 Laravel 就会自动注册相应的服务提供者和门面，从而为扩展包使用者提供一个更加便捷的安装体验。

选择包发现

如果你是包的使用者并且不想使用包自动发现功能，那么可以像这样在应用 composer.json 文件的 section 选项中列出包名：

"extra": {
    "laravel": {
        "dont-discover": [
            "barryvdh/laravel-debugbar"
        ]
    }
},

你还可以在 dont-discover 配置项中通过通配符 * 禁止所有扩展包的自动发现功能：

"extra": {
    "laravel": {
        "dont-discover": [
            "*"
        ]
    }
},

服务提供者

服务提供者是扩展包和 Laravel 之间的连接纽带。服务提供者负责绑定对象到 Laravel 的服务容器并告知 Laravel 从哪里加载包资源如视图、配置和本地化文件。

服务提供者继承自 Illuminate\Support\ServiceProvider 类并包含两个方法： register 和 boot 。 ServiceProvider 基类位于 Composer 包 illuminate/support 。要了解更多关于服务提供者的内容，查看其文档。

资源

配置

通常，需要发布扩展包配置文件到应用根目录下的 config 目录，这将允许扩展包使用者轻松覆盖默认配置选项，要发布一个配置文件，只需在服务提供者的 boot 方法中使用 publishes 方法即可：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot(){
    $this->publishes([
        __DIR__.'/path/to/config/courier.php' => config_path('courier.php'),
    ]);
}

现在，当扩展包用户执行 Laravel 的 Artisan 命令 vendor:publish 时，你的文件将会被拷贝到指定位置，当然，配置被发布后，可以通过和其它配置选项一样的方式进行访问：

$value = config('courier.option');

注：不要在配置文件中定义闭包，因为当用户执行 Artisan 命令 config:cache 时，闭包将不能被正确序列化。

默认扩展包配置

你还可以选择将自己的扩展包配置文件合并到应用的发布副本，这允许使用者只引入他们在应用配置文件中实际想要覆盖的配置选项。要合并两个配置，在服务提供者的 register 方法中使用 mergeConfigFrom 方法即可：

/**
 * 在容器中注册绑定
 *
 * @return void
 */
public function register(){
    $this->mergeConfigFrom(
        __DIR__.'/path/to/config/courier.php', 'courier'
    );
}

注：这个方法只合并到配置数据第一维度。如果用户定义了多维配置数组，缺失的部分将不能被合并。

路由

如果扩展包包含路由，可以使用 loadRoutesFrom 方法加载它们，这个方法会自动判定应用的路由是否被缓存，如果路由已经被缓存将不会加载路由文件：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot()
{
    $this->loadRoutesFrom(__DIR__.'/routes.php');
}

迁移

如果你的扩展包包含数据库迁移，可以使用 loadMigrationsFrom 方法告知 Laravel 如何加载它们。 loadMigrationsFrom 方法接收扩展包迁移的路径作为其唯一参数：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot()
{
    $this->loadMigrationsFrom(__DIR__.'/path/to/migrations');
}

扩展包迁移注册好之后，会在执行 php artisan migrate 时自动运行。不需要将它们导出到应用的 database/migrations 目录。

翻译

如果你的扩展包包含翻译文件，你可以使用 loadTranslationsFrom 方法告诉 Laravel 如何加载它们，例如，如果你的扩展包命名为 courier ，应该添加如下代码到服务提供者的 boot 方法：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot(){
    $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');
}

扩展包翻译使用形如 package::file.line 的语法进行引用。所以，你可以使用如下方式从 messages 文件中加载 courier 包的 welcome 行：

echo trans('courier::messages.welcome');

发布翻译文件

如果你想要发布扩展包翻译到应用的 resources/lang/vendor 目录，可以使用服务提供者的 publishes 方法，该方法接收一个包路径和相应发布路径数组参数，例如，要发布 courier 扩展包的翻译文件，可以这么做：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot(){
    $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');

    $this->publishes([
        __DIR__.'/path/to/translations' => resource_path('lang/vendor/courier'),
    ]);
}

这样，使用者就可以执行 Artisan 命令 vendor:publish 将扩展包翻译文件发布到应用的指定目录。

视图

要在 Laravel 中注册扩展包视图，需要告诉 Laravel 视图在哪，可以使用服务提供者的 loadViewsFrom 方法来实现。 loadViewsFrom 方法接收两个参数：视图模板的路径和扩展包名称。例如，如果你的扩展包名称是 courier ，添加如下代码到服务提供者的 boot 方法即可：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot(){
    $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');
}

扩展包视图通过使用形如 package::view 的语法来引用。所以，你可以通过如下方式加载 courier 扩展包上的 admin 视图：

Route::get('admin', function () {
    return view('courier::admin');
});

覆盖扩展包视图

当你使用 loadViewsFrom 方法的时候，Laravel 实际上为视图注册了两个存放位置：一个是 resources/views/vendor 目录，另一个是你指定的目录。所以，以 courier 为例：当请求一个扩展包视图时，Laravel 首先检查开发者是否在 resources/views/vendor/courier 提供了自定义版本的视图，如果该视图不存在，Laravel 才会搜索你调用 loadViewsFrom 方法时指定的目录。这种机制使得终端用户可以轻松地自定义/覆盖扩展包视图。

发布视图

如果你想要视图能够发布到应用的 resources/views/vendor 目录，可以使用服务提供者的 publishes 方法。该方法接收包视图路径及其相应的发布路径数组作为参数：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 * @translator laravelacademy.org
 */
public function boot(){
    $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');

    $this->publishes([
        __DIR__.'/path/to/views' => base_path('resources/views/vendor/courier'),
    ]);
}

现在，当使用者执行 Laravel Artisan 命令 vendor:publish 时，扩展包视图将会被拷贝到指定路径。

命令

要通过 Laravel 注册扩展包的 Artisan 命令，可以使用 commands 方法。该方法需要传入命令名称数组，注册号命令后，可以使用Artisan CLI 执行它们：

/**
 * Bootstrap the application services.
 *
 * @return void
 */
public function boot()
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            FooCommand::class,
            BarCommand::class,
        ]);
    }
}

前端资源

你的扩展包可能包含 JavaScript、CSS 和图片，要发布这些前端资源到应用根目录下的 public 目录，可以使用服务提供者的 publishes 方法。在本例中，我们添加一个前端资源组标签 public ，用于发布相关的前端资源组：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot(){
    $this->publishes([
        __DIR__.'/path/to/assets' => public_path('vendor/courier'),
    ], 'public');
}

现在，当使用者执行 vendor:publish 命令时，前端资源将会被拷贝到指定位置，由于需要在每次包更新时覆盖前端资源，可以使用 --force 标识：

php artisan vendor:publish --tag=public --force

发布文件组

有时候你可能想要分开发布扩展包前端资源和业务资源（配置、视图等），例如，你可能想要使用者发布扩展包配置的同时不发布前端资源，这可以通过在扩展包的服务提供者中调用 publishes 方法时给它们打上“标签”来实现。下面我们在扩展包服务提供者的 boot 方法中定义两个发布组：

/**
 * Perform post-registration booting of services.
 *
 * @return void
 */
public function boot(){
    $this->publishes([
        __DIR__.'/../config/package.php' => config_path('package.php')
    ], 'config');

    $this->publishes([
        __DIR__.'/../database/migrations/' => database_path('migrations')
    ], 'migrations');
}

现在，用户可以在使用 Artisan 命令 vendor:publish 时通过引用标签名来分开发布这两个组：

php artisan vendor:publish --tag=config