Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nilportugues/php-api-transformer
Base library providing the core functionality for API transformation.
https://github.com/nilportugues/php-api-transformer
api api-transformer hal jsend json marshaller microservice microservices php php7 serialization serializer transformer
Last synced: about 1 month ago
JSON representation
Base library providing the core functionality for API transformation.
- Host: GitHub
- URL: https://github.com/nilportugues/php-api-transformer
- Owner: nilportugues
- License: mit
- Created: 2015-08-13T11:43:07.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-04-07T14:54:35.000Z (over 7 years ago)
- Last Synced: 2024-11-02T09:32:01.753Z (about 2 months ago)
- Topics: api, api-transformer, hal, jsend, json, marshaller, microservice, microservices, php, php7, serialization, serializer, transformer
- Language: PHP
- Homepage: http://nilportugues.com
- Size: 84 KB
- Stars: 9
- Watchers: 4
- Forks: 10
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# API Transformer
[](https://travis-ci.org/nilportugues/php-api-transformer)
[](https://scrutinizer-ci.com/g/nilportugues/api-transformer/?branch=master)
[](https://insight.sensiolabs.com/projects/b4e5056d-c552-407e-ae21-2da685e07c06)
[](https://packagist.org/packages/nilportugues/api-transformer)
[](https://packagist.org/packages/nilportugues/api-transformer)
[](https://packagist.org/packages/nilportugues/api-transformer)
[](https://paypal.me/nilportugues)
## Purpose
This library provides the core functionality for API transformation and is a base library for many other packages.
By itself it's not usable at all. Check the projects using it below.
## Used by
Currently the following transformers make use of this library as foundation:
- [nilportugues/json](https://github.com/nilportugues/json-transformer)
- [nilportugues/jsend](https://github.com/nilportugues/jsend-transformer)
- [nilportugues/hal](https://github.com/nilportugues/hal-transformer)
- [nilportugues/json-api](https://github.com/nilportugues/jsonapi-transformer)
## Installation
Use [Composer](https://getcomposer.org) to install the package:
```json
$ composer require nilportugues/api-transformer
```
## How it works
Loading must be done using the `Mapper` class, as it expects an array containing a defined structure, or a class name implementing `ApiMapping`.
There are 2 styles for flexibility when integrating the library into PHP frameworks.
While I discourage having 2 styles for mapping it is well possible to have them side by side in the very same configuration file. The `Mapper` class that loads all Mappings does internal transformation for both, so client does not have to worry.
### Usage
```php
use NilPortugues\Api\Mapping\Mapper;
use NilPortugues\AcmeProject\Infrastructure\Api\Mappings\PostApiMapping;
$arrayConfig = include 'mappings.php';
$classConfig = [
PostApiMapping::class,
];
$mappings = array_merge($classConfig, $arrayConfig);
//Now $mapper can be passed to a Transformer.
$mapper = new Mapper($mappings);
```
## Creating the Mapping files
### Implementing ApiMapping (Prefered method)
To create a Mapping you may implement the following interfaces:
- `ApiMapping`: transform your data into plain JSON for API consumtion or the JSend API format.
- `JsonApiMapping` to transform your data into the JSONAPI 1.0 standard.
- `HalMapping` to transform your data to HAL+JSON and HAL+XML API standards.
As expected you may implement many interfaces to support multiple API formats.
```php
'headline',
'content' => 'body',
];
}
/**
* {@inheritdoc}
*/
public function getHideProperties() : array
{
return [
'comments',
];
}
/**
* {@inheritdoc}
*/
public function getIdProperties() : array
{
return [
'postId',
];
}
/**
* {@inheritdoc}
*/
public function getUrls() : array
{
return [
// Mandatory
'self' => 'http://example.com/posts/{postId}',
// Optional
'comments' => 'http://example.com/posts/{postId}/comments',
];
}
/**
* Returns an array of curies.
*
* @return array
*/
public function getCuries() : array
{
return [
'name' => 'example',
'href' => 'http://example.com/docs/rels/{rel}',
];
}
/**
* {@inheritdoc}
*/
public function getRelationships() : array
{
return [
'author' => [
'related' => 'http://example.com/posts/{postId}/author',
'self' => 'http://example.com/posts/{postId}/relationships/author',
],
];
}
}
```
### Mapping using an array
```php
// mappings.php
return [
[
'class' => Post::class,
'alias' => 'Posting', //If none is used 'Post' will be used instead.
'aliased_properties' => [
'title' => 'headline',
'content' => 'body',
],
'hide_properties' => [
'comments',
],
'id_properties' => [
'postId',
],
'urls' => [
// Mandatory
'self' => 'http://example.com/posts/{postId}',
// Optional
'comments' => 'http://example.com/posts/{postId}/comments',
],
// (Optional) Used by HAL+JSON / HAL+XML
'curies' => [
'name' => 'example',
'href' => 'http://example.com/docs/rels/{rel}',
],
// (Optional) Used by JSONAPI
'relationships' => [
'author' => [
'related' => 'http://example.com/posts/{postId}/author',
'self' => 'http://example.com/posts/{postId}/relationships/author',
],
]
],
];
```
## Quality
To run the PHPUnit tests at the command line, go to the tests directory and issue phpunit.
This library attempts to comply with [PSR-1](http://www.php-fig.org/psr/psr-1/), [PSR-2](http://www.php-fig.org/psr/psr-2/), [PSR-4](http://www.php-fig.org/psr/psr-4/) and [PSR-7](http://www.php-fig.org/psr/psr-7/).
If you notice compliance oversights, please send a patch via [Pull Request](https://github.com/nilportugues/api-transformer/pulls).
## Contribute
Contributions to the package are always welcome!
* Report any bugs or issues you find on the [issue tracker](https://github.com/nilportugues/api-transformer/issues/new).
* You can grab the source code at the package's [Git repository](https://github.com/nilportugues/api-transformer).
## Support
Get in touch with me using one of the following means:
- Emailing me at
- Opening an [Issue](https://github.com/nilportugues/api-transformer/issues/new)
## Authors
* [Nil Portugués Calderó](http://nilportugues.com)
* [The Community Contributors](https://github.com/nilportugues/api-transformer/graphs/contributors)
## License
The code base is licensed under the [MIT license](LICENSE).