Manipulating entities¶
To get an overview on CREATE, READ, UPDATE, DELETE commands, see Building a REST API.
The following examples show the minimal syntax required to operate CRUD manipulations:
multilang fields
For fields whose value varies from one language to another (multilang), an additional $lang
parameter is used. See i18n for more information.
CRUD operations¶
CRUD operations are part of the ORM foundations and are handled by the ObjectManager service.
All methods return either an integer or an array (when relevant).
By convention, in case of error, a negative integer is returned.
Supported errors codes¶
error codes
All codes are prefixed with EQ_ERROR_
(not show in the table to avoid redundancy). So, for instance, UNKNOWN
will appear as EQ_ERROR_UNKNOWN
in code.
NAME | VALUE | DESCRIPTION |
---|---|---|
UNKNOWN |
-1 | Something went wrong in an unexpected way. |
MISSING_PARAM |
-2 | One or more mandatory parameters are missing. |
INVALID_PARAM |
-4 | One or more parameters have invalid or incompatible value. |
SQL |
-8 | An error occurred while building SQL query or processing it. |
UNKNOWN_OBJECT |
-16 | The request targets an unknown resource (class, object, view, ...). |
NOT_ALLOWED |
-32 | Action violates some rule (including UPLOAD_MAX_FILE_SIZE for binary fields) or user don't have required permissions. |
LOCKED_OBJECT |
-64 | Object is currently locked by another process. |
CONFLICT_OBJECT |
-128 | Version conflict. |
INVALID_USER |
-256 | Authentication failure. |
UNKNOWN_SERVICE |
-512 | Server error : missing service. |
INVALID_CONFIG |
-1024 | Server error : faulty configuration. |
Create¶
<?php
/**
* Creates a new instance of given class and, if given, assigns values to targeted fields.
*
* @param string $entity Class of the object to create.
* @param array $fields Associative array mapping each field to its assigned value.
* @param string $lang Language in which to store multilang fields.
* @param boolean $use_draft If set to false, disables the re-use of outdated drafts.
* @return integer Identfier of the newly created object or, in case of error, the code of the error that was raised.
*/
function create($entity, $fields, $lang=null, $use_draft=true)
Read¶
<?php
/**
* Reads a collection of objects from a given class, based on a list of identfiers.
*
* @param string $class Class of the objects to retrieve.
* @param mixed $ids Identifier(s) of the object(s) to retrieve (accepted types: array, integer, string).
* @param mixed $fields Name(s) of the field(s) to retrieve (accepted types: array, string).
* @param string $lang Language under which return fields values (only relevant for multilang fields).
* @return int|array Resulting associative array mapping ids with objects, or error identifier.
*/
function read($entity, $ids, $fields, $lang=null)
Update¶
<?php
/**
* Updates specified fields of seleced objects and stores changes into database.
*
* @param string $class Class of the objects to write.
* @param mixed $ids Identifier(s) of the object(s) to update (accepted types: array, integer, numeric string).
* @param mixed $fields Array mapping fields names with the value (PHP) to which they must be set.
* @param string $lang Language under which fields have to be stored (only relevant for multilang fields).
* @return int|array Returns an array of updated ids, or an error identifier in case an error occured.
*/
function update($class, $ids, $fields, $lang=null)
Delete¶
<?php
/**
* Deletes an object permanently or put it in the "trash bin" (i.e. setting the 'deleted' flag to 1).
*
* @param string $class Class of the object to delete.
* @param array $ids Array of ids of the objects to delete.
* @param boolean $permanent Flag for soft deleted (marked as deleted) or hard deletion (removed from DB).
*
* @return integer|array Returns a list of ids of deleted objects, or an error identifier in case an error occured.
*/
function delete($entity, $ids, $permanent=false)
Querying entities¶
In addition to classic CRUD operations, eQual comes with a search()
method dedicated to querying entities.
Search method¶
<?php
/**
* Searches for the objects that comply with the domain (series of criteria).
*
* @param string $class Class of the objects to search for.
* @param array $domain Domain (disjunction of conjunctions) defining the criteria the objects have to match.
* @param array $sort Associative array mapping fields and orders on which result have to be sorted.
* @param integer $start The offset at which to start the segment of the list of matching objects.
* @param string $limit The maximum number of results/identifiers to return.
*
* @return integer|array Returns an array of matching objects ids.
*/
function search($class, $domain=null, $sort=['id' => 'asc'], $start='0', $limit='0', $lang=null) {
Collections¶
eQual implements Collections through Collection
objects that are instantiated using entities (model).
Collections give the ability to apply chained actions on multiple objects at a time while checking the permission of the current user (returned by the Authentication
service).
Example :
<?php
use core\User;
User::search(['firstname', 'ilike', '%sam%'])
->from(0)
->limit(5)
->get();
Retrieving a collection is through API calls is available using the standard controller core_model_collect
.
The purpose of the "collect" operation is to perform a search()
and a read()
in a single call.
Querying sub-objects¶
a) dot notation¶
$ ./equal.run \
--get=model_collect \
--entity=core\\User \
--fields=[id,name,groups_ids.name,groups_ids.description]
b) array notation¶
$ ./equal.run \
--get=model_collect \
--entity=core\\User \
--fields="{id,name,groups_ids:{name,description}}"