Laravel Package 中文文件

Annlix發表於2021-04-18
LaravelPackage

該文翻譯自 Laravel Package Development(laravelpackage.com/) 。本文中的第一人稱代詞均為原博作者。

由於譯者能力有限，文章翻譯可能存在紕漏、錯誤或不合理的地方，希望讀者能夠不吝指出。同時，由於譯者需要搬磚養家餬口，文件翻譯只能在工作之餘的空閒時間完成，所以更新時間可能不固定，但譯者會盡快完成文章翻譯，還望見諒。

以我的經驗來看，學習開發一個 Laravel Package 是富有挑戰的，這也就是為什麼我之前寫了一個 關於這個的部落格系列 。
隨著時間的推移，我開始認為這個主題應該有一個合適的文件，而不是幾篇涉及我的見解的文章。這也就是這個關於 Laravel Package 開發的開源文件開始的地方。我已經對我的部落格進行打包，並在不同的章節擴充套件了更多的內容。我非常歡迎您的貢獻，您可以通過 PR 的形式參與其中。我希望這個網站能夠成為分享 Laravel Package 開發知識的地方，並且能夠幫助開發者開始進行相關工作。
我非常鼓勵您參與並 為這個專案做出貢獻，您可以隨時提交 PR ，即便只是簡單的打字錯誤。
首先，我想要感謝 Marcel Pociot 。他清晰明瞭、結構分明的 視訊教程 鼓勵我建立了自己的 PHP Packages 。
? 您是否更青睞於看視訊而不是看書？著名的包開發者 Spatie 釋出了一個完整的 Laravel 包開發 的視訊。

為什麼要開發 Package

您可能會遇到這種情況：您希望在其他應用程式中複用應用程式的某些功能，開源部分功能，或是將相關的程式碼組織起來，但需要與主應用程式分開來。因此，將部分內容提取到 Package 就變得非常有意義。Package 或 library 提供了一個非常方便的途徑來新增可選的功能到現有的應用中，並將重點放在了特定功能上。

配套包

在該文中，我們將會通過逐一介紹列出的功能來構建一個 demo Package（稱之為 BlogPackage）。一定要檢查這個 Package 的完成後的完整版本，以便有一個方便的參考，例如，當某些東西不能按照預期工作時。該 demo 中包含一個測試套件，包括針對所涵蓋主題的單元測試和功能測試。

Composer 和 Packagist

在編寫程式碼時，PHP 軟體包的主要儲存庫 Packagist 上有近 240,000 個包可用。
您可以使用 Composer 來下載和安裝它們，Composer 是 PHP 的包管理工具，它可以幫您管理專案的依賴。
要在一個既有的 Laravel 專案中安裝包，您可以使用 composer require <vendor>/<package> ，它將為您下載所有必要的檔案，並它們置於專案的 vendor 目錄下，其中包含了所有的第三方軟體包，並以 vendor 名稱進行分隔。因此，這意味著包中的內容與應用程式程式碼分離，並且包中的程式碼由特定人員進行維護，通常是該包的建立者。

工具和助手

第一章將介紹 Package 的基本結構，瞭解 Package 的總體結構固然很好，但您亦可檢視一下有用的工具，以立即設定基本框架。

  • Package Skeleton by Spatie ：Spatie的這個包為從頭開始設定 Laravel Package 提供了一個很好的起點。除了 Laravel Package 軟體包的基本元件外，該框架還提供了 Github 特定的配置，包括一組用於 Github 操作 (CI) 的工作流。它還提供了通用的 PHP 擴充套件包。
  • Laravel Package Boilerplate ：Marcel Pociot 的這個工具可以讓您生成一個適用於 Laravel Package 和通用 PHP Package 的模板，您可以將其下載為一個 .zip 檔案。
  • Laravel Packager ：Jeroen-G 的這個包提供了一個 CLI 的工具，可以從現有的 Laravel 應用中快速構建包。這個包在構建 Laracasts 系列的 Laracasts 有介紹。
  • Laravel Packager Hermes ：DelveFore 的這個包是 Laravel Package r包的一個擴充套件，它允許在該包中使用 Artisan 命令快速生成 Laravel 特定的類。目前，它僅支援 Controllers 的腳手架。
  • Laravel Package Tools ：和前面提到的包一樣，Marcel Pociot 的這個包旨在從 Laravel 包中提供 Artisan 命令，以快速構建 Commands，Requests，Jobs，Events 等。
  • Orchestral Canvas ：改包提供了程式碼生成器，以及複製了基本 Laravel 應用程式中的所有的 make artisan 命令。
  • Yeoman Laravel Package Scaffolder ：這個包提供了一個獨立的生成器來快速搭建 Laravel 包。它將生成一個骨架結構，一個現成的 composer.json 檔案和一個完全配置的 Service Provider 。您只取消註釋需要的內容並開始開發。
  • Laravel Packer ：一個PHP軟體包，它提供了一個命令列工具來構建基本的包目錄結構和 composer.json 檔案，並在軟體包中提供了 make artisan 命令。
  • Laravel Package Maker ：一個 PHP 軟體包，提供所有 Laravel make 命令以進行軟體包開發。它使用 Composer 的儲存庫功能將您的測試應用程式與您的軟體包符號連結，以使測試儘可能容易。

