zajFetcher

The zajFetcher class is a way to fetch lists of model objects from the database. Lists can be sorted, combined, filtered, and iterated.

Basic usage

The most basic use for zajFetcher is when you fetch a multiple model objects from the database.

// This will return a zajModel object or false if it is not found
  $a_single_model = Sample::fetch('id_of_sample');
// This will return a zajFetcher object, which contains a list with all Sample objects
  $a_list_of_models = Sample::fetch();

The general idea of the fetcher object is to provide a simplified way to access and filter a list of zajModel objects. It is not meant to replace SQL. Its functionality is enough to cover most (but not all) of the cases where you need to grab a list from the database. You can always build custom SQL queries to work together with the zajFetcher object.

The logic is slightly different from SQL in that SQL is built for flexibility, while zajFetcher is built for simplicity. A zajFetcher list starts out with all objects in the list that are not deleted (status != ‘deleted’) which you can then filter, exclude, include, sort, etc. The order in which you apply functions to a list does not matter.

Some examples:

For more examples and an introduction to various use cases see the intro here and here.

Adding and removing connections

In addition to returning a list of zajModel objects, you use the zajFetcher model to add or remove connections via manytoone and onetomany fields. Use the add() and remove() methods for this. See documentation below as well.

Here are some examples to illustrate:

Properties

The following read-only properties are available:

• zajModel $first Returns the first item in the list.
• integer $total The total number of items on all pages.
• integer $count The number of items in the current limit / page.
• integer $affected The number affected items.
• stdClass $pagination The pagination object. See docs.
• string $wherestr The generated WHERE clause.
• string $orderby The generated ORDER BY clause.
• string $groupby The generated GROUP BY clause
• string $limit The generated LIMIT clause.
• string $class_name The name of the model.
• string $table_name The name of the MySQL table.

paginate()

Paginate results by a specific number.

@param integer $perpage The number of items to list per page.
@param integer|bool $page The current page number. This is normally controlled automatically via the created template variables. See docs for details.
@return zajFetcher This method can be chained.

sort()

Performs sorting by a given field.

Sample::fetch()->sort($by, $order = '')

@param string $by The field name to sort by. Or RANDOM if you want it randomly.
@param string $order ASC or DESC or RANDOM depending on what you want. If left empty, the default for this model will be used.

orderby()

Add an ORDER BY clause to your query.

This will overwrite anything that you sort(). Important! Please be aware that this method is not validated or escaped in any way – it is your responsibility to avoid SQL injection issues.

Sample::fetch()->orderby('name ASC, time_create DESC');

@param string $orderby The ORDER BY clause (without ‘ORDER BY’). If left empty, the default for this model will be used.

group()

A simplified GROUP BY which allows you to specify a single column to group by.

Sample::fetch()->group('name');

@param string|bool $by The fetcher results will be grouped by this field.
@return zajFetcher This method can be chained.

where()

Use this method to specify a custom WHERE clause. Begin with either || or && to continue the query! This is different from {@link zajFetcher->full_query()} because it is appended to the existing query. You should however use this only when necessary as it may cause unexpected behavior.

@param string $wherestr The customized portion of the WHERE clause. Since it is appended to the existing query, begin with || or && to produce a valid query.
@param bool $append If set to true (the detault), the string will be appended to any existing custom WHERE clause.
@return zajFetcher This method can be chained.

set_filter_deleted()

Set filter deleted to 0, 1, or the default.

@param string|integer $filter_deleted Takes 0, 1, or ‘default’.
@return string Returns the actual value it was set to.

add_source()

This method adds a joined source to the query. This is usually for internal use or when you are creating custom queries.

@param string $db_table The name of the table to select from.
@param string $as_name The name of the table as referenced within the sql query (SELECT …. FROM table_name AS as_name)
@param boolean $replace If set to true, this will remove all other sources before adding this new one.
@return zajFetcher This method can be chained.

reset_sources()

Remove all existing joined source from the query. This is mostly for internal use.

@return zajFetcher This method can be chained.

add_field_source()

This method adds a field to be selected from a joined source. This is mostly for internal use.
@param string $source_field The name of the field to select.
@param string|bool $as_name The name of the field as referenced within the sql query (SELECT field_name AS as_name)
@param bool $replace If set to true, this will remove all other joined fields before adding this new one.
@return zajFetcher This method can be chained.

reset_field_sources()

Remove all existing joined fields from the query. This is mostly for internal use.
@return zajFetcher This method can be chained.

from_array()

Create a fetcher object from an array of ids.
@param array $id_array An array of ids to search for.
@return zajFetcher This method can be chained.

show_deleted()

Toggle whether or not to show deleted items. By default, Mozajik will not delete rows you remove, but simply put them in a ‘deleted’ status. However, {@link zajFetcher} will not show these unless you toggle this option.
@param bool $default If set to true (the default), it will show deleted items for this query. If set to false, it will turn this feature off.
@return zajFetcher This method can be chained.

before()

A special filter method to be used for time filtering. It will filter results into everything BEFORE the given time or object. It is important to note that if you use an object as a parameter, it will change the sort order to the opposite since you are “going backwards” from the selected object.

@param string|zajModel $value The value by which to filter. Can also be a zajmodel of the same type – then field is checked by the model’s default sort order.
@param string $field The name of the field to be filtered. Defaults to the time_create field.
@param string $type AND or OR depending on how you want this filter to connect
@return zajFetcher This method can be chained.

after()

A special filter method to be used for time filtering. It will filter results into everything AFTER the given time.

