Merge pull request #694 from seamuslee001/apiv4_join_chaining

Add in chaining and join docs for APIv4 and update v3 example URLS an…

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/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/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.
 

mkdocs.yml

@@ -52,8 +52,8 @@ pages:
     - APIv4 Usage: api/v4/usage.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