php json schema model generator
verging property metadata
Генерирует классы модели PHP из файлов JSON-Schema, включая проверку и плавное автоматическое завершение сгенерированных классов.
Простой пример из PHP-приложения: вы определяете и документируете API с помощью аннотаций Swagger и моделей JSON-Schema. Теперь вы хотите использовать модели в действиях вашего контроллера вместо ручного доступа к данным запроса (например, к массиву). Кроме того, ваша схема уже определяет правила проверки моделей. Зачем дублировать эти правила в написанный вручную код? Вместо этого вы можете настроить промежуточное программное обеспечение, которое создает экземпляры моделей, созданных с помощью этой библиотеки, и снабжает модель данными запроса. Теперь у вас есть проверенная модель, которую вы можете использовать в действии контроллера. С полным автодополнением при работе с вложенными объектами. Ура!
Рекомендуемый способ установки 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 ' );Первым параметром методаgenerModels должен быть класс, реализующий SchemaProviderInterface . Поставщик извлекает файлы схемы JSON и предоставляет их генератору. Доступны следующие провайдеры:
| Поставщик | Описание |
|---|---|
| Рекурсиведиректорипровидер | Извлекает все файлы *.json из заданного исходного каталога. Каждый файл должен содержать определение объекта схемы JSON на верхнем уровне. |
| ОпенAPIv3Provider | Извлекает все объекты, определенные в #/components/schemas section файла спецификации Open API v3. |
Второй параметр должен указывать на существующий и пустой каталог (вы можете использовать вспомогательный generateModelDirectory для создания целевого каталога). Этот каталог будет содержать сгенерированные классы PHP после завершения работы генератора.
В качестве дополнительного параметра вы можете настроить объект GeneratorConfiguration (все доступные параметры см. в документации) для настройки вашего генератора и/или использовать метод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-схемой наш класс с именем 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
Процесс генерации классов в основном делится на три-четыре этапа:
Библиотека тестируется через PHPUnit.
После установки зависимостей библиотеки через composer update вы можете выполнить тесты с помощью ./vendor/bin/phpunit (Linux) илиvendor vendorbinphpunit.bat (Windows). Имена тестов оптимизированы для использования вывода --testdox . Большинство тестов представляют собой атомарные интеграционные тесты, которые настраивают файл JSON-Schema, генерируют класс из схемы и впоследствии проверяют поведение сгенерированного класса.
Во время выполнения тестов будет создан каталог PHPModelGeneratorTest в tmp, куда будут записываться файлы JSON-Schema и классы PHP.
Если тест, который создает класс PHP из JSON-схемы, завершается неудачно, JSON-схема и сгенерированные классы будут сброшены в каталог ./failed-classes
Документация для библиотеки создается с помощью Sphinx.
Чтобы создать документацию, установите Sphinx, войдите в каталог docs и выполните make html (Linux) или make.bat html (Windows). Сгенерированная документация будет доступна в каталоге ./docs/build .
Документация, размещенная на странице Read the Docs, обновляется при каждом обновлении.
