Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/blongden/hal
application/hal builder / formatter for PHP 5.4+
https://github.com/blongden/hal
Last synced: about 1 month ago
JSON representation
application/hal builder / formatter for PHP 5.4+
- Host: GitHub
- URL: https://github.com/blongden/hal
- Owner: blongden
- License: mit
- Created: 2012-04-02T10:07:36.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2021-09-10T15:06:14.000Z (over 3 years ago)
- Last Synced: 2024-10-30T17:49:48.792Z (about 1 month ago)
- Language: PHP
- Homepage:
- Size: 211 KB
- Stars: 203
- Watchers: 10
- Forks: 40
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-php - HAL - A Hypertext Application Language (HAL) builder library. (Table of Contents / API)
- awesome-rest - HAL - Hypertext Application Language (HAL) builder library. (Servers / PHP)
- awesome-php-cn - HAL - 超文本应用程序语言(HAL)构建器库. (目录 / API)
- awesome-projects - HAL - A Hypertext Application Language (HAL) builder library. (PHP / API)
- awesome-php - HAL - A Hypertext Application Language (HAL) builder library. (Table of Contents / API)
README
Nocarrier\Hal
=============
[](http://travis-ci.org/blongden/hal)
[](https://scrutinizer-ci.com/g/blongden/hal/?branch=master)
This is a library for creating documents in the [application/hal+json and application/hal+xml][1] hypermedia formats
It requires PHP 5.4 or later.
```php
addLink('next', '/orders?page=2');
$hal->addLink('search', '/orders?id={order_id}');
$resource = new Hal(
'/orders/123',
array(
'total' => 30.00,
'currency' => 'USD',
)
);
$resource->addLink('customer', '/customer/bob', array('title' => 'Bob Jones '));
$hal->addResource('order', $resource);
echo $hal->asJson();
echo $hal->asXml();
```
## Installation
The preferred method of installation is via packagist as this provides the PSR-0 autoloader functionality. The
following command will download and install the latest version of the Hal library into your project.
```
php composer.phar require nocarrier/hal
```
Alternatively, clone the project and install into your project manually.
## License
Nocarrier\Hal is licensed under the MIT license.
[1]: http://tools.ietf.org/html/draft-kelly-json-hal-05
## Usage
### Creating Hal Resources
A Hal resource can be created with no values set:
```php
$hal = new \Nocarrier\Hal();
```
with a URI for the resource:
```php
$hal = new \Nocarrier\Hal('/orders');
```
and also with an array of data:
```php
$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
```
Hal resources can also be created from existing XML or JSON documents:
```php
$hal = \Nocarrier\Hal::fromJson($jsonString);
```
```php
$hal = \Nocarrier\Hal::fromXml($xmlString);
```
```php
$hal = \Nocarrier\Hal::fromXml($simpleXMLElement);
```
The depth of embedded resources parsed with both these methods is controlled by
a second argument, which defaults to 0:
```php
$hal = \Nocarrier\Hal::fromJson($jsonString, 5);
```
### Getting Representations
The Hal resource can be formatted as JSON or XML:
```php
$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asJson();
```
which with a first argument of `true` for pretty printing:
```php
$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asJson(true);
```
gives:
```json
{
"customerId": "CUS1234",
"_links": {
"self": {"href": "/orders"}
}
}
```
and
```php
$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asXml(true);
```
gives:
```xml
CUS1234
```
### Data
The data can be set through `setData` and read with `getData`:
```php
$hal = new \Nocarrier\Hal('/orders');
$hal->setData(['customerId' => 'CUS1234']);
$hal->getData();
```
Using array keys in the data for the XML representation can be done by
prefixing the key with `@`:
```php
$hal = new \Nocarrier\Hal('/orders');
$hal->setData(['customerId' => ['CUS1234', '@type' => 'legacy']]);
```
gives:
```xml
```
The `@` is ignored if JSON is rendered:
```json
{
"customerId": {
"value": "CUS1234",
"type":" legacy"
},
"_links": {
"self": {"href": "/orders"}
}
}
```
### Links
Links can be added to the resource by providing the rel identifying them
and a URI:
```php
$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->addLink('next', '/orders?page=2');
$hal->addLink('search', '/orders?id={order_id}');
```
gives:
```json
{
"customerId": "CUS1234",
"_links": {
"self": {
"href": "/orders"
},
"next": {
"href": "/orders?page=2"
},
"search": {
"href": "/orders?id={order_id}"
}
}
}
```
If a Hal object has been created from a response returned from elsewhere it
can be helpful to retrieve the links from it.
```php
$json = '{
"customerId": "CUS1234",
"_links": {
"self": {
"href": "/orders"
},
"next": {
"href": "/orders?page=2"
},
"search": {
"href": "/orders?id={order_id}"
}
}
}';
$hal = \Nocarrier\Hal::fromJson($json);
foreach($hal->getLinks() as $rel => $links) {
echo $rel."\n";
foreach($links as $link) {
echo (string) $link."\n";
}
}
```
```
next
/orders?page=2
search
/orders?id={order_id}
```
and
```php
$json = '{
"customerId": "CUS1234",
"_links": {
"self": {
"href": "/orders"
},
"next": {
"href": "/orders?page=2"
},
"search": {
"href": "/orders?id={order_id}"
}
}
}';
$hal = \Nocarrier\Hal::fromJson($json);
foreach($hal->getLink('next') as $link) {
echo (string) $link."\n";
}
```
outputs:
```
/orders?page=2
```
### Embedded Resources
As well as linking to resources so that the client can fetch them they can be
directly embedded in the resource.
```php
$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$resource = new \Nocarrier\Hal(
'/orders/123',
array(
'total' => 30.00,
'currency' => 'USD',
)
);
$resource->addLink('customer', '/customer/bob', array('title' => 'Bob Jones '));
$hal->addResource('order', $resource);
```
outputs:
```json
{
"customerId": "CUS1234",
"_links": {
"self": {
"href": "/orders"
}
},
"_embedded": {
"order": [
{
"total": 30,
"currency": "USD",
"_links": {
"self": {
"href": "/orders/123"
},
"customer": {
"href": "/customer/bob",
"title": "Bob Jones "
}
}
}
]
}
}
```