Download the PHP package webiny/entity without Composer
On this page you can find all versions of the php package webiny/entity. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download webiny/entity
More information about webiny/entity
Files in webiny/entity
Package entity
Short Description Webiny Entity Component
License MIT
Homepage http://www.webiny.com/
Informations about the package entity
Entity Component
Entity
component is an ODM layer for MongoDB. Entity classes created using this component will serve as the main building blocks for modules, forms, tables, etc.
Every entity attribute is a complex data type. There are no simple strings or integers. Even boolean
is a complex data type and has a separate class. This allows us to
generate a lot of code and interface elements automatically.
Install the component
The best way to install the component is using Composer.
For additional versions of the package, visit the Packagist page.
Supported attributes
boolean
char
integer
float
date
datetime
arr
object
dynamic
many2one
one2many
many2many
one2many
and many2many
attributes extend AbstractCollectionAttribute
class. These 2 attributes are the most complex because their value
is represented by EntityCollection
class, which is a wrapper for actual array of data returned from database. This wrapper allows us to implement lazy loading
and provide simple interface for counting data in result set (per page and total).
AbstractEntity
class, which operates on the database, is always returning instances of AbstractEntity
class.
Entity structure
An example code for entity structure:
Attributes many2one
, one2many
and many2many
are lazy loaded, which means, the actual values of these attributes is not loaded from database until you try to access it.
Access to attributes
To access attribute values you can use the following 2 approaches:
NOTE: you need to call getValue()
to get the actual value of the attribute.
If you try to echo or concatenate attributes (not values, but the actual attributes), __toString magic method will be triggered which will automatically call getValue()
method for you.
In case you are trying to access a value of a many2one
attribute:
Setting values
setOnce()
This method allows you to protect an attribute from being updated. You use this method to only allow your attribute to be populated when your new entity instance has no ID set (meaning it's a new instance).
After you save your new entity instance, all subsequent calls to populate()
will skip this attribute.
One2Many Attribute
This attribute's value is an instance of EntityCollection
. You can you is in foreach
loops, access values by numeric indexes and also call count()
method to find out the total number of items in the data set.
Mass populating One2ManyAttribute
There are different ways to populate One2Many attributes from, say, POST request.
1) Structure data as simple array of Entity IDs:
2) Structure data as array of arrays with Entity data. If array contains id
, an existing instance will be loaded, and populated with any data specified in the array (useful for updating existing Entities):
3) Structure data as array
or EntityCollection
of AbstractEntity
instances. Using find
method:
Or if you build your array manually...
Referential integrity
one2many
attribute provides a way to control whether you want these records to be deleted with parent record, or prevent parent record from being deleted if it contains any child records. You can set it using onDelete
method, and choose between cascade
and restrict
, accordingly. More options will be implemented if required.
Aliases
This attribute also provides a way for create aliases
for your data by linking to the same entity, but adding filter values. This means that when you access your attribute value, it will automatically apply the requested filter and only return linked entities that match the filter:
Linking with other entities
Say you posted a new comment, and you need to link it with the Page
entity, you can do it using 2 approaches:
First one is to load a Page instance, and use add()
method on the one2many
attribute:
Second approach is to set Page
instance as a Comment
property (the page
property must exist in Comment entity as a many2one
attribute):
Next time you load Page
comments - the new Comment
will be in the data set.
ArrayAttribute
This attribute is mostly used for some extra data you want to store with your entity that is not shown to users in forms or grids (some settings, etc.). The cool thing about this attribute is it's "set" and "get" methods, which allows you to get and set nested keys and get default value if some part of your key does not exist.
Default value for Many2OneAttribute
Default value for Many2OneAttribute
can be specified in several ways:
Finding entities
There are 3 methods that allow you to find your entities: find
, findById
and findOne
.
find(array $conditions = [], array $order = [], $limit = 0, $page = 0) EntityCollection
- $conditions - is a key => value array of attributes and their values
- $order - is an array of sorters defined as
['-name', '+title', 'lastName']
('-' equals to DESCENDING, '+' or no prefix equals to ASCENDING) - $limit - number of entities to return
- $page - this will be used to calculate offset for you. NOTE: $page values start with 1. Ex: $limit=10, $page=2 will skip the first 10 records and return the next 10.
This method returns an instance of EntityCollection.
findById($id) AbstractEntity
Returns an instance of AbstractEntity
by given $id. If no entity is found, null
is returned.
findOne(array $conditions = []) AbstractEntity
Returns an instance of AbstractEntity
by given $conditions. If no entity is found, null
is returned.
EntityCollection class
This class is used to return results of find() method. It implements IteratorAggregate
and ArrayAccess
interfaces so it behaves exactly as an ordinary array would, and it also contains some utility methods to help you work with the data:
toArray($fields = '')
- returns an array representation of all entities in the resultset (see this for more details)add($item)
- adds $item to resultset (used with One2Many and Many2Many attributes to add new items to the attribute value)count()
- returns number of items in the resultsettotalCount()
- returns total number of items without $limit and $page parameterscontains($item)
- checks if given $item already exists in the resultsetdelete()
- deletes all items in the resultset (removes them from database)removeItem($item)
- removes item from the resultset (without removing them from database. This method is used with Many2Many attributes, to remove links between entities)
Convert AbstractEntity to array
You can get an array representation of current AbstractEntity
instance by calling toArray()
method.
By default, only simple and Many2One attributes will be included in the resulting array.
If you want to control which attributes to include, pass a string containing names of attributes. You can also control attributes of nested attributes:
This will result in something like:
In case your entity has a lot of attributes, you can use '*' to specify 'all default attributes', and then add only specific attributes you need.
Default attributes are all attributes that are not One2ManyAttribute
or Many2ManyAttribute
. If you need to get One2ManyAttribute
or Many2ManyAttribute
attribute values, you need to specify them manually.
This will results in:
Besides attribute names, you can control the depth of data being returned by specifying the depth in second parameter.
Default depth is 1, which means self + 1
(the example above is showing output of depth set to 1, by default).
Resources
To run unit tests, you need to use the following command:
$ cd path/to/Webiny/Component/Entity/
$ composer.phar install
$ phpunit
Make sure you set your MongoDb driver settings in Tests\MongoExampleConfig.yaml
.
All versions of entity with dependencies
webiny/config Version ~1.6
webiny/std-lib Version ~1.6
webiny/mongo Version ~1.6
webiny/service-manager Version ~1.6
webiny/validation Version ~1.6