Entities
, (*1)
Entities are elements that represent your data. Some frameworks call them models, but they are similar, although entities don't deal themselves directly with the database. They should always be stored in the Entities folder of a bundle., (*2)
, (*3)
Installation
If you are working on an Asgard project you don't need to install this library as it is already part of the standard libraries., (*4)
composer require asgard/entity 0.*
, (*5)
Instance
An entity is instantiated like:, (*6)
$article = new Article;
You can also pass default values:, (*7)
$article = new Article(['title'=>'hello!']);
, (*8)
Definition
An entity is defined by a class:, (*9)
<?php
class Article extends \Asgard\Entity\Entity {
public static function definition($definition) {
$definition->properties = [
'title' => [
'required'=>true
],
'content' => 'text',
'posted_on' => 'date'
]
}
}
Here we have defined the entity Article, with 3 properties: title, content and posted_on. title has the default type "string" (text with less than 255 characters), content has the type "text", while posted_on is a date.
There are actually 4 different ways to define a property:, (*10)
$definition->properties = [
'title'
]
#or
$definition->properties = [
'title' => 'string'
]
#or
$definition->properties = [
'title' => [
'type' => 'string',
...
]
]
#or
$definition->properties = [
'title' => new \Asgard\Entity\Property\StringProperty([..])
]
The type is optional and defaults to "string". At the moment you can use the types: "boolean", "date", "datetime", "double", "email", "file", "image", "integer", "text" and "string"., (*11)
Each type affects the property in the way the data are stored in the entity, validated or even persisted in the database., (*12)
You can access an entity definition through:, (*13)
$entity->getDefinition()
The entity properties are accessed like this:, (*14)
$article->title
#or
$article->get('title')
and editable like this:, (*15)
$article->title = 'hello';
$article->set('title', 'hello')
or set multiple properties at once:, (*16)
$article->set(['title'=>'hello', 'content'=>'everyone'])
, (*17)
Property types
boolean, (*18)
'property_name' => 'boolean'
The property only returns true|false., (*19)
date, (*20)
'property_name' => 'date'
The property returns a \Carbon\Carbon object but only shows date when converted to string., (*21)
datetime, (*22)
'property_name' => 'datetime
The property returns a \Carbon\Carbon object., (*23)
double, (*24)
'property_name' => 'double'
The property returns a double number., (*25)
email, (*26)
'property_name' => 'email'
The property returns an email address and is only valid if a valid email address was provided.
pos
file, (*27)
'property_name' => [
'type' => 'file',
'web' => true
]
The property returns a \Asgard\File\File object., (*28)
The web parameter must be set to true if you want to store the file as a web asset., (*29)
integer, (*30)
'property_name' => 'integer'
The property returns an integer number., (*31)
text, (*32)
'property_name' => 'text'
The property returns text with more than 255 characters., (*33)
string, (*34)
'property_name'
The property returns text with less than 255 characters., (*35)
, (*36)
Multiple values per property
A property can even have multiple values (array).
For that, add the multiple parameter like so:, (*37)
$definition->properties = [
'title' => [
'many' => true
]
]
Now, $article->title will return a Asgard\Entity\ManyCollection object which can be used like an array:, (*38)
$article->title[] = 'new title';
$article->title[0] //new title
, (*39)
Property hooks
You can set a hook for every time you update a property value:, (*40)
$definition->properties = [
'title' => [
'hooks' => [
'set' => function($value, $entity) {
if($value < 10)
$value = 10;
return $value;
}
]
]
]
The return result will be used as the new property value., (*41)
, (*42)
Validation
Properties can have all kinds of parameters, including validation rules. For example:, (*43)
$definition->properties = [
'title' => [
'validation' => [
'maxlength' => 10,
'minlength' => 5
]
]
]
To validate your entity use:, (*44)
$article->valid() #returns true of valid, otherwise false
$article->errors() #returns an array of errors
Validation groups, (*45)
$definition->properties = [
'title' => [
'validation' => [
'maxlength' => 10,
'minlength' => [
5,
'groups' => ['registration']
]
]
]
]
With a title with less than 5 characters:, (*46)
$article->valid(['registration']); #false
$article->valid(); #true
For more information on validation, see to the validation section., (*47)
, (*48)
Behaviors
Entities can be enhanced by behaviors. Behaviors can add methods and properties, and modify their current behaviors with Hooks.
For example, to make entities sortable, add the following code to the definition method:, (*49)
$definition->behaviors = [
new \Asgard\Behaviors\SortableBehavior()
];
This adds a property "position" for the Article entity, and two methods: moveAfter($entity) and moveBefore($entity)., (*50)
You can also pass parameters to behaviors:, (*51)
$definition->behaviors = [
new \Asgard\Behaviors\SortableBehavior('category_id')
];
If you want to sort articles only between the ones that have the same category_id., (*52)
Please note that this behavior will only work properly if used with the ORMBehavior., (*53)
, (*54)
I18N
Entities handle internationalization by default. Simply add the parameter i18n to a property:, (*55)
$definition->properties = [
'title' => [
'i18n' => true
]
]
From now on, title will have a different version for all the languages that are in the configuration file., (*56)
To get the default language:, (*57)
$article->title
To get the value in a specific language:, (*58)
$article->get('title', 'fr')
To get the values in all the available languages:, (*59)
$article->get('title', 'all')
And to set values:, (*60)
$article->title = 'hello'
$article->set('title', 'bonjour', 'fr')
$article->set(['title'=>'bonjour', 'content'=>'tout le monde'], 'fr')
To know if an entity has i18n properties, use:, (*61)
$entityDefinition->is18N()
#or
Article::isI18N()
To change an entity instance's default language:, (*62)
$entity->setLocale('fr');
Get all locales of an entity:, (*63)
$entity->getLocales();
Translate an entity into another locale:, (*64)
$frEntity = $enEntity->translate('fr');
#$enEntity->title = 'Hello'
#$frEntity->title = 'Bonjour'
Validation, (*65)
$entity->validI18N(['fr', 'en'], $validationGroups=[]);
Validates the entity and the translations of the given locales. If no locales are given, all the entity locales are used by default., (*66)
To get the errors:, (*67)
$entity->errorsI18N(['fr', 'en'], $validationGroups=[]);
, (*68)
Serialization
Entities can be serialized into arrays or json., (*69)
To create a serializer:, (*70)
$serializer = new \Asgard\Entity\Serializer;
#or
If you use the default serializer, calling methods directly from the Entity class has the same effect. For example:, (*71)
$entity->toArrayRaw($depth=0);
is the same as:, (*72)
$serializer->toArrayRaw($entity, $depth=0);
toArrayRaw, (*73)
$serializer->toArrayRaw($entity, $depth=0);
$depth defines how many levels of relationships to include in the serialization, (*74)
toArrayRaw will return an array containing the values of all properties., (*75)
toArray, (*76)
$serializer->toArray($entity, $depth=0);
The difference with toArrayRaw, is that toArray will convert all properties into strings and arrays. Including related entities., (*77)
toJSON, (*78)
$serializer->toJSON($entity, $depth=0);
This will return a JSON version of toArray., (*79)
toArrayRawI18N, (*80)
$serializer->toArrayRawI18N($entity, $locales=[], $depth=0);
Same as toArrayRaw, but includes the translations as well., (*81)
toArrayI18N, (*82)
$serializer->toArrayI18N($entity, $locales=[], $depth=0);
Same as toArrayRaw, but includes the translations as well., (*83)
toJSONI18N, (*84)
$serializer->toArrayI18N($entity, $locales=[], $depth=0);
Same as toJSON, but includes the translations as well., (*85)
arrayToJSONI18N, (*86)
$serializer->arrayToJSONI18N($entities, $locales=[], $depth=0);
Calls toJSONI18N on an array of entities., (*87)
arrayToJSON, (*88)
$serializer->arrayToJSON($entities, $locales=[], $depth=0);
Calls toJSON on an array of entities., (*89)
, (*90)
Old/New
To verify is an entity is old (persisted), use:, (*91)
$entity->isOld();
#or
$entity->isNew();
Contributing
Please submit all issues and pull requests to the asgardphp/asgard repository., (*92)
License
The Asgard framework is open-sourced software licensed under the MIT license, (*93)
Wallogit.com
