擴展包開發 · 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>