php json schema model generator
verging property metadata
유효성 검사를 포함하고 생성된 클래스에 대한 원활한 자동 완성 기능을 제공하는 JSON-스키마 파일에서 PHP 모델 클래스를 생성합니다.
PHP 애플리케이션의 간단한 예: Swagger 주석과 JSON-스키마 모델을 사용하여 API를 정의하고 문서화합니다. 이제 요청 데이터(예: 배열 항목)에 수동으로 액세스하는 대신 컨트롤러 작업에서 모델을 사용하려고 합니다. 또한 스키마는 이미 모델에 대한 유효성 검사 규칙을 정의합니다. 이 규칙을 수동으로 작성된 코드에 복제하는 이유는 무엇입니까? 대신 이 라이브러리로 생성된 모델을 인스턴스화하고 모델에 요청 데이터를 공급하는 미들웨어를 설정할 수 있습니다. 이제 컨트롤러 작업에 사용할 수 있는 검증된 모델이 생겼습니다. 중첩된 개체로 작업할 때 완전 자동 완성 기능이 있습니다. 이야!
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-production 라이브러리를 포함하는 것이 좋습니다. . 프로덕션 라이브러리는 생성된 코드를 실행하기 위한 모든 클래스를 제공합니다. 클래스 생성은 개발 환경에서 수행되는 단계이거나 애플리케이션의 빌드 단계(권장되는 워크플로)로 수행되어야 합니다.
자세한 내용은 문서를 확인하세요.
모델 생성을 위한 기본 개체는 ModelGenerator 입니다. 생성기를 생성한 후에는 추가 구성 없이 객체를 사용하여 모델 클래스를 생성할 수 있습니다.
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );generateModels 메소드의 첫 번째 매개변수는 SchemaProviderInterface 를 구현하는 클래스여야 합니다. 공급자는 JSON 스키마 파일을 가져와 생성기에 제공합니다. 다음 공급자를 사용할 수 있습니다.
| 공급자 | 설명 |
|---|---|
| 재귀 디렉터리 제공자 | 지정된 소스 디렉터리에서 모든 *.json 파일을 가져옵니다. 각 파일에는 최상위 수준의 JSON 스키마 개체 정의가 포함되어야 합니다. |
| 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-스키마 파일은 개체의 스키마를 제공해야 합니다.
./tests/manual 디렉토리에는 사용법을 보여주는 몇 가지 쉬운 예가 포함되어 있습니다. composer update 통해 라이브러리의 종속성을 설치한 후 php ./tests/manual/test.php 실행하여 예제를 생성하고 일부 JSON-스키마 파일을 사용하여 라이브러리를 탐색할 수 있습니다.
쉬운 예를 살펴보겠습니다. 이름과 선택적인 나이를 가진 사람에 대한 간단한 모델을 만듭니다. 결과 JSON-스키마:
{
"$id" : " Person " ,
"type" : " object " ,
"properties" : {
"name" : {
"type" : " string "
},
"age" : {
"type" : " integer " ,
"minimum" : 0
}
},
"required" : [
" name "
]
} 이 JSON-스키마를 사용하여 클래스를 생성한 후 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
클래스 생성 프로세스는 기본적으로 3~4단계로 나뉩니다.
라이브러리는 PHPUnit을 통해 테스트됩니다.
composer update 통해 라이브러리의 종속성을 설치한 후 ./vendor/bin/phpunit ) 또는 vendorbinphpunit.bat (Windows)를 사용하여 테스트를 실행할 수 있습니다. 테스트 이름은 --testdox 출력 사용에 맞게 최적화되었습니다. 대부분의 테스트는 JSON-스키마 파일을 설정하고 스키마에서 클래스를 생성한 후 생성된 클래스의 동작을 테스트하는 원자 통합 테스트입니다.
실행 중에 테스트는 JSON-스키마 파일과 PHP 클래스가 기록될 tmp에 PHPModelGeneratorTest 디렉토리를 생성합니다.
JSON-스키마에서 PHP 클래스를 생성하는 테스트가 JSON-스키마에 실패하면 생성된 클래스는 ./failed-classes 디렉터리에 덤프됩니다.
라이브러리에 대한 문서는 Sphinx로 생성됩니다.
Sphinx 설치 문서를 생성하려면 docs 디렉토리에 들어가서 make html (Linux) 또는 make.bat html (Windows)을 실행하세요. 생성된 문서는 ./docs/build 디렉터리에서 사용할 수 있습니다.
Read the Docs에 호스팅된 문서는 푸시할 때마다 업데이트됩니다.
