Download the PHP package james-harper/data-contracts without Composer

Data Contracts

Data contracts defined here can be shared between multiple services.

This was originally designed for use with Laravel projects in mind, so there are some Laravel-specific convenience methods - dealing with validation rules or automatically converting to API resources, for example.

Todo and User data contracts have been included as examples. The following commands can be run to remove all traces of them.

Installation

This can be included in other packages via composer.

For any serious use, it is recommended to fork this repository and add data contracts that are appropriate to the domain you are working on. And then use the forked version via composer.

Defining Contracts

A data contract is defined in a JSON file which follows the JSON Schema specification.

The schema definition can be validated against the specification using the following command:

The id field of the resource (which will be id by default) will not be returned from the describe() method. If a resource is using something different as its identifier - for example guid - the contract's protected static $id property can be updated to reflect this.

PHP data contracts can be created by extending DataContracts\DataContract and then setting the $schema property as a link to the JSON definition. Schema paths should be relative to the project root. A RuntimeException will be thrown if no schema is defined.

DataContracts can be generated using the following composer command:

Usage

Each DataContract has a static describe() method which will return all of the fields on the contract (that are not considered private) and an all() method that will display everything.

There is also a validationRules() method that can be used to get any validation rules for the contract. These should use Laravel validation rules so that the output can be used directly for Request validation in Laravel projects. Transformers must be applied to get valid Laravel rules from a JSON Schema: these can be found in src/Rules.

Some helpers exist to make working with validation rules easier. validationRulesOptional() gets all rules but removes any required rules. This is useful for partial updates when not all fields would be expected. And rulesExcept($rule) can be used to filter out the chosen rule.

DataContracts can be used anywhere, but should be defined in this repository for shareability purposes.

Usage with Laravel Eloquent models

A DataContract can be used to filter Eloquent models down to only fields that are on the DataContract

Usage with Laravel API Resources

Simarly, DataContracts can be used to filter Laravel API Resources down to only fields that are on the DataContract

If any additional transformation needs to be performed, it is a case of simply overwriting the default transformation

CLI Tool

A CLI tool has been created to simplify common tasks and encourage the use of consistent patterns. It has been designed in a similar way to Laravel's artisan so it should feel familiar to use. It can be run using ./cli or php cli. Running the tool without any additional arguments will show the help screen which lists all available commands.

The following commands can be used:

• Flush cache
  • php cli flush:cache
  • php cli flush
• Run linting
  • php cli lint:run
  • php cli lint
  • php cli lint --fix
• Generate console command
  • php cli make:command <name>
  • php cli new <name>
• Generate data contract
  • php cli make:contract <name>
  • php cli schema <name>
• Delete data contract
  • php cli delete:contract <name>
  • php cli delete <name>
  • php cli remove <name>
• Generate console formatting pattern
  • php cli make:pattern <name> <delimiter>
  • php cli make:pattern <name> <opening-delimiter> <closing-delimiter>
  • php cli pattern <name> <delimiter>
• Generate validation rule
  • php cli make:rule <name>
  • php cli rule <name>
• Run tests
  • php cli test:run
  • php cli test
  • Run group(s) of tests
  • php cli test cache
  • php cli test rules,schemas
  • php cli test cache,contracts,rules,schemas,validation
• Update CHANGELOG.md
  • php cli update:changelog
  • php cli changelog
  • php cli make:log
  • php cli generate:log
• Validate JSON Schema
  • php cli validate:schema <name>
  • php cli validate <name>
• Validate all JSON Schemas
  • php cli validate:all

For additional help with any command the following command can be run:

• php cli -h <command>
• For example:
  • php cli -h make:command
  • php cli -h new

CLI documentation is stored in markdown files in console/docs

Tab completion for the CLI can be enabled by running the following command:

Notes

• Since DataContracts do not change until there is an update to this package, they are a good candidate to be cached. There is an in-built caching support. By default Illuminate\Cache is used with the file driver, but any PSR-16 compliant cache can be set with DataContract::setCache($cache)
• It is recommended to alias DataContracts to have a Contract suffix to avoid them being confused with models. For example: use DataContracts\User as UserContract. A statement like User::all() would be valid for both an Eloquent model and a DataContract. UserContract::all() makes it much easier to tell at a glance.
• In order to avoid autoloading issues, any sub-directories within directories that are configured to use PSR-4 autoloading (console/, src/, tests/) should begin with an uppercase letter. Folders that are not intended to contain any .php files (such as console/scripts) do not need to follow this rule.
• composer test can be used to run the whole test suite or the CLI test command can be used php cli test cache,contracts,rules,schemas,validation to run just a specific group of tests.
• JSON Schema dates/times can be quite fiddly at times. Here are some examples of the formats that can be used. "full-date full-time" will match "Y-m-d h:i:s". "date-time" expects a T between the date and time portions.