@param string|zajModel $value The value by which to filter. Can also be a zajmodel of the same type – then field is checked by the model’s default sort order.
@param string $field The name of the field to be filtered. Defaults to the time_create field. Ignored if first paramter is zajModel.
@param string $type AND or OR depending on how you want this filter to connect
@return zajFetcher This method can be chained.

search()

Performs a search on all searchable fields. You can optionally use similarity search. This will use the wherestr parameter.

@param string $query The text to search for.
@param boolean $similarity_search If set to true (false is the default), similar sounding results will be returned as well.
@param string $type AND or OR depending on how you want this filter to connect
@return zajFetcher This method can be chained.

full_query()

Execute a full, customized query. Any query must return a column ‘id’ with the IDs of corresponding {@link zajModel} objects. Otherwise it will not be a valid {@link zajFetcher} object and related methods will fail. A full query will override any other methods used, except for paginate and limit (the limit is appended to the end, if specified!).

@param string $full_sql The full, customized query.
@return zajFetcher This method can be chained.

get_query()

This method returns the sql statement which will be used during the query.

@return string

query()

Executes the fetcher query.

@param bool $force By default, query will only execute once, so a second query() will be ignored. Set this to true if you want to force execution regardless of previous status.
@return zajFetcher

reset()

Reset will force the fetcher to reload the next time it is accessed.

count()

Returns the total count of this fetcher object.

limit()

Limits result list with the LIMIT clause in MySQL.

Sample::fetch()->limit($startat, $limitto)

Sample::fetch()->limit($limitto)

@param integer $startat This can be either startat or it can be the limit itself.
@param integer|bool $limitto The number of objects to take. Leave empty if the first parameter is used as the limit.
@return zajFetcher This method can be chained.

filter()

Can be used to filter results in a zajFetcher list. When you use Sample::fetch() you get a list of all Sample objects in the database (except those with status=’deleted’). You can then filter this list with the filter() method.

Sample::fetch()->filter($field, $value, $operator='LIKE', $type='AND')

@param string $field The name of the field to be filtered.
@param mixed $value The value by which to filter. The type of values accepted depends on the field you are filtering.
@param string $operator The operator with which to filter. Can be any valid MySQL-compatible operator: LIKE, NOT LIKE, <, >, <=, =, REGEXP etc. Some data types may not support all operators. @param string $type AND or OR depending on how you want this filter to connect
@return zajFetcher This method can be chained.

remove_filters()

Remove filters completely or for a specific field.

$list->remove_filters('name');

@param string|boolean $field The name of the field whoes filter should be reset. If omitted (or if false), all are removed.
@return zajFetcher This method can be chained.

exc() / exclude()

Exclude is very similar to filter except that instead of filtering data, it excludes data. Technically it’s just an alias with the default $operator set to ‘NOT LIKE’.

Sample::fetch()->exclude($field, $value, $operator='NOT LIKE', $type='AND')

@param string $field The name of the field to be filtered.
@param mixed $value The value by which to filter. The type of values accepted depends on the field you are filtering.
@param string $operator The operator with which to filter. Can be any valid MySQL-compatible operator: LIKE, NOT LIKE, <, >, <=, =, REGEXP etc. Some data types may not support all operators. @param string $type AND or OR depending on how you want this filter to connect
@return zajFetcher This method can be chained.

exclude_all()

This is a way to exclude all items from the list. As mentioned, Sample::fetch() includes all items in the database by default. If you use Sample::fetch()->exclude_all() then your list will become a completely empty list. You can then use inc() to add certain matching rows.

inc()

Inc is include, the opposite of exclude. Like exclude, it is very similar to filter except that instead of filtering data, it includes data. Technically it’s just an alias with the default $operator set to ‘LIKE’ and the type set to ‘OR’ (whereas filter() uses LIKE / AND).

Sample::fetch()->inc($field, $value, $operator='LIKE', $type='OR')

@param string $field The name of the field to be filtered.
@param mixed $value The value by which to filter. The type of values accepted depends on the field you are filtering.
@param string $operator The operator with which to filter. Can be any valid MySQL-compatible operator: LIKE, NOT LIKE, <, >, <=, =, REGEXP etc. Some data types may not support all operators. @param string $type AND or OR depending on how you want this filter to connect
@return zajFetcher This method can be chained.

filter_query()

Apply a filter query (typically generated from a filter ui) to the list.

@param array|boolean $query The filter query. See below for formatting. Defaults to $_GET.
@param boolean $similarity_search If set to true (false is the default), similar sounding results will be returned as well.
@param string $type AND or OR depending on how you want this filter to connect
@return zajFetcher This method can be chained.

Additional details:

• Typically filter ui is generated using the {% inputfilter %} tag (see docs)
• When the filter query is being applied, the __onFilterQueryFetcher($this, $query, $similarity_search, $type) static magic method will be called on the model class (docs).
• The format of the GET request is detailed here.
• You can define an __onFilterGeneration($param_array, &$source) magic method in your field definition file in case you need additional features or data. See existing examples (manytoone.field.php). It is very similar to _onInputGeneration. (docs)

add()

This method adds $object to the relationship.

@param zajModel $object The model object you would like to add.
@return zajFetcher Returns the zajFetcher object, so it can be chained.

remove()

This method removes $object from the relationship.

@param zajModel $object The model object you would like to add.
@param bool $delete_all Remove all connections not just a single one. This only works in ‘delete’ mode. Defaults to false.
@return zajFetcher Returns the zajFetcher object, so it can be chained.

is_connected()

Returns true or false based on whether or not the current fetcher is connected to the object $object.

@param zajModel $object The object in question.
@return boolean True if connected, false otherwise.