level3 / resource
Level3 Resource is a library for representing resources and consuming in different hypermedia formats.
Installs: 34 456
Dependents: 4
Suggesters: 0
Security: 0
Stars: 17
Watchers: 3
Forks: 6
Open Issues: 0
Requires
- php: >=5.4.0
- hampel/json: 1.0.*
Requires (Dev)
- mockery/mockery: 0.8.0
- phpunit/phpunit: 3.7.*
This package is not auto-updated.
Last update: 2020-01-20 03:37:15 UTC
README
Level3 Resource is a library for representing and consuming resources in different hypermedia formats.
A resource in a [HATEOAS API] (http://en.wikipedia.org/wiki/HATEOAS) must describe its own capabilities and interconnections, which is the third level of Three Levels of the REST Maturity Model
Why Hypermedia?
As you can read in the prologue of Designing Hypermedia APIs book:
Hypermedia APIs embrace the principles that make the web great: flexibility, standardization, and loose coupling to any given service. They take into account the principles of systems design enumerated by Roy Fielding in his thesis, but with a little less sytems theory jargon.
Hypermedia designs scale better, are more easily changed and promote decoupling and encapsulation, with all the benefits those things bring. On the downside, it is not necessarily the most latency-tolerant design, and caches can get stale if you're not careful. It may not be as efficient on an individual request level as other designs.
Which Hypermedia specification should I use?
Hypermedia is being defined these days. Only the best APIs implement Hypermedia. Currently there is no de facto standard, so you must choose between the differents specifications.
Level3 Resource currenly implements or is planned to implement these specifications:
- HAL: This is the most common and active. It has a JSON and a XML version.
- Siren: Currently being defined. It implements some useful things like actions, classes, etc.
- Collection+JSON: This is fully designed to be a CRUD oriented API.
Requirements
- PHP 5.4.x
- hampel/json >= 1.0
Installation
The recommended way to install Level3 Resource is through composer. You can see the package information on Packagist.
{ "require": { "level3/resource": "dev-master" } }
Examples
Writer
Basic Resource with Link as application/hal+json
use Level3\Resource\Link; use Level3\Resource\Resource; use Level3\Resource\Format\Writer\HAL; $resource = new Resource(); $resource->setURI('/foo'); $resource->setLink('foo', new Link('/bar')); $resource->setData([ 'foo' => 'bar', 'baz' => 'qux' ]); $writer = new HAL\JsonWriter(true); echo $writer->execute($resource);
{ "foo": "bar", "baz": "qux", "_links": { "self": { "href": "/foo" }, "foo": { "href": "/bar" } } }
Resource with embedded resources as aapplication/vnd.siren+json
use Level3\Resource\Link; use Level3\Resource\Resource; use Level3\Resource\Format\Writer\Siren; $resource = new Resource(); $resource->setRepositoryKey('index'); $resource->setURI('/index?page=2'); $resource->setLink('prev', new Link('/index?page=1')); $resource->setLink('next', new Link('/index?page=3')); $resource->addData('count', 5); $subresource = []; foreach (range(1, 5) as $value) { $subresource = new Resource(); $subresource->addData('value', $value); $subresources[] = $subresource; } $resource->addResources('subresources', $subresources); $writer = new Siren\JsonWriter(true); echo $writer->execute($resource);
{ "class": [ "index" ], "properties": { "count": 5 }, "entities": [ { "rel": "subresources", "class": [ "index", "subresources" ], "properties": { "value": 1 } }, ... { "rel": "subresources", "class": [ "index", "subresources" ], "properties": { "value": 5 } } ], "links": [ { "rel": "self", "href": "/index?page=2" }, { "rel": "prev", "href": "/index?page=1" }, { "rel": "next", "href": "/index?page=3" } ] }
Resource with linked resource as application/hal+xml
use Level3\Resource\Link; use Level3\Resource\Resource; use Level3\Resource\Format\Writer\HAL; $author = new Resource(); $author->setURI('/john-doe'); $author->setTitle('John Doe'); $article = new Resource(); $article->setURI('/lorem-ipsum'); $article->addData('description', 'Lorem ipsum dolor sit amet ...'); $article->linkResource('author', $author); $writer = new HAL\XMLWriter(true); echo $writer->execute($article);
<?xml version="1.0"?> <resource href="/lorem-ipsum"> <description>Lorem ipsum dolor sit amet ...</description> <link rel="author" href="/john-doe" title="John Doe"/> </resource>
Reader
Basic Resource with Link as application/hal+json
use Level3\Resource\Format\Reader\HAL; $json = '{"foo":"bar","baz":"qux","_links":{"self":{"href":"/foo"},"foo":{"href":"/bar"}}}'; $reader = new HAL\JsonReader(); $resource = $reader->execute($json); print_r($resource);
Level3\Resource\Resource Object ( [uri:protected] => /foo [links:protected] => Array ( [foo] => Level3\Resource\Link Object ( [href:protected] => /bar ) ) [data:protected] => Array ( [foo] => bar [baz] => qux ) )
Tests
Tests are in the tests
folder.
To run them, you need PHPUnit.
Example:
$ phpunit --configuration phpunit.xml.dist
License
MIT, see LICENSE