Need help with hal?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

blongden
199 Stars 37 Forks MIT License 244 Commits 0 Opened issues

Description

application/hal builder / formatter for PHP 5.4+

Services available

!
?

Need anything else?

Contributors list

# 55,453
PHP
Kuberne...
Shell
guzzle
78 commits
# 346,183
PHP
standal...
Shell
fluent-...
5 commits
# 69,206
PHP
Symfony
Compose...
guzzle
4 commits
# 17,520
PHP
PHPUnit
stub
curl
4 commits
# 10,520
PHP
oauth2
uuid
php7
3 commits
# 11,538
PHP
Symfony
reactph...
HTML
3 commits
# 26,469
woocomm...
php7
symfony...
google-...
2 commits
# 23,285
PHP
CSS
amp-htm...
recaptc...
2 commits
# 688,857
PHP
Ruby
2 commits
# 370,822
PHP
Shell
2 commits
# 432,957
PHP
asteris...
ami
CSS
2 commits
# 90,186
smtp-se...
travis-...
Symfony
Less
2 commits
# 129,551
PHP
HTML
chef-co...
chef
2 commits
# 646,229
PHP
2 commits
# 423,318
PHP
Symfony
symfony...
HTML
1 commit
# 720,669
PHP
1 commit
# 29,121
Ruby
Compose...
wordpre...
Objecti...
1 commit
# 630,681
PHP
HTML
1 commit
# 14,878
Go
golang
git-cli...
Git
1 commit
# 162,770
PHP
CSS
iOS
Shell
1 commit

Nocarrier\Hal

Build Status Scrutinizer Code Quality

This is a library for creating documents in the application/hal+json and application/hal+xml hypermedia formats

It requires PHP 5.4 or later.

use Nocarrier\Hal;

$hal = new Hal('/orders'); $hal->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.

Usage

Creating Hal Resources

A Hal resource can be created with no values set:

$hal = new \Nocarrier\Hal();

with a URI for the resource:

$hal = new \Nocarrier\Hal('/orders');

and also with an array of data:

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);

Hal resources can also be created from existing XML or JSON documents:

$hal = \Nocarrier\Hal::fromJson($jsonString);
$hal = \Nocarrier\Hal::fromXml($xmlString);
$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:

$hal = \Nocarrier\Hal::fromJson($jsonString, 5);

Getting Representations

The Hal resource can be formatted as JSON or XML:

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asJson();

which with a first argument of

true
for pretty printing:
$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asJson(true);

gives:

{
    "customerId": "CUS1234",
    "_links": {
        "self": {"href": "/orders"}
    }
}

and

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->asXml(true);

gives:

    CUS1234

Data

The data can be set through

setData
and read with
getData
:
$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

@
:
$hal = new \Nocarrier\Hal('/orders');
$hal->setData(['customerId' => ['CUS1234', '@type' => 'legacy']]);

gives:

    

The

@
is ignored if JSON is rendered:
{
    "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:

$hal = new \Nocarrier\Hal('/orders', ['customerId' => 'CUS1234']);
$hal->addLink('next', '/orders?page=2');
$hal->addLink('search', '/orders?id={order_id}');

gives:

{
    "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.

$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

$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.

$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:

{
    "customerId": "CUS1234",
    "_links": {
        "self": {
            "href": "/orders"
        }
    },
    "_embedded": {
        "order": [
            {
                "total": 30,
                "currency": "USD",
                "_links": {
                    "self": {
                        "href": "/orders/123"
                    },
                    "customer": {
                        "href": "/customer/bob",
                        "title": "Bob Jones "
                    }
                }
            }
        ]
    }
}

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.