shingo-kumagai / siren-module
Requires
- php: >=5.5.0
- bear/resource: ~1.0
- bear/sunday: ~1.0
- danielgsims/php-siren: ~0.9
This package is not auto-updated.
Last update: 2024-10-26 18:43:46 UTC
README
WARNING: This is highly experimental stuff that isn't ready for production use yet.
Siren support for BEAR.Sunday
Siren renderer
It overrides default renderer and represents your resource in Siren format.
Siren [https://github.com/kevinswiber/siren]
Demo
Demo application using this module [https://github.com/shingo-kumagai/MyVendor.MySirenApi]
Entity
class (optional)
You can specify this optional value with @SirenClass
annotation.
@SirenClass("order")
properties (optional)
Properties are the response body of the resource object.
Entities
Add sub related resource entities using @SirenEmbedResource
annotation.
@SirenEmbedResource(rel="customer", src="app://self/customer?customerId={customerId}")
And then, you can embed the entity by request like below.
$this['customer']->addQuery(['customerId' => $customerId])->eager->request();
For sub related link entity use @SirenEmbedLink
annotation.
@SirenEmbedLink(rel="order-items", src="app://self/order/items?orderNumber={orderNumber}")
Actions
Action can be added using @SirenAction
annotation.
@SirenAction(src="app://self/order/items?orderNumber={orderNumber}", method="post")
The actual method defined as SirenAction
has to be annotated like below.
/** * @SirenName("add-item") * @SirenTitle("Add Item") * @SirenField(name="orderNumber", type="hidden", value="{orderNumber}") * @SirenField(name="productCode", type="text") * @SirenField(name="quantity", type="number") * * @param int $customerId * @return $this */ public function onPost($customerId) { // do something... return $this; }
name (required)
You need to define action name using @SirenName
annotation when you want to represent Action
title (optional)
This is optional. You can specify with @SirenTitle
annotation.
field (optional)
This is going to be controls of the action.
You can add user control for the action with @SirenField
annotation.
type (optional)
WIP
Links
@SirenLink(rel="previous", param="orderNumber")
@SirenLink(rel="next", param="orderNumber")
Example
Response
{ "class": [ "order" ], "properties": { "orderNumber": 42, "itemCount": 3, "status": "pending" }, "entities": [ { "href": "/customer?customerId=pj123", "rel": [ "customer" ], "class": [ "info", "customer" ], "properties": { "customerId": "pj123", "name": "Peter Joseph" } }, { "href": "/orderitems?orderNumber=42", "rel": [ "order-items" ], "class": [ "items", "collection" ] } ], "actions": [ { "name": "add-item", "href": "/orderitems?orderNumber=42", "method": "POST", "title": "Add Item", "type": "application/x-www-form-urlencoded", "fields": [ { "name": "orderNumber", "type": "hidden", "value": "42" }, { "name": "productCode", "type": "text" }, { "name": "quantity", "type": "number" } ] } ], "links": [ { "rel": [ "self" ], "href": "/orders?orderNumber=42" }, { "rel": [ "previous" ], "href": "/orders?orderNumber=41" }, { "rel": [ "next" ], "href": "/orders?orderNumber=43" } ] }