Wallogit.com
2017 © Pedro Peláez
Tools that can build differient representations of objects
Represent provides a serialization layer that can create and configure different representations of resources. When implementing a web service, having dedicated layer of that service control the representation of resources will provide a high degree of flexibility. In the context of a RESTful web service, REST embodies a set of design constraints. Two concepts lie underneath the technologies that have evolved from the design constraints of REST. Resources, and Representations., (*1)
Creating different representations of resources can be as simple as letting a client decide what format it would like to receive. Or it can get more complicated, such as controlling what properties of a resource should get included in a response. Represent packages all of this functionality together., (*2)
Your application should interact with Represent's serializers. Currently, a GenericSerializer and a HalSerializer exist. These classes handle preparing a specific representation of a given object and returning the data in a serialized format (currently JSON only). These serializers use builders to construct the desired representation. The most important Builder is the GenericRepresentation Builder. This is the entry point for all representations. The GenericBuilder handles parsing out the configuration for a class (currently given in annotations) and creates a representation composed of stdClass objects, arrays, and primitive type values. Format specific builders, such as the HalBuilder, take a Generic Representation and modify it comply with a specific format's standards. In the case of Hal, handling _links and _embedded. You can interact with the builders directly, however, only interacting with the serializers can reduce complexity in your application and help keep the representation layer separated., (*3)
Configuration that always gets used to create a Generic Representation. All of these options will work with any specific format builder. Currently, Represent only supports class configuration with annotations. All examples will show annotations., (*4)
The following annotations function at the class level:, (*5)
This gets set at the class level and can either be whiteList or blackList. This tells The GenericRepresentationBuilder what properties to either include or exclude.
* whiteList: all properties included by default unless they are marked hidden
* blackList: all properties excluded by default unless they are marked with show, (*6)
NOTE: if an exclusion policy is not specified, whiteList is used by default, (*7)
Example:, (*8)
use Represent\Annotations as Represent; /** * @Represent\ExclusionPolicy(policy="whiteList") */ class Car
The following annotations function at the property level:, (*9)
Only used when a class's exclusion policy is set to whiteList. Can be used to hide a property from all representations., (*10)
Example (excludes vinNumber):, (*11)
use Represent\Annotations as Represent;
/**
* @Represent\ExclusionPolicy(policy="whiteList")
*/
class Car
{
public $make;
public $model;
public $dateBuilt;
/**
* @Represent\Hide()
*/
private $vinNumber;
}
Only used when a class's exclusion policy is set to blackList. Can be used to show properties in representations., (*12)
Example (shows make and model):, (*13)
use Represent\Annotations as Represent
/**
* @Represent\ExclusionPolicy(policy="blackList")
*/
class Car
{
/**
* @Represent\Show()
*/
public $make;
/**
* @Represent\Show()
*/
public $model;
public $dateBuilt;
private $vinNumber;
}
```
### Property
Used to control the serialized name and data type of the value.
Example (renames `dateBuilt` to `year` and forces it to integer:
```php
use Represent\Annotations as Represent
class Car
{
public $make;
public $model;
/**
* @Represent\Property(name="year", type="integer")
*/
public $dateBuilt;
private $vinNumber
}
```
### View
Used to control specific views of resources. A view of a resource is like a particular context that can get represented. Anything excluded via the exclusion policy will get excluded. Properties that do not have a view will always show up, if the exclusion policy allows. Properties with a view will only show up when that view is represented.
Example (the `vinNumber` will only represented in the `owner` view):
```php
use Represent\Annotations as Represent
class Car
{
public $make;
public $model;
public $dateBuilt;
/**
* @Represent\View(name={"owner"})
*/
private $vinNumber;
}
The following configuration options only work with the Hal Builder and configure options specific to the Hal Format (_links and _embedded)., (*14)
The following annotations function at the class level:, (*15)
LinkCollection the container for all of the Links that should be included in _links. Currently links are all generated using the SymfonyUrlGenerator. The links uri property takes a route name. Parameters can be defined with expressions using The Expression Language, (*16)
Example yields the following json:, (*17)
use Represent\Annotations as Represent;
/**
* @Represent\LinkCollection(links={
* @Represent\Link(
* name="self",
* uri="get_car_by_ID",
* parameters={"id" = "expr('object->id')" }
* )
* })
*/
class Car
{
public $id;
public $make;
public $model;
}
{
"id":1,
"make":"dodge",
"model":"neon",
"_links":{
"self":{
"href":"www.mysite.com/car/1"
}
}
}
The following annotations function at the property level:, (*18)
Causes properties to show up in _embedded and NOT as properties on the object itself., (*19)
Example yields the following json:, (*20)
```php use Represent\Annotations as Represent, (*21)
class Car { /* * @Represent\Embedded() */ public $type, (*22)
public $dateBuilt;
}, (*23)
class Type { public $make;, (*24)
public $model;
}, (*25)
```json
{
"dateBuilt":"1989",
"_embedded":{
"type": {
"make":"Dodge",
"model":"Neon"
}
}
}
use Represent\Annotations as Represent; /** * @Represent\ExclusionPolicy(policy="whiteList") */ class Car
| Property | Required | Content |
|---|---|---|
| policy | Yes | ('whiteList' or 'blackList') |
use Represent\Annotations as Represent;
/**
* @Represent\ExclusionPolicy(policy="whiteList")
*/
class Car
{
/**
* @Represent\Hide()
*/
private $vinNumber;
}
| Property | Required | Content |
|---|---|---|
| n/a | n/a | n/a |
use Represent\Annotations as Represent
/**
* @Represent\ExclusionPolicy(policy="blackList")
*/
class Car
{
/**
* @Represent\Show()
*/
public $make;
}
| Property | Required | Content |
|---|---|---|
| n/a | n/a | n/a |
```php use Represent\Annotations as Represent, (*26)
class Car { public $make;, (*27)
public $model; /** * @Represent\Property(name="year", type="integer") */ public $dateBuilt; private $vinNumber
}, (*28)
| Property | Required | Content | |----------|----------|---------------------------------------------------| | Name | No | string | | Type | No | string (integer or string or boolean or datetime) | #### @View ```php use Represent\Annotations as Represent class Car { public $make; public $model; public $dateBuilt; /** * @Represent\View(name={"owner"}) */ private $vinNumber; }
| Property | Required | Content |
|---|---|---|
| name | Yes | array (strings) |
use Represent\Annotations as Represent;
/**
* @Represent\LinkCollection(links={
* @Represent\Link(
* name="self",
* uri="get_car_by_ID",
* parameters={"id" = "expr('object->id')" }
* )
* })
*/
class Car
{
public $id;
public $make;
public $model;
}
@LinkCollection, (*29)
| Property | Required | Content |
|---|---|---|
| links | Yes | Array (Link) |
@Link, (*30)
| Property | Required | Content |
|---|---|---|
| name | yes | string |
| uri | yes | string |
| parameters | no | array (key,value) |
| views | no | array (string) |
| absolute | no | boolean |
```php use Represent\Annotations as Represent, (*31)
class Car { /* * @Represent\Embedded() */ public $type, (*32)
public $dateBuilt;
} ```, (*33)
| Property | Required | Content |
|---|---|---|
| n/a | n/a | n/a |
Tools that can build differient representations of objects
MIT
api rest hypermedia representor