{"id":13623972,"url":"https://github.com/blongden/hal","last_synced_at":"2025-06-19T15:03:45.705Z","repository":{"id":2891998,"uuid":"3899458","full_name":"blongden/hal","owner":"blongden","description":"application/hal builder / formatter for PHP 5.4+","archived":false,"fork":false,"pushed_at":"2021-09-10T15:06:14.000Z","size":216,"stargazers_count":203,"open_issues_count":0,"forks_count":40,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-07T14:44:31.626Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"BashtonLtd/apt-transport-s3","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blongden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-04-02T10:07:36.000Z","updated_at":"2024-07-21T13:50:52.000Z","dependencies_parsed_at":"2022-07-21T23:02:19.827Z","dependency_job_id":null,"html_url":"https://github.com/blongden/hal","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blongden%2Fhal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blongden%2Fhal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blongden%2Fhal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blongden%2Fhal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blongden","download_url":"https://codeload.github.com/blongden/hal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249148240,"owners_count":21220500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:01:37.472Z","updated_at":"2025-04-15T20:32:53.684Z","avatar_url":"https://github.com/blongden.png","language":"PHP","readme":"Nocarrier\\Hal\n=============\n\n[![Build Status](https://secure.travis-ci.org/blongden/hal.png)](http://travis-ci.org/blongden/hal)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/blongden/hal/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/blongden/hal/?branch=master)\n\nThis is a library for creating documents in the [application/hal+json and application/hal+xml][1] hypermedia formats\n\nIt requires PHP 5.4 or later.\n\n```php\n\u003c?php\nrequire_once 'vendor/autoload.php';\n\nuse Nocarrier\\Hal;\n\n$hal = new Hal('/orders');\n$hal-\u003eaddLink('next', '/orders?page=2');\n$hal-\u003eaddLink('search', '/orders?id={order_id}');\n\n$resource = new Hal(\n    '/orders/123',\n    array(\n        'total' =\u003e 30.00,\n        'currency' =\u003e 'USD',\n    )\n);\n\n$resource-\u003eaddLink('customer', '/customer/bob', array('title' =\u003e 'Bob Jones \u003cbob@jones.com\u003e'));\n$hal-\u003eaddResource('order', $resource);\necho $hal-\u003easJson();\necho $hal-\u003easXml();\n```\n\n## Installation\n\nThe preferred method of installation is via packagist as this provides the PSR-0 autoloader functionality. The\nfollowing command will download and install the latest version of the Hal library into your project.\n\n```\nphp composer.phar require nocarrier/hal\n```\n\nAlternatively, clone the project and install into your project manually.\n\n## License\n\nNocarrier\\Hal is licensed under the MIT license.\n\n[1]: http://tools.ietf.org/html/draft-kelly-json-hal-05\n\n## Usage\n\n### Creating Hal Resources\n\nA Hal resource can be created with no values set:\n\n```php\n$hal = new \\Nocarrier\\Hal();\n```\nwith a URI for the resource:\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders');\n```\n\nand also with an array of data:\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders', ['customerId' =\u003e 'CUS1234']);\n```\n\nHal resources can also be created from existing XML or JSON documents:\n\n```php\n$hal = \\Nocarrier\\Hal::fromJson($jsonString);\n```\n\n```php\n$hal = \\Nocarrier\\Hal::fromXml($xmlString);\n```\n\n```php\n$hal = \\Nocarrier\\Hal::fromXml($simpleXMLElement);\n```\n\nThe depth of embedded resources parsed with both these methods is controlled by\na second argument, which defaults to 0:\n\n```php\n$hal = \\Nocarrier\\Hal::fromJson($jsonString, 5);\n```\n\n### Getting Representations\n\nThe Hal resource can be formatted as JSON or XML:\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders', ['customerId' =\u003e 'CUS1234']);\n$hal-\u003easJson();\n```\n\nwhich with a first argument of `true` for pretty printing:\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders', ['customerId' =\u003e 'CUS1234']);\n$hal-\u003easJson(true);\n```\n\ngives:\n\n```json\n{\n    \"customerId\": \"CUS1234\",\n    \"_links\": {\n        \"self\": {\"href\": \"/orders\"}\n    }\n}\n```\n\nand\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders', ['customerId' =\u003e 'CUS1234']);\n$hal-\u003easXml(true);\n```\n\ngives:\n\n```xml\n\u003c?xml version=\"1.0\"?\u003e\n\u003cresource href=\"/orders\"\u003e\n    \u003ccustomerId\u003eCUS1234\u003c/customerId\u003e\n\u003c/resource\u003e\n```\n\n### Data\n\nThe data can be set through `setData` and read with `getData`:\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders');\n$hal-\u003esetData(['customerId' =\u003e 'CUS1234']);\n$hal-\u003egetData();\n```\n\nUsing array keys in the data for the XML representation can be done by\nprefixing the key with `@`:\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders');\n$hal-\u003esetData(['customerId' =\u003e ['CUS1234', '@type' =\u003e 'legacy']]);\n```\n\ngives:\n\n```xml\n\u003c?xml version=\"1.0\"?\u003e\n\u003cresource href=\"/orders\"\u003e\n    \u003ccustomerId value=\"CUS1234\" type=\"legacy\"/\u003e\n\u003c/resource\u003e\n```\n\nThe `@` is ignored if JSON is rendered:\n\n```json\n{\n    \"customerId\": {\n        \"value\": \"CUS1234\",\n        \"type\":\" legacy\"\n    },\n    \"_links\": {\n        \"self\": {\"href\": \"/orders\"}\n    }\n}\n```\n\n### Links\n\nLinks can be added to the resource by providing the rel identifying them\nand a URI:\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders', ['customerId' =\u003e 'CUS1234']);\n$hal-\u003eaddLink('next', '/orders?page=2');\n$hal-\u003eaddLink('search', '/orders?id={order_id}');\n```\n\ngives:\n\n```json\n{\n    \"customerId\": \"CUS1234\",\n    \"_links\": {\n        \"self\": {\n            \"href\": \"/orders\"\n        },\n        \"next\": {\n            \"href\": \"/orders?page=2\"\n        },\n        \"search\": {\n            \"href\": \"/orders?id={order_id}\"\n        }\n    }\n}\n```\n\nIf a Hal object has been created from a response returned from elsewhere it\ncan be helpful to retrieve the links from it.\n\n```php\n$json = '{\n     \"customerId\": \"CUS1234\",\n     \"_links\": {\n         \"self\": {\n             \"href\": \"/orders\"\n         },\n         \"next\": {\n             \"href\": \"/orders?page=2\"\n         },\n         \"search\": {\n             \"href\": \"/orders?id={order_id}\"\n         }\n     }\n }';\n\n$hal = \\Nocarrier\\Hal::fromJson($json);\n\nforeach($hal-\u003egetLinks() as $rel =\u003e $links) {\n    echo $rel.\"\\n\";\n    foreach($links as $link) {\n        echo (string) $link.\"\\n\";\n    }\n}\n```\n\n```\nnext\n/orders?page=2\nsearch\n/orders?id={order_id}\n```\nand\n\n```php\n$json = '{\n     \"customerId\": \"CUS1234\",\n     \"_links\": {\n         \"self\": {\n             \"href\": \"/orders\"\n         },\n         \"next\": {\n             \"href\": \"/orders?page=2\"\n         },\n         \"search\": {\n             \"href\": \"/orders?id={order_id}\"\n         }\n     }\n }';\n$hal = \\Nocarrier\\Hal::fromJson($json);\nforeach($hal-\u003egetLink('next') as $link) {\n    echo (string) $link.\"\\n\";\n}\n```\n\noutputs:\n\n```\n/orders?page=2\n```\n\n### Embedded Resources\n\nAs well as linking to resources so that the client can fetch them they can be\ndirectly embedded in the resource.\n\n```php\n$hal = new \\Nocarrier\\Hal('/orders', ['customerId' =\u003e 'CUS1234']);\n\n$resource = new \\Nocarrier\\Hal(\n    '/orders/123',\n    array(\n        'total' =\u003e 30.00,\n        'currency' =\u003e 'USD',\n    )\n);\n\n$resource-\u003eaddLink('customer', '/customer/bob', array('title' =\u003e 'Bob Jones \u003cbob@jones.com\u003e'));\n$hal-\u003eaddResource('order', $resource);\n```\noutputs:\n\n```json\n{\n    \"customerId\": \"CUS1234\",\n    \"_links\": {\n        \"self\": {\n            \"href\": \"/orders\"\n        }\n    },\n    \"_embedded\": {\n        \"order\": [\n            {\n                \"total\": 30,\n                \"currency\": \"USD\",\n                \"_links\": {\n                    \"self\": {\n                        \"href\": \"/orders/123\"\n                    },\n                    \"customer\": {\n                        \"href\": \"/customer/bob\",\n                        \"title\": \"Bob Jones \u003cbob@jones.com\u003e\"\n                    }\n                }\n            }\n        ]\n    }\n}\n```\n","funding_links":[],"categories":[" REST API","Servers","目录","Table of Contents","PHP","REST和API","REST and API"],"sub_categories":["PHP","API"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblongden%2Fhal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblongden%2Fhal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblongden%2Fhal/lists"}