Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mixerapi/hal-view
A Hypertext Application Language (HAL+JSON) View for CakePHP [READ-ONLY]
https://github.com/mixerapi/hal-view
cakephp hal hal-json hateoas php
Last synced: about 1 month ago
JSON representation
A Hypertext Application Language (HAL+JSON) View for CakePHP [READ-ONLY]
- Host: GitHub
- URL: https://github.com/mixerapi/hal-view
- Owner: mixerapi
- License: other
- Created: 2020-07-26T16:50:34.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-03-25T23:50:19.000Z (9 months ago)
- Last Synced: 2024-11-01T02:18:10.220Z (about 2 months ago)
- Topics: cakephp, hal, hal-json, hateoas, php
- Language: PHP
- Homepage: https://mixerapi.com/plugins/hal-view
- Size: 101 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# MixerApi HAL View
[](https://packagist.org/packages/mixerapi/hal-view)
[](https://github.com/mixerapi/mixerapi-dev/actions?query=workflow%3ABuild)
[](https://coveralls.io/github/mixerapi/mixerapi-dev?branch=master)
[](http://mixerapi.com)
[](https://book.cakephp.org/4/en/index.html)
[](https://php.net/)
A Hypertext Application Language ([HAL+JSON](http://stateless.co/hal_specification.html)) View for CakePHP. This plugin
supports links, pagination, and embedded resources. Once setup any request with `application/hal+json` will be
rendered by this plugin.
## Table of Contents
- [Installation](#installation)
- [Setup](#setup)
- [Usage](#usage)
- [Serializing](#serializing)
## Installation
!!! note ""
You can skip this step if MixerAPI is installed.
```console
composer require mixerapi/hal-view
bin/cake plugin load MixerApi/HalView
```
Alternatively after composer installing you can manually load the plugin in your Application:
```php
# src/Application.php
public function bootstrap(): void
{
// other logic...
$this->addPlugin('MixerApi/HalView');
}
```
## Setup
Your controllers must be using the `RequestHandler` component. This is typically loaded in your `AppController`.
```php
# src/Controller/AppController.php
public function initialize(): void
{
parent::initialize();
$this->loadComponent('RequestHandler');
// other logic...
}
```
## Usage
For `_link.self.href` support you will need to implement `MixerApi\HalView\HalResourceInterface` on entities that you
want to expose as HAL resources. This informs the plugin that the Entity should be treated as a HAL resource and
provides the mapper with a `_link.self.href` URL:
```php
[
'href' => '/actors/' . $entity->get('id')
]
];
}
}
```
Now an HTTP GET to the `/actors/149` endpoint will render HAL using the CakePHP native serialization process:
```php
#src/Controller/ActorsController.php
public function view($id = null)
{
$this->request->allowMethod('get');
$actor = $this->Actors->get($id, [
'contain' => ['Films'],
]);
$this->set('actor', $actor);
$this->viewBuilder()->setOption('serialize', 'actor');
}
```
Example
```json
{
"_links": {
"self": {
"href": "/actors/149"
}
},
"id": 149,
"first_name": "RUSSELL",
"last_name": "TEMPLE",
"modified": "2006-02-15T04:34:33+00:00",
"_embedded": {
"films": [
{
"id": 53,
"title": "BANG KWAI",
"description": "A Epic Drama of a Madman And a Cat who must Face a A Shark in An Abandoned Amusement Park",
"release_year": "2006",
"language_id": 1,
"rental_duration": 5,
"rental_rate": "2.99",
"length": 87,
"replacement_cost": "25.99",
"rating": "NC-17",
"special_features": "Commentaries,Deleted Scenes,Behind the Scenes",
"modified": "2006-02-15T05:03:42+00:00"
"_links": {
"self": {
"href": "/films/53"
}
}
}
]
}
}
```
If your Entity does not implement the interface it will still be returned as HAL resource when serialized, but minus
the `_links` property. Collection requests will work without this interface as well, example:
```php
#src/Controller/ActorsController.php
public function index()
{
$this->request->allowMethod('get');
$actors = $this->paginate($this->Actors, [
'contain' => ['Films'],
]);
$this->set(compact('actors'));
$this->viewBuilder()->setOption('serialize', 'actors');
}
```
Example
```json
{
"_links": {
"self": {
"href": "/actors?page=3"
},
"next": {
"href": "/actors?page=4"
},
"prev": {
"href": "/actors?page=2"
},
"first": {
"href": "/actors?page=1"
},
"last": {
"href": "/actors?page=11"
}
},
"count": 20,
"total": 207,
"_embedded": {
"actors": [
{
"id": 1,
"first_name": "PENELOPE",
"last_name": "GUINESS",
"modified": "2006-02-15T04:34:33+00:00"
"_embedded": {
"films": [
{
"id": 1,
"title": "ACADEMY DINOSAUR",
"description": "A Epic Drama of a Feminist And a Mad Scientist who must Battle a Teacher in The Canadian Rockies",
"release_year": "2006",
"language_id": 1,
"rental_duration": 6,
"rental_rate": "0.99",
"length": 86,
"replacement_cost": "20.99",
"rating": "PG",
"special_features": "Deleted Scenes,Behind the Scenes",
"modified": "2006-02-15T05:03:42+00:00"
}
]
}
}
]
}
}
```
If the Actor and Film entities were implementing `MixerApi\HalView\HalResourceInterface` then the example above would
include the `_links` property for each serialized entity.
Try it out for yourself:
```console
# json
curl -X GET "http://localhost:8765/actors" -H "accept: application/hal+json"
```
## Serializing
Optionally, you can manually serialize data into HAL using `JsonSerializer`. This is the same class that the main HalJsonView uses. Example:
```php
use MixerApi\HalView\JsonSerializer;
# json
$json = (new JsonSerializer($data))->asJson(JSON_PRETTY_PRINT); // asJson argument is optional
# array
$hal = (new JsonSerializer($data))->getData();
# json with `_links.self.href` and pagination meta data
use Cake\Http\ServerRequest;
use Cake\View\Helper\PaginatorHelper;
$json = (new JsonSerializer($data, new ServerRequest(), new PaginatorHelper()))->asJson();
```