Post Processors

Backward incompatible changes

The interfaces for filters have been moved to the production repository to implement a custom filter in a single class. The namespaces have been changed:

• FilterInterface is now located at PHPModelGenerator\Filter\FilterInterface
• TransformingFilterInterface is now located at PHPModelGenerator\Filter\TransformingFilterInterface

The output format of schema providers has been changed. Instead of a tuple for each schema a JsonSchema object must be returned. If you have implemented a custom schema provider have a look at the SchemaProviderInterface for more details and change your implementation to match the new interface. Basically instead of a tuple [$fileName, $jsonSchemaStructure] you must now return a JsonSchema object:

new JsonSchema($fileName, $jsonSchemaStructure);

Features

• Implemented post processors (#16) which can be used to change the generated model (eg. add additional functions to the model) (docs)
  • Builtin post processor: PopulatePostProcessor, adds a populate method to the model which allows updating any subset of the model's properties with validation (docs)
  • Provides an interface to implement custom post processors (docs)
• Extended the output of a SchemaException to contain the file which caused the exception

Internal

• Instead of arrays the schemas are passed through the library via JsonSchema objects.
• Adding serialization methods is now handled via a post processor

Reworked type hints

Backward incompatible changes

Arrays accepted null values implicitly without an option to disable null values. This behaviour has been changed so only non-null values are accepted now. If you require the acceptance of null values add null to the accepted item types of your array:

...
"myArrayProperty": {
	"type": "array",
	"items": {
		"type": ["string", "null"]
	}
}
...

Internal

• Changed some internal behaviour for a performance increase of the generated models (#12)
• Changed the generation process of merged properties so no unused code is generated (#13) (docs)

Bugfixes

• Arrays accept null entries implicitly
• RecursiveDirectoryIterator with a trailing slash results in a wrong base directory (#14)
• Wrong type hints for multi type properties and array properties

Bugfix

Bugfixes

• Fix error importing builtin types for transforming filters leading to fatal errors

Rework Exceptions

Backward incompatible changes

Fixed immutable classes default value (issue #7)

The default value for immutable was documented as true but was set to false. Now the default value is true. If you rely on setters being generated but haven't explicitly set the option on your GeneratorConfiguration you can simply set the option for immutable classes to false:

new Generator(
    (new GeneratorConfiguration())
        ->setImmutable(false)
);

Dropped setExceptionClass option

As errors are thrown as specific exceptions now the option to set a custom exception class for the early-return mode has been removed. A custom ErrorRegistryException for collecting validation errors can still be added

Changed ErrorRegistryExceptionInterface

As the internal errors which are collected in an ErrorRegistryException are now passed as ValidationExceptions and not as strings the interface for ErrorRegistryExceptions has been updated. If you provide a custom ErrorRegistryException you must update your implementation to follow the interface.

The method getErrors now returns an array of validation errors instead of a string array providing access to the collected errors.

The result of ErrorRegistryException->getMessage() hasn't been changed

Changed signature of toJSON and toArray

If you use the $options or $depth parameter of the toJSON or toArray method you must add the $except parameter which is now the first parameter of both functions (docs)

Features

Reworked exceptions

Instead of strings the internal errors are now specific exceptions implemented in the wol-soft/php-json-schema-model-generator-production repository. Each validation violation now has a dedicated exception implementation with additional data instead of a simple string (compare the docs for more details on which exceptions provide which data).

All exceptions, including the ErrorRegistryException now provide a toJSON and a toArray method for serialization and implement the PHP builtin interface JsonSerializable which allows the exceptions to be passed directly into json_encode.

Except for serialization methods

The serialization methods now provide an $except parameter to define properties which must'nt be serialized (eg. a password property for an user) (docs)

Bugfixes

• Skip filters after a failing transforming filter to avoid irrelevant additional errors due to type incompatibilities (PR #9)

Bugfix

Bugfixes

• Custom serializer methods from transforming filters are added multiple times if the filter gets applied to a multi type property

Explicit null

Backward incompatible changes

The models were generated with an implicit null acceptance for optional object properties (eg. an optional string value would also pass the validation if the property is present and contains null). This behaviour is not according to the JSON-Schema standard. Consequently now by default an explicit null type is required to accept null (eg. your property has a multi type ["string", "null"]). With a newly added option on your GeneratorConfiguration you can enable implicit null acceptance to get the old behaviour. View the docs for more details on the implicit null option.

new Generator(
    (new GeneratorConfiguration())
        ->setImplicitNull(true)
);

Features

• By default the properties now require an explicit definition of null acceptance via a multi type (eg. ["string", "null"]). A new option on the GeneratorConfiguration allows implicit null acceptance for optional object properties (docs)
• Models can be initialized without providing an array. The $modelData parameter now defaults to an empty array. All properties will be validated against the empty array when initializing a new model without providing data.
• If serialization is enabled the generated model will implement the PHP builtin JsonSerializable interface so the model can be passed to json_encode (docs)
• The builtin dateTime filter now accepts PHPs builtin constants for formatting options (docs)

Bugfixes

• In a filter chain containing a transforming filter the filters after the transforming filter are now type checked against transformed type instead of the base type
• transforming filters applied to a multi type property must accept each of the defined types on the property
• don't execute enum validation for values with a fransforming filter if the provided value is already transformed

Advanced filters and Schema Providers

Backward incompatible changes

As the JSON schemas are fetched via a provider now you have to change your model generator script. To get the old behaviour simply add the RecursiveDirectoryProvider:

Change from:

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

to:

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

Features

• Fetch JSON schemas via a provider implementation allowing different sources for object schemas than a folder structure containing the objects as separate .json files
• Added an Open API v3 schema provider which accepts an Open API v3 json file and converts all models located at #/components/schemas into PHP models (docs)
• Added additional builtin filters
  • notEmpty filter: Removes empty elements from a provided array (docs)
  • dateTime filter: converts a DateTime compatible string into a DateTime object (docs)
• Advanced filter logic
  • Filter may be applied to an array
  • Added transforming filter. A transforming filter takes the provided value and transforms the value into another type. The transformed type will be reflected as property type into the generated model (docs). A transforming filter for example may be used to initialize an object with a provided string (eg. date string into DateTime object). Properties with a transforming filter also accept an already transformed value (eg. the property with a DateTime filter also accepts a DateTime object).
  • Added filter options. A filter now may accept additional options which define the behaviour of the filter (docs)

Bugfixes

• If multiple filters are applied to a single property they will now be executed in the order of their appearance in the JSON Schema

Internal

• Moved serialization functionality into a trait to reduce code duplication

Dependencies

Features

• Added depth parameter to serialization methods (docs)
• Allow base references (docs)
• Added Property Dependencies (docs)
  • Require a list of properties to be present based on the presence of a property
• Added Schema Dependencies (docs)
  • Dependency to an object schema based on the presence of a property
  • Dependency to a composition schema based on the presence of a property
  • Dependency to a schema reference referring to either an object or a composition based on the presence of a property

Update ECS dependency

0.11.1

Fix typos

General Interface

• Each generated class now implements the JSONModelInterface