diff --git a/docs/development/services/model/fetching.md b/docs/development/services/model/fetching.md index f4d989dcc..8492d0ac4 100755 --- a/docs/development/services/model/fetching.md +++ b/docs/development/services/model/fetching.md @@ -21,7 +21,7 @@ Use the `get()` method with a model name to begin a query: $builder = ee('Model')->get('Template'); -This will return a builder object, which we will use narrow down the selection. When you're ready to retrieve the matching data, call `all()`. You will be returned a [Collection](development/services/model/collection.md): +This will return a [Query Builder](development/services/model/query-builder.md) object, which we will use narrow down the selection. When you're ready to retrieve the matching data, call `all()`. You will be returned a [Collection](development/services/model/collection.md): $templates = $builder->all(); @@ -29,7 +29,7 @@ Usually these calls are chained for brevity: $templates = ee('Model')->get('Template')->all(); -NOTE: **Note:** Please see [Collection](development/services/model/collection.md) for list of methods to operate returned data. +NOTE: **Note:** Please see [Query Builder](development/services/model/query-builder.md) for list of methods to build model query and [Collection](development/services/model/collection.md) for list of methods to operate returned data. ## Filters @@ -203,3 +203,11 @@ In order to reduce memory usage, you can ask for only a subset of the available ->first(); NOTE: **Note:** This method should only be used for querying data. It should not be used for models that will be edited, deleted, or passed to other code for processing. + +## Caching + +The queries are not cached by default. If you'll need to reuse same model query at a later time, you can specify boolean `true` as parameter for `->all()` or `->first()` methods: + + $templates = ee('Model')->get('Template')->all(true); + + $template = ee('Model')->get('Template')->first(true); diff --git a/docs/development/services/model/query-builder.md b/docs/development/services/model/query-builder.md new file mode 100644 index 000000000..575fed627 --- /dev/null +++ b/docs/development/services/model/query-builder.md @@ -0,0 +1,169 @@ +--- +lang: php +--- + + + +# Model Query Builder + +Model Query Builder class is providing a bridge between Model instance and the database by transforming PHP code into SQL queries. + +In order to use methods of this class, you need to have a [Model](development/services/model.html) instance. You can get a Model instance by using `ee('Model')` service and getting or making a new model. + + $existingTemplate = ee('Model')->get('Template'); + + $newTemplate = ee('Model')->make('Template'); + +## Method Reference + +**class `ExpressionEngine\Service\Model\Query\Builder`** + +[TOC=3] + +### `first($cache = FALSE)` + +Run the query limited to one result and return the first element in the [Collection](development/services/model/collection.md) + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------ | +| \$cache | `Bool` | Whether the query results should be cached. Defaults to `false` | +| Returns | `Mixed` | The first element in the collection (or NULL if empty) | + +### `all($cache = FALSE)` + +Run the query and return the results as a [Collection](development/services/model/collection.md) + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------ | +| \$cache | `Bool` | Whether the query results should be cached. Defaults to `false` | +| Returns | `Mixed` | All elements in the collection (or NULL if empty) | + +### `update()` + +Updates the model(s) data by running SQL `UPDATE` query. +NOTE: It's not recommended to use this method directly. Use `save()` method of the model instead. + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| Returns | `Void` | | + +### `insert()` + +Inserts new database record for model by running SQL `INSERT` query. +NOTE: It's not recommended to use this method directly. Use `save()` method of the model instead. + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| Returns | `Void` | | + +### `delete()` + +Delete the model(s) from database by running SQL `DELETE` query. + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| Returns | `Void` | | + +### `count()` + +Get the number of records that match criterias by running SQL `COUNT` query + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| Returns | `Int` | The number of matching models | + +### `search($properties, $value)` + +Performs search using `LIKE` operator on specified columns. +Subsequent calls to this method will be chained with `AND` operator. + +| Parameter | Type | Description | +| --------- | --------- | -------------------- | +| \$properties | `String|Array` | Model property name, or array of property names | +| \$value | `String` | String value to search | +| Returns | `Builder` | Modified instance of Query Builder | + +### `filter($property, $operator = '==', $value = NULL)` + +Filter the query by adding a `WHERE` clause to the SQL query. +Note: when third parameter is omited, second parameter is used as value and `==` operator is used. +Subsequent calls to this method will be chained with `AND` operator. + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| \$property | `String` | Model property name | +| \$operator | `String` | Comparison operator. (List of supported operators)[development/services/model/fetching.md#available-filters]. Defaults to `==` | +| \$value | `String` | Value to compare to | +| Returns | `Builder` | Modified instance of Query Builder | + +### `orFilter()` + +Same as `filter()` but chained with `OR` operator. + +### `filterGroup()` + +Used to group filters with `AND` operator. Should be closed with `endFilterGroup()` method. + +### `orFilterGroup()` + +Used to group filters with `OR` operator. Should be closed with `endFilterGroup()` method. + +### `endFilterGroup()` + +Indicates the end of filter group. + +### `fields($field1, $field2, ...)` + +Limits the `SELECT` part of SQL query to only fetch certain model properties. + +### `set($property, $value)` + +Sets the model property with SQL `SET` so it could be saved to database later + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| \$property | `String` | Model property name | +| \$value | `String` | New property value | +| Returns | `Builder` | Modified instance of Query Builder | + +### `with($relationship)` + +Adds [related model](development/services/model/fetching.md#relationships) to the query by performing SQL `JOIN` + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| \$property | `String|Array` | Name of model relatioship, or deeply nested array of relationship names | +| Returns | `Builder` | Modified instance of Query Builder | + +### `order()` + +Name of property to order by, converted to SQL `ORDER BY` clause + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| Returns | `Builder` | Modified instance of Query Builder | + +### `limit($limit)` + +Limit the query by applying SQL `LIMIT` clause + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| \$limit | `Int` | Number to limit by. Defaults to 2^64 | +| Returns | `Builder` | Modified instance of Query Builder | + +### `offset($offset)` + +Limit the query by applying offset to SQL `LIMIT` clause + +| Parameter | Type | Description | +| --------- | ------- | -------------------- | +| \$offset | `Int` | Number to offset. Defaults to 0 | +| Returns | `Builder` | Modified instance of Query Builder | diff --git a/docs/toc_sections/_advanced_usage_toc.yml b/docs/toc_sections/_advanced_usage_toc.yml index a40751102..64ac5fdef 100644 --- a/docs/toc_sections/_advanced_usage_toc.yml +++ b/docs/toc_sections/_advanced_usage_toc.yml @@ -362,6 +362,8 @@ href: development/services/model/fetching.md - name: Relationships href: development/services/model/relationships.md + - name: Query Builder + href: development/services/model/query-builder.md - name: Collections href: development/services/model/collection.md - name: Building your own Models