自動載入

Composer 會在每次安裝或更新包之後自動在 /vendor 目錄下生成一個 autoload.php 檔案。通過引用這個單一的檔案，您可以訪問您安裝的包提供的所有類。
檢視 Laravel 專案，您會發現在應用的根目錄下的 public/index.php 檔案（用於處理所有傳入的請求）中包含了這個自動載入器（autoload.php），這將使所有必需的庫在您的應用程式範圍內可用。其中包括 Laravel 的 Illuminate 元件以及所有必需的第三方軟體包。
Laravel 的 public/index.php 檔案：

    <?php

    define('LARAVEL_START', microtime(true));

    require __DIR__.'/../vendor/autoload.php';

    // additional bootstrapping methods...

目錄結構

通常情況下（按照慣例），Package 包含一個 src/（「source」的縮寫）目錄，其中包含了所有 package 特定的邏輯（類），以及一個 composer.json 檔案，它包含了有關 package 的資訊。此外，大多數軟體包還包括許可證和文件。
如果我們檢視一個 package 的通用目錄結構，您會發現它與標準的 Laravel 有很大的區別：

    - src
    - tests
    CHANGELOG.md
    README.md
    LICENSE
    composer.json

在 package 中，所有置於 Laravel 專案的 app/ 目錄下的程式碼都位於 src/ 目錄下。

安裝 Composer

很有可能您已經安裝了 Composer 。當然，如果您還沒有安裝 Composer ，那麼最快地啟動和執行的方式是複製 Composer 上提供的指令碼。通過在命令列中複製和貼上提供的指令碼， 將會下載、安裝和移除 composer.phar 安裝器。您可以使用 composer self-update 來更新 Composer 到最新版本。

Package 架構

要開始開發一個 package ，首先，請建立一個空目錄。無需將其巢狀在現有的 Laravel 專案中。為了清晰起見，我強烈推薦將您的 Package 與（ Laravel ）專案分開來。
例如，我將所有的 package 儲存到 ~/packages 目錄下，將我的 Laravel 應用儲存到 ~/websites 目錄下。

Composer.json

首先，在您的 package 根目錄下建立一個 composer.json 檔案，它擁有最小配置（如下所示）。請按需配置。
name 最後與包名保持一致。標準約定是使用您的 Github / Gitlab / Butbucket / Gitee① 等，後根一個正斜槓（/），後接您的 kebab 格式的包名。
下面列出了 composer.json 的示例。

    {
        "name": "johndoe/blogpackage",
        "description": "A demo package",
        "type": "library",
        "license": "MIT",
        "authors": [
            {
                "name": "John Doe",
                "email": "john@doe.com"
            }
        ],
        "require": {}
    }

或者，您可以通過在空目錄下執行 composer init 來生成 composer.json 檔案。
如果您打算公開發布您的 package ，那麼選擇合適 package 型別（在我們的例子中是： library ）和許可證（同樣的，在我們的例子中是：MIT）是很重要的。您可以訪問 ChooseALicense.com 來選擇一個合適的許可證。

名稱空間

由於我們想要使用 src/ 目錄（約定俗成的）來儲存我們的程式碼，因此我們需要告訴 Composer 在建立自動載入器（ autoload.php ）時對映包的名稱空間到制定的目錄下。
我們可以按如下方式在 composer.json 檔案中的 「psr-4」自動載入項下注冊名稱空間（請按需配置）：

    {
        ...,

        "require": {},

        "autoload": {
            "psr-4": {
                "JohnDoe\\BlogPackage\\": "src"
            }
        }
    }

PSR-4 自動載入

