Laravel Package 中文文件

Annlix發表於2021-04-18

該文翻譯自 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 命令,以快速構建 CommandsRequestsJobsEvents 等。
  • 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 目錄,它包含了一個 laravelsrc 目錄。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.

相關文章