php json schema model generator下載 - php json schema model generator原始碼下載

php json schema model generator

其他類別

verging property metadata

下載

php-json-架構-模型產生器

從 JSON-Schema 檔案產生 PHP 模型類，包括驗證並為產生的類別提供流暢的自動完成功能。

動機

PHP 應用程式的簡單範例：您使用 swagger 註解和 JSON-Schema 模型定義並記錄 API。現在您想要在控制器操作中使用模型，而不是手動存取請求資料（例如陣列內容）。此外，您的架構已經定義了模型的驗證規則。為什麼要將此規則複製到您手動編寫的程式碼中？相反，您可以設定一個中間件來實例化使用該程式庫產生的模型，並向模型提供請求資料。現在您有了經過驗證的模型，可以在控制器操作中使用它。處理巢狀物件時具有全自動完成功能。耶！

要求

至少需要 PHP 8.0
需要 PHP 擴充 ext-json 和 ext-mbstring

安裝

安裝 php-json-schema-model-generator 的建議方法是透過 Composer：

 $ composer require --dev wol-soft/php-json-schema-model-generator
$ composer require wol-soft/php-json-schema-model-generator-production

為了避免將 php-json-schema-model-generator 的所有相依性新增至生產相依性中，建議將該程式庫新增為開發相依性並包含 wol-soft/php-json-schema-model-generator-product 函式庫。生產庫提供了運行生成的程式碼的所有類別。生成類別應該是在開發環境中完成的步驟，或作為應用程式的建置步驟（這是建議的工作流程）。

基本用法

查看文件以取得更多詳細資訊。

生成模型的基礎物件是ModelGenerator 。建立生成器後，您可以使用該物件來產生模型類，而無需任何進一步配置：

( new ModelGenerator ())
    -> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );

generateModels方法的第一個參數必須是實作SchemaProviderInterface 的類別。提供者取得 JSON 模式檔案並將其提供給生成器。可以使用以下提供者：

提供者	描述
遞迴目錄提供者	從給定的來源目錄中取得所有 *.json 檔案。每個檔案必須在頂層包含一個 JSON Schema 物件定義
OpenAPIv3提供者	取得 Open API v3 規範檔案的`#/components/schemas section`中定義的所有對象

第二個參數必須指向現有的空目錄（您可以使用generateModelDirectory幫助器方法來建立目標目錄）。該目錄將包含生成器完成後產生的 PHP 類別。

作為可選參數，您可以設定GeneratorConfiguration物件（查看文件以了解所有可用選項）來配置您的 Generator 和/或使用方法generateModelDirectory產生模型目錄（如果不存在，則將產生該目錄；如果它存在，所有包含的文件和資料夾將被刪除以進行乾淨的生成過程）：

 $ generator = new ModelGenerator (
    ( new GeneratorConfiguration ())
        -> setNamespacePrefix ( ' MyAppModel ' )
        -> setImmutable ( false )
);

$ generator
    -> generateModelDirectory ( __DIR__ . ' /result ' );
    -> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );

生成器將遞歸檢查給定的來源目錄並將所有找到的 *.json 檔案轉換為模型。來源目錄中的所有 JSON-Schema 檔案都必須提供物件的架構。

範例

目錄./tests/manual包含一些顯示用法的簡單範例。透過composer update安裝程式庫的依賴項後，您可以執行php ./tests/manual/test.php來產生範例並使用一些 JSON-Schema 檔案來探索該程式庫。

讓我們來看一個簡單的例子。我們為一個人創建一個簡單的模型，其中包含姓名和可選年齡。我們得到的 JSON 模式：

{
  "$id" : " Person " ,
  "type" : " object " ,
  "properties" : {
    "name" : {
      "type" : " string "
    },
    "age" : {
      "type" : " integer " ,
      "minimum" : 0
    }
  },
  "required" : [
    " name "
  ]
}

使用此 JSON-Schema 產生類別後，名為Person的類別將提供以下介面：

 // the constructor takes an array with data which is validated and applied to the model
public function __construct( array $ modelData );

// the method getRawModelDataInput always delivers the raw input which was provided on instantiation
public function getRawModelDataInput(): array ;

// getters to fetch the validated properties. Age is nullable as it's not required
public function getName(): string ;
public function getAge(): ? int ;

// setters to change the values of the model after instantiation (only generated if immutability is disabled)
public function setName( string $ name ): Person ;
public function setAge(? int $ age ): Person ;

現在讓我們來看看生成的模型的行為：

 // Throws an exception as the required name isn't provided.
// Exception: 'Missing required value for name'
$ person = new Person ([]);

// Throws an exception as the name provides an invalid value.
// Exception: 'Invalid type for name. Requires string, got int'
$ person = new Person ([ ' name ' => 12 ]);

// Throws an exception as the age contains an invalid value due to the minimum definition.
// Exception: 'Value for age must not be smaller than 0'
$ person = new Person ([ ' name ' => ' Albert ' , ' age ' => - 1 ]);

// A valid example as the age isn't required
$ person = new Person ([ ' name ' => ' Albert ' ]);
$ person -> getName (); // returns 'Albert'
$ person -> getAge (); // returns NULL
$ person -> getRawModelDataInput (); // returns ['name' => 'Albert']

// If setters are generated the setters also perform validations.
// Exception: 'Value for age must not be smaller than 0'
$ person -> setAge (- 10 );

更複雜的異常訊息，例如。 allOf 組合可能如下所示：

 Invalid value for Animal declined by composition constraint.
  Requires to match 3 composition elements but matched 1 elements.
  - Composition element #1: Failed
    * Value for age must not be smaller than 0
  - Composition element #2: Valid
  - Composition element #3: Failed
    * Value for legs must not be smaller than 2
    * Value for legs must be a multiple of 2

這到底是怎麼運作的？

類生成過程基本上分為三到四個步驟：

掃描給定的來源目錄以查找所有應處理的 *.json 檔案。
循環遍歷所有應該產生的模式。這是類別生成的主要步驟。現在，每個模式都被解析，並且保存生成模型屬性的模式模型類別已填入。 JSON-Schema 中定義的所有驗證規則都會轉換為純 PHP 程式碼。模型完成後，會產生 RenderJob 並將其新增至 RenderQueue 。如果 JSON 架構包含巢狀物件或引用，則可以將多個 RenderJobs 新增至給定架構檔案的 RenderQueue 中。
如果為生成過程定義了後處理器，則將套用後處理器。
在解析所有模式檔案且沒有錯誤的情況下，渲染佇列將會關閉。所有先前新增的 RenderJobs 將被執行，並且 PHP 類別將被儲存到給定目標目錄的檔案系統中。

測試

該函式庫透過 PHPUnit 進行測試。

透過composer update安裝程式庫的依賴項後，您可以使用./vendor/bin/phpunit (Linux)或vendorbinphpunit.bat (Windows)執行測試。測試名稱針對--testdox輸出的使用進行了最佳化。大多數測試都是原子整合測試，它將設定 JSON 架構檔案並從該架構產生一個類，然後測試生成的類別的行為。

在執行期間，測試將在 tmp 中建立目錄 PHPModelGeneratorTest，其中將寫入 JSON-Schema 檔案和 PHP 類別。

如果從 JSON-Schema 建立 PHP 類別的測試失敗，則 JSON-Schema 和產生的類別將轉儲到目錄./failed-classes