現在，您可能已經明白了為什麼我們需要一個「psr-4」鍵。 PSR 標準是 PHP Framework Interoperability Group （ PHP-FIG ）設計的 PHP 標準建議。這個由 20 個成員組成的小組代表了 PHP 社群的一部分，他們提出了一系列的 PSR 。
在列表中，PSR-4 代表了一個關於從檔案路徑自動載入類的建議，取代了當時流行的 PSR-0 自動載入標準 。
PSR-0 和 PSR-4 之間顯著的區別在於 PSR-4 允許將基本目錄對映到特定的名稱空間，因此可以在專案中使用較短的名稱空間。我認為 Stackoverflow 上的 這個評論 清楚的描述了 PSR-0 和 PSR-4 是如何工作的。
PSR-0

    "autoload": {
        "psr-0": {
            "Book\\": "src/",
            "Vehicle": "src/"
        }
    }

  • 它將在 src/Book/History/UnitedStates.php 檔案中尋找 Book\History\UnitedStates

  • 它將在 src/Vehicle/Air/Wings/Airplane.php 檔案中尋找 Vehicle\Air\Wings\Airplane
    PSR-4

      "autoload": {
      "psr-4": {
          "Book\\": "src/",
          "Vehicle\\": "src/"
      }
  }

  • 它將在 src/History/UnitedStates.php 檔案中尋找 Book\History\UnitedStates

  • 它將在 src/Air/Wings/Airplane.php 檔案中尋找 Vehicle\Air\Wings\Airplane

    匯入本地 Package

    為了方便開發，您可以在本地的 Laravel 專案中匯入位於本地 Package 。
    如果您擁有一個本地的 Laravel 專案，您可以在 您的 Laravel 應用 的 composer.json 檔案中定義一個「repository」來自定義您的本地包。
    在 Laravel 應用的 composer.json 檔案中的「scripts」部分下方新增「repositories」鍵（請將「url」的值修改為您的 package 所處的位置）：

      {
      "scripts": { ... },

      "repositories": [
          {
              "type": "path",
              "url": "../../packages/blogpackage"
          }
      ]
  }

    現在，您便可以在您的 Laravel 專案中使用您的包名來引用你的包。按照我們的例子，這將是：

      composer require johndoe/blogpackage

    如果您在同一目錄中有多個軟體包，並且想讓 Composer 查詢所有軟體包，則可以使用萬用字元*列出包的位置，如下所示：

      {
      "scripts": { ... },

      "repositories": [
          {
                "type": "path",
                "url": "../../packages/*"
          }
        ]
  }

    重點：每當您修改了 package 或其他註冊了的任何程式的 composer.json 檔案時，都需要在 Laravel 程式中執行 composer update 。

    Orchestra Testbench

    我們現在已經擁有了一個 composer.json 檔案和一個空的 src/ 目錄。但是，我們還無法訪問 Illuminate 元件提供的 Laravel 特定的功能。
    要在包中使用這些元件，我們可以使用Orchestra Testbench 。請注意，每個版本的 Laravel 框架都有一個對應的 Orchestra Testbench 版本。在這一節中，我假設我們在 Laravel 8.0 下進行開發，這是撰寫該部分時最新的 Laravel 版本。

      composer require --dev "orchestra/testbench=^6.0"

    下方列出了完整的 Orchestra Testbench 相容性列表，摘自其 原始文件 。

Laravel Testbench
8.x 6.x
7.x 5.x
6.x 4.x
5.8.x 3.8.x
5.7.x 3.7.x
5.6.x 3.6.x
5.5.x 3.5.x
5.4.x 3.4.x
5.3.x 3.3.x
5.2.x 3.2.x
5.1.x 3.1.x
5.0.x 3.0.x

當 Orchestra Testbench 安裝完成後，您可以找到 vendor/orchestra/testbench-core 目錄，它包含了一個 laravel 和 src 目錄。laravel 目錄和真實的 Laravel 應用的結構類似，src 目錄提供了 Laravel 助手函式，它涉及與專案目錄的互動（例如：與檔案操作相關的）。
在每次測試前，TestBench 會建立一個測試環境，其包含了一個完整的 booted (test) 應用。如果我們使用 Orchestra TestBench 的基礎 TestCase 測試用例來進行測試，Orchestra\Testbench\Concerns 名稱空間的 CreatesApplication trait 提供的方法將負責建立測試應用。如果我們檢視其中的一個方法 getBasePath() ，我們可以發現它直接指向了 Orchestra Testbench 的 laravel 目錄。

    // 'vendor/orchestra/testbench-core/src/Concerns/CreatesApplication.php'
    /**
     * Get base path.
     *
     * @return string
     */
    protected function getBasePath()
    {
        return \realpath(__DIR__.'/../../laravel');
    }

① 譯者注：原文沒有 Gitee ，Gitee 為譯者加入。
[內容持續更新中……]

本作品採用《CC 協議》，轉載必須註明作者和本文連結
Pompeo is a pig.

相關文章