Annotations

As Gamine uses annotations to determine how to manage your php objects, you will need to annotate your objects properly. Here is a list of available annotations, and how to use them.

@Column

Description: This is the default annotation for any object property you want to store. Gamine will only store properties annotated with @Column, and only properties annotated with @Column will be autopopulated.

Usage: /** @Column */ protected $_title;

Properties:

• string name - This is the name used when communication with the backend. Ex: if the object property is $first_name, but the key used in the json encoded array when communicating with the REST-backend is firstName, you can specify this in the name property.

@Id

Description: This indicates that the specified property is the identificator for this object. Gamine does not support composite IDs, so an object can only have one property annotated with @Id. The @Id annotation must be combined with a @Column annotation.

Usage: ` /**

• @Id
• @Column */ protected $_id; `

Properties: This annotation does not have any properties.

@ReadOnly

Description: This indicates that the property will not be saved, but will be populated when the object is retrieved from the database.

Usage: ` /**

• @ReadOnly
• @Column */ protected $_password; `

Properties: This annotation does not have any properties.

@Extract

Description: This is an annotation that can be used if you want to extract the value of the original data out to other properties on the object and handle them individually. These properties are then used to build the stored data value when the object is saved back to the storage backend. Ex: Your REST user data array has a "name" subarray that consists of "first_name", "last_name" and "username" keys. You want to extract these into $firstName, $lastName and $nickname, respectively.

Usage: ` /**

• @Column
• @Extract(columns={"first_name"="firstName", "last_name"="lastName", "username"="nickname"} */ protected $name; protected $firstName; protected $lastName; protected $nickname; `

Properties:

• array columns (required) - This is the data_array_key => property mapped list describing which keys from the data array maps to which object properties. Note that the properties you extract the data to should not have a @Column annotation, as these are not stored separately.
• boolean preserve_items - This property indicates whether or not the annotated property should contain the elements they have been extracted to other properties. Defaults to true

@Relates

Description: This indicates that the property is related to another backend resource, and will be lazyloaded.

Ex: There are several ways this property can be used:

• The current object has a value stored in this property that is used to retrieve the related object (one-to-one). In this case, the property must also have a @Column annotation so the stored value can be autopopulated.
• The current object has a value in this property that is used to retrieve several related objects (one-to-many). Same as above, the property must also have a @Column annotation so the stored value can be autopopulated.
• The current object has no value in this property but its id property is used to retrieve the related object (one-to-many)

Usage: ` /**

• @Relates(entity="product", collection=false, related_by="productId") */ protected $_product; `

` /**

• @Relates(entity="product", collection=true, related_by="productId") */ protected $_products; `

Properties:

• string entity (required) - This is the entity defined in the services.yml file. The services.yml configuration decides how to retrieve and manage the object / objects.
• boolean collection - This property defines whether the property relates to one or many objects. This also decides whether the entity or collection backend endpoint is used.
• string related_by - This is the object property from the related object that defines the relation back to this object (Note that this is the property, and not the data array key from the related object - Gamine will look at the annotation for the related property to determine how to load the related object / objects).
• boolean relative - This determines whether the location used when loading the related object is relative to the unique backend endpoint location of the current object, or if the backend endpoint used to retrieve the related object is a separate collection / entity endpoint. Ex: If a user has several teams, the related team data may be retrieved via an endpoint that looks like this: /user/12/teams (relative=true), whereas if the user has one group, the endpoint may look like this: /team/4 (relative=false).

@SubModel

Description: This means that the data from this property is used to populate a related object or an array of related objects. The data returned from the endpoint should be identical to the data used when loading the specified related object standalone. This property does not need to have an associated @Column annotation.

Usage: ` /**

• @SubModel(entity="address") */ protected $_address; `

` /**

• @SubModel(entity="address", collection=true) */ protected $_addresses; `

Properties:

• string entity - Same as the @Relates annotation, this must match an entity resource configured in services.yml
• boolean collection - Whether or not this is an array of submodel objects, or just a single object. Default: false
• string identifier - When set up as an array of submodel objects, the identifier property can be used to specify that the array should be keyed using values from this object property. Ex: If your submodel objects have a $type property, you can set identifier="type" to specify that the submodel array should be keyed by the value of each object's $type property.
• string extract_mode - This specifies how the related object is represented when saved back to the backend endpoint. It defaults to "full" which means that it will send back a complete array representation (similar to storing the object normally) of the object. Setting extract_mode to "min" will only send back changed properties, together with the id of the object.