Commit 90d3f9fa authored by eileen's avatar eileen 🎱
Browse files

Merge branch 'api4Cleanups' into 'master'

Apiv4 - Usage clarifications and formatting fixes

See merge request !955
parents c09fb4b6 29b2a819
......@@ -57,8 +57,6 @@ An API [`Result`](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/
- Some actions extend the Result object to store extra metadata. For example [`BasicReplaceAction`](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicReplaceAction.php) returns [`\Civi\Api4\Result\ReplaceResult`](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Result/ReplaceResult.php) which includes the additional `$deleted` property to list any items deleted by the operation.
3. Provide convenience methods like `$result->first()` and `$result->indexBy($field)`.
If you need to use array functions such as `is_array` on the result you can cast it you cast it to an array by doing $result = (array) $result. If you prefer you can call [`getArrayCopy()`](https://www.php.net/manual/en/arrayobject.getarraycopy.php) first i.e. `$result->getArrayCopy()` which basically copies the ArrayObject into an actual Array.
## Class Inheritance
![Inheritance](../../img/inheritance-community-chest.jpg)
......@@ -181,34 +179,33 @@ Basic Actions are designed to be used in 1 of 2 ways:
1. Your Entity's action function can construct the basic action directly, passing the callback into the constructor.
2. You can override the basic action class (e.g. for customizing the parameters). See [`Example::create()`](https://lab.civicrm.org/extensions/api4example/blob/master/Civi/Api4/Action/Example/Create.php).
- [**`BasicGetAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicGetAction.php):
- [**`BasicGetAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicGetAction.php):
Used to build actions whose purpose is fetching records. Parameters are `select`, `where`, `offset`, `limit`, and `orderBy`.
Its built-in array-query engine automatically filters/sorts the raw data returned by your callback according to the parameters.
Normally your callback can simply return an array of all existing records, but if performance is a concern, the functions `_itemsToGet()` and `_isFieldSelected()` can help you optimize your callback to only return results that are needed.
- [**`BasicCreateAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicCreateAction.php):
- [**`BasicCreateAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicCreateAction.php):
Used to create a new record. Parameters are `values`. Values will be passed into the callback via `writeRecord`, or you can override the `writeRecord` method in your custom create class.
See [`Example::create()`](https://lab.civicrm.org/extensions/api4example/blob/master/Civi/Api4/Action/Example/Create.php).
- [**`BasicUpdateAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicUpdateAction.php):
- [**`BasicUpdateAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicUpdateAction.php):
Used to update records based on a search query. Parameters are `values`, `reload`, `where`, `offset`, `limit`, and `orderBy`.
Internally calls `Get` to obtain records to update, so your entity must implement a get action.
Each will be passed into the callback via `writeRecord`, or you can override the `writeRecord` method in your custom update class.
- [**`BasicSaveAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicSaveAction.php):
- [**`BasicSaveAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicSaveAction.php):
Used to create or update multiple records. Parameters are `records`, `defaults`, and `reload`.
Each will be passed into the callback via `writeRecord`, or you can override the `writeRecord` method in your custom save class.
- [**`BasicBatchAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicBatchAction.php):
- [**`BasicBatchAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicBatchAction.php):
Used to perform an action on records based on a search query. Use this class, for example, to implement Delete.
Parameters are `where`, `offset`, `limit`, and `orderBy`.
Internally calls `Get` to obtain records, so your entity must implement a get action.
Each will be passed into the callback via `doTask`, or you can override the `doTask` method in your custom batch class.
- [**`BasicReplaceAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicReplaceAction.php):
- [**`BasicReplaceAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicReplaceAction.php):
Used to replace a set of records. Parameters are `records`, `default`, `reload`, `where`, `offset`, `limit`, and `orderBy`.
Internally calls `Get` to obtain records and `Save` to write them, so your entity must implement those actions.
- [**`BasicGetFieldsAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicGetFieldsAction.php):
- [**`BasicGetFieldsAction`**](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Generic/BasicGetFieldsAction.php):
Metadata action returns a list of fields for your entity.
......@@ -31,15 +31,27 @@ Consider these samples with commonly-used actions and parameters for the `Contac
## API Output
The API returns an array, with each item representing one record (also an array).
In PHP, this output is contained in an ArrayObject, which can be accessed like an array using e.g. `$result[0]` or `foreach ($result as ...)`. It also has the following methods:
In PHP, this output is contained in an ArrayObject, which can be accessed like an array using e.g. `$result[0]` or `foreach ($result as ...)`.
It also has the following methods:
- `$result->first()`: returns the first item, or NULL if not found.
- `$result->single()`: returns a single item, or throws an exception if not exactly one item was returned.
- `$result->last()`: returns the last item, or NULL if not found.
- `$result->itemAt($index)`: returns the item at a given index, or NULL if not found.
- `$result->indexBy($field)`: reindexes the array by the value of a field.
- `$result->column($field)`: reduces the array to a single field.
- `$result->count()`: counts the results.
- `$result->column($field)`: flattens the array, discarding all but a single field (call this second if using in conjunction with `indexBy` to create a key=>value array).
- `$result->count()`: get the total number of results. See note below on use with LIMIT.
- `$result->getArrayCopy()`: convert the object to a simple array.
!!! Getting Full Count While Using LIMIT
Sometimes you want to limit the number of results returned (e.g. when using a pager)
but also need the full count of results outside the limit you have set. Adding `row_count` to the
select clause will trigger the api to include the complete set of results in `$result->count()`.
!!! Converting ArrayObject to a Real Array
If you need to use functions such as `is_array` on the result you can cast it you cast it to an array, `(array) $result`, or use the [`getArrayCopy()`](https://www.php.net/manual/en/arrayobject.getarraycopy.php) method.
## Example
<iframe src="https://learn.civi.be/wp-admin/admin-ajax.php?action=h5p_embed&id=6" width="680" height="480" frameborder="0" allowfullscreen="allowfullscreen"></iframe>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment