扩展包开发 · laravel 5.4

<article><h1>Laravel 的扩展插件开发指南</h1><ul><li><a href="#introduction">简介</a><ul><li><a href="#a-note-on-facades">Facade 注解</a></li></ul></li><li><a href="#service-providers">服务提供者</a></li><li><a href="#routing">路由</a></li><li><a href="#resources">资源文件</a><ul><li><a href="#configuration">配置</a></li><li><a href="#migrations">数据库迁移</a></li><li><a href="#routes">路由</a></li><li><a href="#translations">语言包</a></li><li><a href="#views">视图</a></li></ul></li><li><a href="#commands">命令</a></li><li><a href="#public-assets">公用 Assets</a></li><li><a href="#publishing-file-groups">发布群组文件</a></li></ul><a name="introduction"></a><h2><a href="#introduction">简介</a></h2>扩展包是添加功能到 Laravel 的主要方式。扩展包可以包含许多好用的功能，像 <a href="https://github.com/briannesbitt/Carbon">Carbon</a> 可用于处理时间，或像 <a href="https://github.com/Behat/Behat">Behat</a> 这种完整的 BDD 测试框架。当然，这有非常多不同类型的扩展包。有些扩展包是独立运作的，意思是指他们并不依赖于任何框架，包括 Laravel。刚刚所提到的 Carbon 及 Behat 就是这种扩展包。要使用这种扩展包只需要在 <code class=" language-php">composer.json</code> 文件里引入它们即可。另一方面，有些扩展包特别指定只能在 Laravel 里面集成。这些扩展包可能包含路由、控制器、视图以及扩展包的相关设置，目的是增强 Laravel 本身的功能。这份指南里将主要以开发 Laravel 专属的扩展包为目标进行说明。<a name="a-note-on-facades"></a><h3>Facade 注解</h3>当开发 Laravel 应用程序时，通常来讲你使用契约(contracts) 还是 facades 并没有什么区别，因为他们都提供了基本相同的水平的可测试性。但是，在进行扩展包开发的时候，最好的方式是使用 <a href="/docs/5.4/contracts">contracts</a> ，而不是 <a href="/docs/5.4/facades">facades</a>。因为你开发的包并不能访问所有 Laravel 提供的测试辅助函数，模拟 contracts 要比模拟 facade 简单很多。<a name="service-providers"></a><h2><a href="#service-providers">服务提供者</a></h2><a href="/docs/5.4/providers">服务提供者</a> 是你的扩展包与 Laravel 连接的重点。服务提供者负责绑定一些东西至 Laravel 的 <a href="/docs/5.4/container">服务容器</a> 并告知 Laravel 要从哪加载扩展包的资源，例如视图、配置文件、语言包。服务提供者继承了 <code class=" language-php">Illuminate\Support\ServiceProvider</code> 类并包含了两个方法：<code class=" language-php">register</code> 及 <code class=" language-php">boot</code> 。基底的 <code class=" language-php">ServiceProvider</code> 类被放置在 Composer 的 <code class=" language-php">illuminate/support</code> 扩展包，你必须将它加入至你自己的扩展包依赖中。若要了解更多关于服务提供者的结构与用途，请查阅 <a href="/docs/5.4/providers">它的文档</a>。<a name="routing"></a><h2><a href="#routing">路由</a></h2>要为你的扩展包定义路由，只需在包的服务提供者的 <code class=" language-php">boot</code> 方法中传递 routes 文件路径到 <code class=" language-php">loadRoutesFrom</code> 方法即可。在你的路由文件中，你可以使用 <code class=" language-php">Illuminate\Support\Facades\Route</code> 来 <a href="/docs/5.4/routing">注册路由</a> ，就像在典型的 Laravel 应用程序中一样：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->loadRoutesFrom(__DIR__.'/path/to/routes.php'); }</code></pre><a name="resources"></a><h2><a href="#resources">资源文件</a></h2><a name="configuration"></a><h3>配置</h3>有时候，你可能想要将扩展包的配置文件发布到应用程序本身的 config 目录上。这能够让扩展包的用户轻松的重写这些默认的设置选项。如果要发布扩展包的配置文件，只需要在服务提供者里的 <code class=" language-php">boot</code> 方法内使用 <code class=" language-php">publishes</code> 方法：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->publishes([ __DIR__.'/path/to/config/courier.php' => config_path('courier.php'), ]); }</code></pre>现在当扩展包的用户使用 Laravel 的 <code class=" language-php">vendor:publish</code> 命令时，扩展包的文件将会被复制到指定的位置上。当然，只要你的配置文件被发布，就可以如其它配置文件一样被访问：<pre class=" language-php"><code class=" language-php">$value = config('courier.option');</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 您不应在配置文件中定义闭包函数。当用户执行 <code class=" language-php">config:cache</code> Artisan命令时，它们不能正确地序列化。</blockquote><h4>默认的扩展包配置文件</h4>你也可以选择合并你的扩展包配置文件和应用程序里的副本配置文件。这样能够让你的用户在已经发布的副本配置文件中只包含他们想要重写的设置选项。如果想要合并配置文件，可在服务提供者里的 <code class=" language-php">register</code> 方法里使用 <code class=" language-php">mergeConfigFrom</code> 方法：<pre class=" language-php"><code class=" language-php">/** * 在容器中注册绑定。 * * @return void */ public function register() { $this->mergeConfigFrom( __DIR__.'/path/to/config/courier.php', 'courier' ); }</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 此方法仅合并配置数组的第一级。如果您的用户部分定义了多维配置数组，则不会合并缺失的选项。</blockquote><a name="routes"></a><h3>路由</h3>如果您的扩展包包中包含路由，您可以使用 <code class=" language-php">loadRoutesFrom</code> 方法加载它们。此方法将自动确定应用程序的路由是否已缓存，如果路由已缓存，将不会加载路由文件：<pre class=" language-php"><code class=" language-php">/** * 执行服务的注册后启动。 * * @return void */ public function boot() { $this->loadRoutesFrom(__DIR__.'/routes.php'); }</code></pre><a name="migrations"></a><h3>数据库迁移</h3>如果你的扩展包包含 <a href="/docs/5.4/migrations">数据库迁移</a> ，你需要使用 <code class=" language-php">loadMigrationsFrom</code> 方法告知 Laravel 如何去加载他们。<code class=" language-php">loadMigrationsFrom</code> 方法只需要你的扩展包的迁移文件路径作为唯一参数。<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->loadMigrationsFrom(__DIR__.'/path/to/migrations'); }</code></pre>完成扩展包迁移文件注册之后，在运行 <code class=" language-php">php artisan migrate</code> 命令时，它们就会自动被执行。你并不需要把他们导出到应用程序的 <code class=" language-php">database/migrations</code> 目录。<a name="translations"></a><h3>语言包</h3>如果你的扩展包里面包含了 <a href="/docs/5.4/localization">本地化</a> ，则可以使用 <code class=" language-php">loadTranslationsFrom</code> 方法来告知 Laravel 该如何加载它们。举个例子，如果你的扩展包名称为 <code class=" language-php">courier</code> ，你可以按照以下方式将其添加至服务提供者的 <code class=" language-php">boot</code> 方法：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier'); }</code></pre>扩展包翻译参照使用了双分号 <code class=" language-php">package::file.line</code> 语法。所以，你可以按照以下方式来加载 <code class=" language-php">courier</code> 扩展包中的 <code class=" language-php">messages</code> 文件 <code class=" language-php">welcome</code> 语句：<pre class=" language-php"><code class=" language-php">echo trans('courier::messages.welcome');</code></pre><h4>发布语言包</h4>如果你想将扩展包的语言包发布至应用程序的 <code class=" language-php">resources/lang/vendor</code> 目录，则可以使用服务提供者的 publishes 方法。<code class=" language-php">publishes</code> 方法接受一个包含扩展包路径及对应发布位置的数组。例如，在我们的 <code class=" language-php">courier</code> 扩展包中发布语言包：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier'); $this->publishes([ __DIR__.'/path/to/translations' => resource_path('lang/vendor/courier'), ]); }</code></pre>现在，当使用你扩展包的用户运行 Laravel 的 vendor:publish Artisan 命令时，扩展包的语言包将会被复制到指定的位置上。<a name="views"></a><h3>视图</h3>若要在 Laravel 中注册扩展包 <a href="/docs/5.4/views">视图</a>，则必须告诉 Laravel 你的视图位置。你可以使用服务提供者的 <code class=" language-php">loadViewsFrom</code> 方法来实现。<code class=" language-php">loadViewsFrom</code> 方法允许两个参数：视图模板路径与扩展包名称。例如，如果你的扩展包名称是 <code class=" language-php">courier</code> ，你可以按照以下方式将其添加至服务提供者的 <code class=" language-php">boot</code> 方法内：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier'); }</code></pre>扩展包视图参照使用了双分号 <code class=" language-php">package::view</code> 语法。所以，你可以通过如下方式从 <code class=" language-php">courier</code> 扩展包中加载 <code class=" language-php">admin</code> 视图：<pre class=" language-php"><code class=" language-php">Route::get('admin', function () { return view('courier::admin'); });</code></pre><h4>重写扩展包视图</h4>当你使用 <code class=" language-php">loadViewsFrom</code> 方法时，Laravel 实际上为你的视图注册了两个位置：一个是应用程序的 resources/views/vendor 目录，另一个是你所指定的目录。所以，以 <code class=" language-php">courier</code> 为例：当用户请求一个扩展包的视图时，Laravel 会在第一时间检查 <code class=" language-php">resources/views/vendor/courier</code> 是否有开发者提供的自定义版本视图存在。接着，如果这个路径没有自定义的视图，Laravel 会搜索你在扩展包 <code class=" language-php">loadViewsFrom</code> 方法里所指定的视图路径。这个方法可以让用户很方便的自定义或重写扩展包视图。<h4>发布视图</h4>若要发布扩展包的视图至 <code class=" language-php">resources/views/vendor</code> 目录，则必须使用服务提供者的 <code class=" language-php">publishes</code> 方法。<code class=" language-php">publishes</code> 方法允许一个包含扩展包视图路径及对应发布路径的数组。<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier'); $this->publishes([ __DIR__.'/path/to/views' => resource_path('views/vendor/courier'), ]); }</code></pre>现在，当你的扩展包用户运行 Laravel 的 <code class=" language-php">vendor:publish</code> Artisan 命令时，扩展包的视图将会被复制到指定的位置上。<a name="commands"></a><h2><a href="#commands">命令</a></h2>给你的扩展包注册 Artisan 命令，您可以使用 <code class=" language-php">commands</code> 方法。此方法需要一个命令类的数组。一旦命令被注册，您可以使用 <a href="/docs/5.4/artisan">Artisan 命令行</a> 执行它们：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { if ($this->app->runningInConsole()) { $this->commands([ FooCommand::class, BarCommand::class, ]); } }</code></pre><a name="public-assets"></a><h2><a href="#public-assets">公用 Assets</a></h2>你的扩展包内可能会包含许多的资源文件，像 JavaScript、CSS 和图片等文件。如果要发布这些资源文件到应用程序的 <code class=" language-php">public</code> 目录上，只需使用服务提供者的 <code class=" language-php">publishes</code> 方法。在这个例子中，我们也会增加一个 <code class=" language-php">public</code> 的资源分类标签，可用于发布与分类关联的资源文件：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @return void */ public function boot() { $this->publishes([ __DIR__.'/path/to/assets' => public_path('vendor/courier'), ], 'public'); }</code></pre>现在，当您的扩展包的用户执行 <code class=" language-php">vendor:publish</code> 命令时，您的 Assets 将被复制到指定的发布位置。由于每次更新包时通常都需要覆盖资源，因此您可以使用 <code class=" language-php">--force</code> 标志：<pre class=" language-php"><code class=" language-php">php artisan vendor:publish --tag=public --force</code></pre><a name="publishing-file-groups"></a><h2><a href="#publishing-file-groups">发布群组文件</a></h2>你可能想要分别发布分类的扩展包资源文件或是资源。举例来说，你可能想让用户不用发布扩展包的所有资源文件，只需要单独发布扩展包的配置文件即可。这可以通过在调用 <code class=" language-php">publishes</code> 方法时使用「标签」来实现。例如，让我们在扩展包的服务提供者中的 <code class=" language-php">boot</code> 方法定义两个发布群组：<pre class=" language-php"><code class=" language-php">/** * 在注册后进行服务的启动。 * * @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'); }</code></pre>现在当你的用户使用 <code class=" language-php">vendor:publish</code> Artisan 命令时，就可以通过标签名称分别发布不同分类的资源文件：<pre class=" language-php"><code class=" language-php">php artisan vendor:publish --tag=config</code></pre><h2>译者署名</h2><table><thead><tr><th>用户名</th><th>头像</th><th>职能</th><th>签名</th></tr></thead><tbody><tr><td><a href="https://github.com/e421083458">@e421083458</a></td><td><img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/10802_1486368142.jpeg?imageView2/1/w/100/h/100"></td><td>翻译</td><td>Github求star，<a href="https://github.com/e421083458/">@e421083458</a> at Github</td></tr></tbody></table></article>