Merge branch 'master' into apiv4_custom_data

docs/api/v3/actions.md

-# API Actions
+# APIv3 Actions
 
 Most entities support the following actions:
 

docs/api/v3/chaining.md

 # APIv3 Chaining
 
-It is now possible to do two API calls at once with the first call feeding into
-the second. E.g. to create a contact with a contribution you can nest the
-contribution create into the contact create. Once the contact has been created
-it will action the contribution create using the id from the contact create as
-`contact_id`. Likewise you can ask for all activities or all contributions to
-be returned when you do a get.
+It is possible to do two API calls at once with the first call feeding into the second. E.g. to create a contact with a contribution you can nest the contribution create into the contact create. Once the contact has been created it will action the contribution create using the id from the contact create as `contact_id`. Likewise you can ask for all activities or all contributions to be returned when you do a `get`.
 
-See [api/v3/examples] within the core source code for a plethora of examples
-(from unit tests) that use chaining. To start, look at these examples:
-
--   [APIChainedArray.php]
--   [APIChainedArrayFormats.php]
--   [APIChainedArrayValuesFromSiblingFunction.php]
-
-[api/v3/examples]: https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples
-[APIChainedArray.php]: https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArray.php
-[APIChainedArrayFormats.php]: https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayFormats.php
-[APIChainedArrayValuesFromSiblingFunction.php]: https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayValuesFromSiblingFunction.php
+See [api/v3/examples](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples) within the core source code for a plethora of examples (from unit tests) that use chaining. To start, look at these examples:
 
+-   [APIChainedArray.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArray.ex.php)
+-   [APIChainedArrayFormats.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayFormats.ex.php)
+-   [APIChainedArrayValuesFromSiblingFunction.php](https://github.com/civicrm/civicrm-core/blob/master/api/v3/examples/Contact/APIChainedArrayValuesFromSiblingFunction.ex.php)
 
 Note that there are a few supported syntaxes:
 
@@ -71,6 +59,4 @@ civicrm_api('Contact', 'create', array(
 
 The format you use on the way in will dictate the format on the way out.
 
-Currently this supports any entity and it will convert to `entity_id` -
-i.e. a PledgePayment inside a contribution will receive the `contribution_id`
-from the outer call.
+Currently this supports any entity and it will convert to `entity_id` - i.e. a PledgePayment inside a contribution will receive the `contribution_id` from the outer call.

docs/api/v3/examples.md

@@ -4,7 +4,7 @@ All the APIv3 Examples are generated through Tests in the CodeBase and are auto-
 
 ## Location of Examples
 
-The most current examples can be found in CiviCRM's GitHub Repo on the [Master Branch](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples). In the GitHub Repo can you also find examples that relate to the LTS version as well in the [4.6 Branch](https://github.com/civicrm/civicrm-core/tree/4.6/api/v3/examples). When you install CiviCRM the Examples that come with the particular version of CiviCRM you have installed can be found in `<civicrm_root>/api/v3/examples`. You will also be able to view them through the [API Explorer](/api/index.md#api-explorer) by clicking on the **Examples** tab in the Explorer.
+The most current examples can be found in CiviCRM's GitHub Repo on the [Master Branch](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples). When you install CiviCRM the Examples that come with the particular version of CiviCRM you have installed can be found in `<civicrm_root>/api/v3/examples`. You will also be able to view them through the [API Explorer](/api/index.md#api-explorer) by clicking on the **Examples** tab in the Explorer.
 
 ## Creating a New Example
 

docs/api/v3/joins.md

@@ -43,7 +43,7 @@ $result = civicrm_api3('Event', 'get', array(
 ));
 ```
 !!! tip
-    Joins are available only with the [get](/api/v3/actions.md#getfields),
+    Joins are available only with the [get](/api/v3/actions.md#get),
     [getsingle](/api/v3/actions.md#getsingle), and [getcount](/api/v3/actions.md#getcount)
     actions.
 

docs/api/v4/actions.md

+# APIv4 Actions
+
+Most entities support the following actions:
+
+## Create
+
+Insert new records into the database.
+
+## Update
+
+Update records in the database.
+
+## Delete
+
+Delete one or more records. Requires an explicit `id`. If you want to skip the 'recycle bin' for entities that support undelete (e.g. contacts) you should set `$param['skip_undelete'] => 1);`
+
+## Get
+
+Search for records
+
+## GetFields
+
+Fetch entity metadata, i.e. the list of fields supported by the entity. There is now an option that you can pass in for get fields which is `loadOptions`. This is the equivilant of the apiv3 getoptions API call. When used for any field that specifies a pseudoconstant it will return the relevant options in an options key. You can also pass in an option `IncludeCustom` which will specifiy whether to include the relevant custom fields for that entity or not.
+
+## Replace
+
+Replace an old set of records with a new or modified set of records. (For example, replace the set of "Phone" numbers with a different set of "Phone" numbers.).
+
+!!! warning
+    Replace includes an implicit delete action - use with care & test well before using in production.
+
+## Save
+
+Create or update one or more records

docs/api/v4/chaining.md

+# APIv4 Chaining
+
+It is possible to do two API calls at once with the first call feeding into the second. E.g. to create a contact with a contribution you can nest the contribution create into the contact create. Once the contact has been created it will action the contribution create using the id from the contact create as `contact_id`. Likewise you can ask for all activities or all contributions to be returned when you do a `get`.
+
+Note that there are a few supported syntaxes:
+
+Object Oriented way
+
+```php
+$results = \Civi\Api4\Contact::create()
+  ->addValue('contact_id', 'Individual')
+  ->addValue('display_name', 'BA Baracus')
+  ->setChain([
+    'create_website' => ['Website', 'create', ['values' => ['contact_id' => '$id', 'url' => 'example.com']]],
+  ])
+  ->execute();
+```
+
+Traditional:
+
+```php
+civicrm_api('Contact', 'create', [
+  'version' => 4,
+  'values' => [
+    'contact_type' => 'Individual',
+    'display_name' => 'BA Baracus',
+  ],
+  'chain' => [
+    'create_website', ['Website', 'create', ['values' => ['url' => 'example.com', 'contact_id' => '$id']]],
+  ],
+]);
+```
+
+If you have 2 websites to create you can pass them as separate key => array pairs just specify a unique array key in the chain array
+
+Object Oriented way
+
+```php
+$results = \Civi\Api4\Contact::create()
+  ->addValue('contact_id', 'Individual')
+  ->addValue('display_name', 'BA Baracus')
+  ->setChain([
+    'create_first_website' => ['Website', 'create', ['values' => ['contact_id' => '$id', 'url' => 'example.com']]],
+    'create_second_website' => ['Website', 'create', ['values' => ['contact_id' => '$id', 'url' => 'example.org']]],
+  ])
+  ->execute();
+```
+
+Traditional:
+
+```php
+civicrm_api('Contact', 'create', [
+  'version' => 4,
+  'values' => [
+    'contact_type' => 'Individual',
+    'display_name' => 'BA Baracus',
+  ],
+  'chain' => [
+    'create_first website', ['Website', 'create', ['values' => ['url' => 'example.com', 'contact_id' => '$id']]],
+    'create_second_website', ['Website', 'create', ['values' => ['url' => 'example.org', 'contact_id' => '$id']]],
+  ],
+]);
+```
+
+Currently this supports any entity and it will convert to `entity_id` - i.e. a PledgePayment inside a contribution will receive the `contribution_id` from the outer call.

docs/api/v4/joins.md

+# API Joins
+
+An API "get" action will typically return only the values of the entity requested. However, there are times when it is advantageous to returned data from a related entity.  For instance, when querying the API for email addresses, you may want to return the name of the associated contact from the Contact entity.
+
+The CiviCRM API supports two methods of returning data from associated entities; APIv4 Joins and [APIv4 Chaining](/api/v4/chaining.md).  API joins provide higher performance by making a single SQL query with a [SQL join](https://dev.mysql.com/doc/refman/5.7/en/join.html), and are generally preferable to API chaining where available.
+
+## Using an API Join
+
+To use a join in an API call, specify the name of the field on which the join happens, a period, and the name of the field to reference.  
+
+For instance, to search for all primary emails, returning the email and joining to also return the contact's display name:
+
+Object Oriented way:
+
+```php
+$result \Civi\Api4\Email::get()
+  ->setSelect([
+    'contact.display_name', 
+    'email',
+  ])
+  ->addWhere('is_primary', '=', 1)
+  ->setLimit(25)
+  ->setCheckPermissions(FALSE)
+  ->execute();
+```
+
+Traditional:
+
+```php
+$result = civicrm_api4('Email', 'get', [
+  'select' => ["email", "contact.display_name"],
+  'where' => [
+    ['is_primary', '=', 1],
+  ],
+  'limit' => 25,
+]);
+```
+
+Alternatively, to return email addresses of everyone whose last name is Smith by joining to the Contact entity:
+
+Object Oriented way:
+
+```php
+$result \Civi\Api4\Email::get()
+  ->addWhere('contact.last_name', '=', 'Smith')
+  ->setLimit(25)
+  ->setCheckPermissions(FALSE)
+  ->execute();
+```
+
+Traditional:
+
+```php
+$result = civicrm_api4('Email', 'get', [
+  'where' => [
+    ['contact.last_name', '=', "Smith"],
+  ],
+  'limit' => 25,
+]);
+```
+
+You can join multiple times in one query.  For instance, to return a list of events, displaying their name, the name of the related campaign, and that campaign's type:
+
+Object Oriented way:
+
+```php
+$result \Civi\Api4\Email::get()
+  ->setSelect(['title', 'campaign.name', 'campaign.campaign_type_id'])
+  ->setLimit(25)
+  ->setCheckPermissions(FALSE)
+  ->execute();
+```
+
+Traditional:
+
+```php
+$result = civicrm_api4('Event', 'get', [
+  'select' => ['title', 'campaign.name', 'campaign.campaign_type_id'],
+));
+
+```
+
+!!! tip
+    Joins are available only with the [get](/api/v4/actions.md#get) action
+
+## Identifying fields eligible for a join
+
+It is possible to join an entity to any other entity if the [xml schema](/framework/database/schema-definition.md) identifies a [foreign key](/framework/database/schema-definition.md#table-foreignKey) or a [pseudoconstant](/framework/database/schema-definition.md#table-field-pseudoconstant).  The [getfields](/api/v3/actions.md#getfields) action identifies
+fields that are eligible for an API join.

docs/api/v4/usage.md

@@ -11,6 +11,9 @@ Canonically, an API call is processed by the API kernel.  The `$entity`, `$actio
 
 A couple of significant differences between APIv4 and APIv3 is that in v4 the `check_permissions` flag is set to true by default and on get actions especially but more generally the limit of 25 items returned that v3 has has been removed in favour of coders specifying the limit if they want to in their code calls.
 
+!!! info
+   As of CiviCRM version 5,18 not all core entities have been added to APIv4. You should check the API explorer to see which entities are available. If the entity you require is not available then please open a pull request against the [`civicrm-core` repository](https://github.com/civicrm/civicrm-core) to add the entity in or open an (issue)[https://lab.civicrm.org/dev/core] and request that the entity is added.
+
 ```php
 $result = Civi::service('civi_api_kernel')->run('Contact', 'get', [
   'version' => 4,

docs/core/pr-review.md

@@ -46,7 +46,7 @@ On the PR, click over to “Files Changed” and understand what the code is doi
 
 ## Reproduce the problem
 
-Confirm which branch the PR was created against. This is probably either `master` or the LTS. Setup an instance locally from that branch (e.g. with [buildkit](https://github.com/civicrm/civicrm-buildkit)), or test on the [public demo site if possible](https://civicrm.org/demo). Repeat the steps to reproduce described in the ticket or PR.
+Confirm which branch the PR was created against. This is probably either `master` or a Release Candidate branch. Setup an instance locally from that branch (e.g. with [buildkit](https://github.com/civicrm/civicrm-buildkit)), or test on the [public demo site if possible](https://civicrm.org/demo). Repeat the steps to reproduce described in the ticket or PR.
 
 Confirm that the issue was a problem and a problem “worth solving”, generally worthy of being in core.
 

docs/extensions/civix.md

@@ -165,6 +165,8 @@ If you want your extension to store data in the database, then you will need to
     
 Now your entity should be ready to use. Try it out with `cv api MyEntity.create` and `cv api MyEntity.get`. Then [add some tests](#generate-test).
 
+By default when you generate an entity you will be generating an APIv4 entity. To generate an APIv3 (or both) interface you need to specify `--api-version 3,4` or just `--api-version 3`
+
 !!! note "Troubleshooting"
 
     If you've generated an entity within an extension that you created with `civix` v18.01.0 or earlier, then you'll need to add this hook to your `myextension.php` file (changing `myextension` to your extension's short name).

mkdocs.yml

@@ -50,10 +50,10 @@ pages:
   - API Interfaces: api/interfaces.md
   - APIv4:
     - APIv4 Usage: api/v4/usage.md
-  #  - APIv4 Actions: api/v4/actions.md
+    - APIv4 Actions: api/v4/actions.md
   #  - APIv4 Options: api/v4/options.md
-  #  - APIv4 Joins: api/v4/joins.md
-  #  - APIv4 Chaining: api/v4/chaining.md
+    - APIv4 Joins: api/v4/joins.md
+    - APIv4 Chaining: api/v4/chaining.md
     - APIv4 Custom Data: api/v4/custom-data.md
   #  - APIv4 Examples: api/v4/examples.md
   #  - APIv4 Changes: api/v4/changes.md

redirects/internal.txt

@@ -8,7 +8,7 @@ hooks/hook_civicrm_trigger_info hooks/hook_civicrm_triggerInfo
 testing/setup testing
 testing/javascript testing/karma
 framework/schema-definition framework/database/schema-definition
-api/params api/options
+api/params api/v3/options
 testing/selinium testing/selenium
 core/develop tools/git
 basics/filesystem framework/filesystem

redirects/wiki-crmdoc.txt

@@ -112,7 +112,7 @@ hook_civicrm_alterReportVar hooks/hook_civicrm_alterReportVar
 Hook+Reference hooks
 Hooks hooks
 Extension+Review extensions/lifecycle/#formal-review
-Call+the+CiviCRM+API+from+a+custom+template api/usage/#smarty
+Call+the+CiviCRM+API+from+a+custom+template api/v3/usage/#smarty
 Using+the+API api
 Hook+examples hooks
 Database+hooks hooks
@@ -137,7 +137,7 @@ API+Architecture+Standards framework/api-architecture
 How+to+migrate+or+write+an+api framework/api-architecture
 Javascript+Reference standards/javascript
 Resource+Reference framework/resources
-API+Examples api/examples
+API+Examples api/v3/examples
 REST+interface api/interfaces#rest-interface
 AJAX+Interface api/interfaces#ajax-interface
 Smarty+API+interface api/interfaces#smarty-api-interface
@@ -146,16 +146,16 @@ Extension+Reference extensions/info-xml
 Settings+Reference framework/setting
 Region+Reference framework/region
 HTML+Header+Region framework/region#header
-Chaining api/chaining
+Chaining api/v3/chaining
 Add-on+Formats extensions/packaging
 IDE+Settings+to+Meet+Coding+Standards tools/phpstorm
-API+changes api/changes
+API+changes api/v3/changes
 Ajax+Pages+and+Forms framework/ajax
 Coding+Standards standards
 QuickForm+Reference framework/quickform
 EntityRef+Fields framework/quickform/entityref
 Pseudoconstant+option+list+Reference framework/pseudoconstant
-API+Security api/usage/#api-security
+API+Security api/v3/usage/#api-security
 UI+Elements+Reference framework/ui
 Accordions framework/ui
 Buttons framework/ui
@@ -165,7 +165,7 @@ In-Place+Field+Editing framework/ui
 Notifications+and+Confirmations framework/ui
 Section+elements framework/ui
 Database+layer standards/database
-Using+Custom+Data+with+the+API api/custom-data
+Using+Custom+Data+with+the+API api/v3/custom-data
 CiviReport+Reference framework/civireport
 Manual+testing testing/manual
 Dedupe+and+merge+testing testing/manual/#dedupe