juliangut / json-api
PSR7 aware json-api integration
Requires
- php: ^7.1
- juliangut/mapping: ^1.0
- neomerx/json-api: ^4.0
- psr/http-message: ^1.0
- psr/http-server-middleware: ^1.0
Requires (Dev)
- brainmaestro/composer-git-hooks: ^2.8
- doctrine/annotations: ^1.4
- friendsofphp/php-cs-fixer: ^2.16
- infection/infection: ^0.13|^0.15
- laminas/laminas-diactoros: ^2.0
- overtrue/phplint: ^1.2
- phpmd/phpmd: ^2.8
- phpstan/extension-installer: ^1.0.3
- phpstan/phpstan: ^0.12
- phpstan/phpstan-deprecation-rules: ^0.12
- phpstan/phpstan-strict-rules: ^0.12
- phpunit/phpunit: ^7.5|^8.0
- povils/phpmnd: ^2.1
- roave/security-advisories: dev-master
- sebastian/phpcpd: ^4.0
- squizlabs/php_codesniffer: ^3.5
- thecodingmachine/phpstan-strict-rules: ^0.12
Suggests
- doctrine/annotations: In order to load resource mapping from annotations
- symfony/yaml: In order to load resource mapping from YAML files
This package is auto-updated.
Last update: 2021-01-13 00:17:04 UTC
README
json-api
Easy JSON:API integration.
Installation
Composer
composer require juliangut/json-api
doctrine/annotations to parse annotations
composer require doctrine/annotations
symfony/yaml to parse yaml files
composer require symfony/yaml
Usage
Require composer autoload file
require './vendor/autoload.php';
use Jgut\JsonApi\Manager; use Jgut\JsonApi\Configuration; use Neomerx\JsonApi\Schema\Error; $configuration = new Configuration([ 'sources' => ['/path/to/resource/files'], ]); $jsonApiManager = new Manager($configuration); // Get encoded errors $jsonApiManager->encodeErrors(new Error()); // Get encoded resources $jsonApiManager->encodeResources(new MyClass(), new ServerRequestInstance());
Configuration
sources
must be an array containing arrays of configurations to create MappingDriver objects:type
one of \Jgut\JsonApi\Mapping\Driver\DriverFactory constants:DRIVER_ANNOTATION
,DRIVER_PHP
,DRIVER_JSON
,DRIVER_XML
orDRIVER_YAML
defaults to DRIVER_ANNOTATION if no driverpath
a string path or array of paths to where mapping files are located (files or directories) REQUIRED if no driverdriver
an already created \Jgut\JsonApi\Mapping\Driver\DriverInterface object REQUIRED if no type AND path
attributeName
name of the PSR-7 Request attribute that will hold query parameters for resource encoding, defaults to 'JSON_API_query_parameters'schemaClass
class name implementing \Jgut\JsonApi\Schema\MetadataSchemaInterface (\Jgut\JsonApi\Schema\MetadataSchema by default)urlPrefix
prefix for generated URLsmetadataResolver
an instance of \Jgut\Mapping\Metadata\MetadataResolver. It is highly recommended to provide a PSR-16 cache to metadata resolver on productionencodingOptions
global encoding options, an instance of \Jgut\JsonApi\Encoding\OptionsInterfacejsonApiVersion
none by defaultjsonApiMeta
optional global metadata
Resources
Resources can be defined in two basic ways: by setting them in definition files of various types or directly defined in annotations on classes
Annotations
Resource (Class level)
Identifies each resource. Its presence is mandatory on each resource class
use Jgut\JsonApi\Mapping\Annotation as JJM; /** * @JJM\Resource( * name="company", * schemaClass="customSchemaClass", * urlPrefix="resourcePrefix", * selfLinkIncluded=true, * relatedLinkIncluded=false, * links={"link1": "http://...", "link2": "http://..."], * meta=["meta1", "meta2"] * ) */ class Company { }
name
, optional, resource name, class name by defaultschemaClass
, optional, schema class, must implementNeomerx\JsonApi\Contracts\Schema\SchemaInterface
,Jgut\JsonApi\Schema\MetadataSchema
by defaultutlPrefix
, optional, none by defaultselfLinkIncluded
, optional bool, display self link, null by defaultrelatedLinkIncluded
, optional bool, display self link when included, null by defaultlinks
, optional, list of optional resource linksmeta
, optional, list of optional resource metadata
Attribute (Property level)
Defines each and every attribute accessible on the resource
use Jgut\JsonApi\Mapping\Annotation as JJM; /** * @JJM\Resource */ class Company { /** * @var string * * @JJM\Attribute( * name="email", * getter="getEmail", * setter="setEmail", * groups=["view"] * ) */ protected $email; }
name
, optional, attribute name, property name by defaultgetter
, optional, getter method namesetter
, optional, setter method namegroups
, optional, list of encoding groups
Id (Property level)
The resource identifier
use Jgut\JsonApi\Mapping\Annotation as JJM; /** * @JJM\Resource */ class Company { /** * @var string * * @JJM\Id( * name="id", * getter="getId", * setter="setId", * groups=["view"] * ) */ protected $id; }
Relationship (Property level)
Identifies this resource relationships
use Jgut\JsonApi\Mapping\Annotation as JJM; /** * @JJM\Resource */ class Company { /** * @var Owner * * @JJM\Relationship( * selfLinkIncluded=true, * relatedLinkIncluded=false, * links={"link1": "http://...", "link2": "http://..."], * meta=["meta1", "meta2"] * ) */ protected $company; }
selfLinkIncluded
, optional bool, display self link, null by defaultrelatedLinkIncluded
, optional bool, display self link when included, null by defaultlinks
, optional, list of optional relationship linksmeta
, optional, list of optional relationship metadata
Definition files
PHP
JSON
XML
YAML
Middleware
Use PSR-15 middleware Jgut\JsonApi\Middleware\JsonApiMiddleware
in order to validate request being a valid JSON:API specification request
use Jgut\JsonApi\Middleware\JsonApiMiddleware; /** @var \Psr\Http\Message\ResponseFactoryInterface $responseFactory */ /** @var \Jgut\JsonApi\Manager $jsonApiManager */ $middleware = new JsonApiMiddleware($responseFactory, $jsonApiManager); // Add the middleware to PSR-15 compatible library/framework, such as Slim, Mezzio, etc
Contributing
Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.
See file CONTRIBUTING.md
License
See file LICENSE included with the source code for a copy of the license terms.