[ Laravel 5.3 文档 ] 附录 —— 包开发

1、简介

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

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

另一方面,其它包只能特定和 Laravel 一起使用,这些包可能有路由,控制器、视图配置用于加强 Laravel 应用的功能,本章主要讨论只能在 Laravel 中使用的包。

关于门面的注意点

编写Laravel应用时,不管你使用契约还是门面,通常并没有什么关系,因为两者都提供了基本同等级别的可测试性。不过,编写扩展包时,最好使用契约而不是门面,由于你的扩展包不能访问所有的Laravel测试辅助函数,所以模拟或存根契约往往比模拟门面来得更容易些。

2、服务提供者

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

服务提供者继承自Illuminate\Support\ServiceProvider类并包含两个方法:registerbootServiceProvider基类位于Composer包illuminate/support

要了解更多关于服务提供者的内容,查看其文档

3、路由

要定义包的路由,只需要在包服务提供者中的boot方法中引入路由文件。在路由文件中,可以使用 Illuminate\Support\Facades\Route 门面注册路由,和Laravel应用中注册路由一样:

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

4、资源

配置

通常,需要发布包配置文件到应用根目录下的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');

默认包配置

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

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

迁移

如果你的包包含数据库迁移,可以使用 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
 */
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时,你的视图包将会被拷贝到指定路径。

5、命令

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

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

6、前端资源

你的包可能包含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

7、发布文件组

有时候你可能想要分开发布包前端资源组和资源,例如,你可能想要用户发布包配置的同时不发布包前端资源,可以通过在扩展包的服务提供者中调用 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"

学院君

学院君 has written 548 articles

资深PHP工程师,Laravel学院院长