Get an array of entities.
$options is an associative array, which contains any of the following settings (in the form $options['name'] = value):
- class - (string) The class to create each entity with.
- limit - (int) The limit of entities to be returned.
- offset - (int) The offset from the oldest matching entity to start retrieving.
- reverse - (bool) If true, entities will be retrieved from newest to oldest. Therefore, offset will be from the newest entity.
- sort - (string) How to sort the entities. Accepts "guid", "cdate", and "mdate". Defaults to "cdate".
- return - (string) What to return. "entity" or "guid". Defaults to "entity".
- source - (string) Will be 'client' if the query came from a REST call.
- skip_cache - (bool) If true, Nymph will skip the cache and retrieve the entity from the DB.
- skip_ac - (bool) If true, Tilmeld will not filter returned entities according to access controls. (If Tilmeld is installed.) (This is Always set to false by the REST endpoint.)
If a class is specified, it must have a factory() static method that returns a new instance.
Selectors are also associative arrays. Any amount of selectors can be provided. Empty selectors will be ignored. The first member of a selector must be a "type" string. The type string can be:
- & - (and) All values in the selector must be true.
- | - (or) At least one value in the selector must be true.
- !& - (not and) All values in the selector must be false.
- !| - (not or) At least one value in the selector must be false.
The rest of the entries in the selector are either more selectors or associative entries called selector clauses, which can be any of the following (in the form $selector['name'] = value, or $selector['name'] = [value1, value2,...]):
- guid - A GUID. True if the entity's GUID is equal.
- tag - A tag. True if the entity has the tag.
- isset - A name. True if the named property exists and is not null.
- equal - An array with a name, then value. True if the named property is defined and equal.
- data (deprecated) - An alias for equal.
- strict - An array with a name, then value. True if the named property is defined and identical.
- array - An array with a name, then value. True if the named property is an array containing the value. Uses in_array().
- match - An array with a name, then regular expression. True if the named property matches. Uses preg_match(). More powerful than "pmatch" but much slower. Must be surrounded by "/" delimiters.
- pmatch - An array with a name, then regular expression. True if the named property matches. Uses POSIX RegExp. Case sensitive. Faster than "match". Must not be surrounded by any delimiters.
- ipmatch - An array with a name, then regular expression. True if the named property matches. Uses POSIX RegExp. Case insensitive. Faster than "match". Must not be surrounded by any delimiters.
- like - An array with a name, then pattern. True if the named property matches. Uses % for variable length wildcard and _ for single character wildcard. Case sensitive.
- ilike - An array with a name, then pattern. True if the named property matches. Uses % for variable length wildcard and _ for single character wildcard. Case insensitive.
- gt - An array with a name, then value. True if the named property is greater than the value.
- gte - An array with a name, then value. True if the named property is greater than or equal to the value.
- lt - An array with a name, then value. True if the named property is less than the value.
- lte - An array with a name, then value. True if the named property is less than or equal to the value.
- ref - An array with a name, then either an entity, or a GUID. True if the named property is the entity or an array containing the entity.
These clauses can all be negated, by prefixing them with an exclamation point, such as "!isset".
Any clause that accepts an array of name and value can also accept a third element. If value is null and the third element is a string, the third element will be used with PHP's strtotime function to set value to a relative timestamp. For example, the following selector will look for all entities that were created in the last day:
[
'&',
'gte' => ['cdate', null, '-1 day']
]
This example will retrieve the last two entities where:
- It has 'person' tag.
- spouse exists and is not null.
- gender is male and lname is Smith.
- warnings is not an integer 0.
- It has 'level1' and 'level2' tags, or it has 'access1' and 'access2' tags.
- It has either 'employee' or 'manager' tag.
- name is either Clark, James, Chris, Christopher, Jake, or Jacob.
- If age is 22 or more, then pay is not greater than 8.
$entities = \Nymph\Nymph::getEntities(
['reverse' => true, 'limit' => 2],
[
'&', // all must be true
'tag' => 'person',
'isset' => 'spouse',
'equal' => [
['gender', 'male'],
['lname', 'Smith']
],
'!strict' => ['warnings', 0]
],
[
'|', // at least one of the selectors in this must evaluate to true
[
'&',
'tag' => ['level1', 'level2']
],
[
'&',
'tag' => ['access1', 'access2']
]
],
[
'|', // at least one must be true
'tag' => ['employee', 'manager']
],
[
'|',
'equal' => [
['name', 'Clark'],
['name', 'James']
],
'pmatch' => [
['name', 'Chris(topher)?'],
['name', 'Ja(ke|cob)']
]
],
[
'!|', // at least one must be false
'gte' => ['age', 22],
'gt' => ['pay', 8]
]
);
- Parameters
-
| array | $options | The options. |
| array | $selectors | Unlimited optional selectors to search for. If none are given, all entities are retrieved for the given options. |
| array | $selectors,... | |
- Returns
- array|null An array of entities, or null on failure.
- Todo:
An option to place a total count in a var.
Use an asterisk to specify any variable.
Definition at line 490 of file Nymph.php.
1.8.15