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.
- Resources: Data models usually compose the resources offered by a web service. In a broader sense, a resource is anything important enough to be referred to as a thing in and of itself. For a RESTful web service, URI's describe resources. GET /car/1 described a car resource.
- Representations: A representation is any machine readable document that contains any information about a resource. For RESTful services, a representation should also explain the current state of the resource.
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.
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.
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.
The following annotations function at the class level:
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 markedhiddenblackList: all properties excluded by default unless they are marked withshow
NOTE: if an exclusion policy is not specified, whiteList is used by default
Example:
use Represent\Annotations as Represent;
/**
* @Represent\ExclusionPolicy(policy="whiteList")
*/
class CarThe following annotations function at the property level:
Only used when a class's exclusion policy is set to whiteList. Can be used to hide a property from all representations.
Example (excludes vinNumber):
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.
Example (shows make and model):
use Represent\Annotations as Represent
/**
* @Represent\ExclusionPolicy(policy="blackList")
*/
class Car
{
/**
* @Represent\Show()
*/
public $make;
/**
* @Represent\Show()
*/
public $model;
public $dateBuilt;
private $vinNumber;
}Used to control the serialized name and data type of the value.
Example (renames dateBuilt to year and forces it to integer:
use Represent\Annotations as Represent
class Car
{
public $make;
public $model;
/**
* @Represent\Property(name="year", type="integer")
*/
public $dateBuilt;
private $vinNumber
}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):
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).
The following annotations function at the class level:
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
Example yields the following json:
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:
Causes properties to show up in _embedded and NOT as properties on the object itself.
Example yields the following json:
use Represent\Annotations as Represent
class Car
{
/*
* @Represent\Embedded()
*/
public $type
public $dateBuilt;
}
class Type
{
public $make;
public $model;
}{
"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 |
use Represent\Annotations as Represent
class Car
{
public $make;
public $model;
/**
* @Represent\Property(name="year", type="integer")
*/
public $dateBuilt;
private $vinNumber
}| Property | Required | Content |
|---|---|---|
| Name | No | string |
| Type | No | string (integer or string or boolean or datetime) |
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
| Property | Required | Content |
|---|---|---|
| links | Yes | Array (Link) |
@Link
| Property | Required | Content |
|---|---|---|
| name | yes | string |
| uri | yes | string |
| parameters | no | array (key,value) |
| views | no | array (string) |
| absolute | no | boolean |
use Represent\Annotations as Represent
class Car
{
/*
* @Represent\Embedded()
*/
public $type
public $dateBuilt;
}| Property | Required | Content |
|---|---|---|
| n/a | n/a | n/a |