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