toga-ai 1.0.0

package/knowledge/2.0/standards/backend-php.md

@@ -0,0 +1,710 @@
+---
+title: Back-End Coding Standards
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-06-08
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/_underscore/architecture.md
+  - ../apps/api2/architecture.md
+  - ../apps/worker2/architecture.md
+---
+
+## General Principals
+
+### Modularity and Reusability
+
+* Ensure that the code is modular, making use of functions and classes to promote reusability and separation of concerns.
+
+## Database/SQL
+
+### Table Design
+
+#### **Order of Fields**
+
+1. `id` (mandatory)
+2. `uuid` (mandatory)
+3. Foreign Keys
+4. Record Identifiers (references like order number)
+5. Date/Time fields
+6. Date fields
+7. Flag/Boolean fields
+8. ENUM-type fields (lists)
+9. Char/Varchar/Integer/Decimal fields
+10. Text/Blob fields
+11. Custom fields
+
+### UUIDs
+
+* All records inserted in the 2.0 database must be given a random UUID in the second column of each table called `uuid`
+* Do not use the built-in `UUID()` function provided by MySQL because they are not fully random and instead are time-based which causes UUIDs to be nearly identical, making it hard for developers to read.
+* Instead, generate a fully-random UUID in PHP with **`_String::generateUuid()`** (defined in `_underscore/String.php`). It builds a random 32-hex value formatted as a standard UUID. Do not rely on a MySQL-side function for this.
+
+#### **Custom Fields**
+
+* A non-standard field requested or required by the client/3rd party is called a custom field. When adding custom fields to a table, keep this in mind:
+  * The custom field should be at the end of the table
+  * Start the field name with `c_` , for example `c_employeeId`
+  * Maintain camelCase after the `c_` prefix
+
+#### **Table & Field Comments**
+
+* All database tables and fields in 2.0 databases must be given a short, but descriptive comment which will be visible to clients and the public.
+* Example SQL query for altering a table comment:
+
+```sql
+ALTER TABLE AclLogicGroups COMMENT 'ACL logic groups of a record';
+```
+
+* Field commenting rules:
+  * Do not begin a comment with "The"
+  * Some fields have a specific format that must be followed:
+    * `id`: Must be 'Internal unique identifier of the record'
+    * `uuid`: Must be 'External unique identifier of the record'
+    * Foreign keys such as `purchaseOrderId`: Must begin with the database (Core/Client/Logs) with exact table name, a `.`, and a descriptive comment such as: 'Client.PurchaseOrders record this ASN is for'
+    * Foreign keys such as `shipToAddressId`: Must begin with the database (Core/Client/Logs) with exact table name, a `.`, and a descriptive comment using the specific type in the second part of the sentence. For example: 'Client.Addresses record this ASN is shipping to'
+
+#### **Engine, Character Set & Collation**
+
+* All tables must use the `InnoDB` engine.
+* All tables must use `utf8mb4` as the character set and `utf8mb4_0900_ai_ci` as the collation except in specific cases where a different character set or collation is required such as a case sensitive field or different encoding.
+
+```sql
+# Syntax for engine, character set, and collation
+ENGINE=InnoDB
+DEFAULT CHARSET=utf8mb4
+COLLATE=utf8mb4_0900_ai_ci
+```
+
+### Queries
+
+* While it's ok to use `SELECT *` in your MySQL client, it should NEVER be used in code because this puts undue stress on the servers and uses up undue resources.
+
+#### **Capitalization**
+
+* All SQL keywords need to be capitalized.
+* This includes `SELECT`, `FROM`, `INNER JOIN`, `ON`, `WHERE`, `AND`, `OR`, `NOT`, `LIKE`, `GROUP_CONCAT`, `AS`, `ORDER BY`, `DESC`, `LIMIT`, `IS`, `IN`, `GROUP BY`, `HAVING`, etc.
+
+```sql
+# Bad
+select column1 From table1
+
+# Good
+SELECT column1 FROM table1
+```
+
+#### **Spacing**
+
+1. ALWAYS use tabs for indentation.
+2. Every clause should start on a new line.
+3. Indent the column list that follows a `SELECT` clause, and the condition that follows a `WHERE` or `ON` clause.
+4. Do not leave trailing spaces at the end of lines.
+5. Use a line break after each comma in the `SELECT` clause or column list.
+6. `SELECT`, `WHERE`, `GROUP BY`, `HAVING`, and `ORDER BY` should be on their own lines by themselves.
+7. `LIMIT` should be on a new line but may be followed by the count and offset on the same line.
+8. When ordering by multiple columns, each column should be on a new line.
+
+```sql
+# Bad
+SELECT
+   column1,
+  column2  
+FROM table1
+WHERE val > 0
+GROUP BY column1
+HAVING column2 < 0
+ORDER BY column1 DESC, 
+   column2 ASC LIMIT 10   
+
+# Good
+SELECT
+    column1,
+    column2
+FROM table1
+WHERE
+    val > 0
+GROUP BY
+    column1
+HAVING
+    column2 < 0
+ORDER BY
+    column1 DESC, 
+    column2 ASC
+LIMIT 10
+```
+
+#### SQL within PHP
+
+* When using SQL within PHP, make sure to put the quotations (`"`) on their own lines and indent the query.
+
+```php
+$sql = "
+    SELECT
+        column1,
+        column2
+    FROM table1
+    WHERE
+        val > 0
+    GROUP BY
+        column1
+    HAVING
+        column2 < 0
+    ORDER BY
+        column1 DESC, 
+        column2 ASC
+    LIMIT 10
+";
+```
+
+#### **Aliasing**
+
+* Tables should only be aliased when necessary – for example, if there is more than one table with the same name in the same query.
+* Column aliases should be used when the column name is derived from a function or complex expression. Use the `AS` keyword to assign aliases.
+
+```sql
+# Bad
+SELECT column1, column2 FROM table1
+
+# Good
+SELECT
+    column1 AS alias1,
+    column2 AS alias2
+FROM table1 AS t1
+INNER JOIN table1 AS aliasTable1 ON aliasTable1.id = t1.id
+```
+
+#### Joining
+
+* The join condition should be clearly mentioned in the ON clause.
+* Each `JOIN` clause should start on a new line.
+* When using `INNER JOIN`s and `OUTER JOIN`s in the same query, always put your `INNER JOIN`s first.
+* Whenever possible, use `LEFT OUTER JOIN`s instead of `RIGHT OUTER JOIN`
+
+```sql
+# Bad
+SELECT
+    column1
+FROM table1
+INNER JOIN table2 ON table1.id = table2.id
+RIGHT OUTER JOIN table4 ON table1.id = table2.id
+INNER JOIN table3 ON table1.id = table2.id
+
+# Good
+SELECT
+    column1
+FROM table1
+INNER JOIN table2 ON table1.id = table2.id
+INNER JOIN table3 ON table1.id = table2.id
+LEFT OUTER JOIN table4 ON table1.id = table2.id
+```
+
+#### **Subqueries**
+
+* Use indentation for subqueries to clearly distinguish them from the main query.
+* Start subqueries on a new line.
+* Enclose subqueries in parentheses.
+
+```sql
+# Bad
+SELECT
+    column1,
+SELECT column2
+FROM table2
+WHERE table2.id = table1.id AS alias2
+FROM table1
+
+# Good
+SELECT
+    column1, 
+    (
+        SELECT
+            column2 
+        FROM table2 
+        WHERE
+            table2.id = table1.id
+    ) AS alias2
+FROM table1
+```
+
+#### **Conditions**
+
+* Multiple conditions in a `WHERE` clause should be on separate lines.
+* Use parentheses to group conditions when necessary for clarity and to control the logical order of operations.
+* When mixing `AND` and `OR`s together, you MUST use parentheses.
+* When adding `AND` and `OR`, start them on a new line.
+* SQL operators like `>` and `<` should be surrounded by spaces for readability.
+
+```sql
+# Bad
+SELECT
+    column1
+FROM table1 WHERE column1 > 10 AND
+    column2<20 OR column3='value'
+
+# Good
+SELECT
+    column1
+FROM table1 
+WHERE
+    column1 > 10
+    AND (
+        column2 < 20
+        OR column3 = 'value'
+    )
+```
+
+#### **SQL Comments**
+
+* If necessary, add comments to clarify complex sections of SQL code. Comments should be concise and informative.
+* Prefer to use the `#` character to begin a comment rather than `--`.
+
+```sql
+# Bad
+SELECT * # This query selects all columns from table1
+FROM table1
+WHERE column1 = 'value'
+
+# Good
+# This query selects all columns from table1
+SELECT
+    column1
+FROM table1 
+WHERE
+    column1 = 'value'
+```
+
+### **Encoding**
+
+* All data inserted into the databases must already be decoded unless otherwise specified and intended.  Ensure the data is not HTML or URL-encoded before inserting.
+  * For example, the actual `<` character should be in the database instead of the HTML-encoded value of `&lt;`
+
+### **SQL Naming Conventions**
+
+#### **Bridge Tables**
+
+* Most bridge tables need to include an underscore between the two tables they are joining. If you are joining a parent with a child table, the parent should come first. Exceptions may be made for inherent child records like `SalesOrderItems` being a child yet also a bridge of `SalesOrders`
+* All bridge tables should exactly line up with the tables they refer to, including plurals.
+* When in doubt, collaborate!
+
+```
+# Bad
+LocationAttributes_Locations  # (parent should be first)
+Order_OrderLineItem  # (missing plural, not aligned with table names)
+Contacts-Addresses  # (should use underscore)
+
+# Good
+# Locations table with child table called LocationAttributes: 
+Locations_LocationAttributes 
+
+# Two sibling tables called Posts and Authors (either are valid)
+Posts_Authors 
+Authors_Posts 
+```
+
+#### **Human-readable text fields**
+
+* All human-readable fields should be called `name` . Don't use `label` or `type` or `displayName` or `niceName`.
+* Bad examples:
+  * In a table called `Tags`, the human-readable field should NOT be `label`
+  * In a table called `Companies`, the human-readable field should NOT be `companyName`
+  * In a table called `ServiceRequestTypes`, the human-readable field should NOT be `ServiceType`
+* Good Examples:
+  * In a table called `Tags`, the human-readable field should be `name`
+  * In a table called `Companies`, the human-readable field should be `name`
+  * In a table called `ServiceRequestTypes`, the human-readable field should be `name`
+
+#### **Naming Foreign Keys**
+
+* When using a Foreign key to refer to another table:
+  1. Take the table that it's referring, such as: `Customers`
+  2. Make it singular: `Customer`
+  3. Add `id` to the end and convert to camelCase: `customerId`
+* Bad Examples (Didn't convert to camelCase, didn't convert to singular):
+  * Table name: `PurchaseOrderItems`
+  * Table you're referencing: `PurchaseOrders`
+  * Foreign key field name: `PurchaseOrdersId`
+* Good Examples:
+  * Table name: `PurchaseOrderItems`
+  * Table you're referencing: `PurchaseOrders`
+  * Foreign key field name: `purchaseOrderId`
+
+#### **Case**
+
+* Database names in PascalCase or their formal name (ie: `TOGa`)
+* Table names in PascalCase
+* Field names in camelCase
+
+**SQL Data Types**
+
+* In code you rarely write these raw types directly. A `_Model` declares each column as a `FIELD_*` constant that maps to the underlying SQL type — e.g. `FIELD_PRIMARYKEY` / `FIELD_FOREIGNKEY` (unsigned int keys), `FIELD_INTEGER`, `FIELD_BOOLEAN` (the `is*` tinyint flag), `FIELD_DECIMAL`, `FIELD_CHAR` / `FIELD_CHAR_UUID`, `FIELD_LIST` (ENUM), `FIELD_DATETIME_CREATED` / `FIELD_DATETIME_UPDATED` (auto-managed timestamps), `FIELD_BLOB`, `FIELD_STORAGE`, and `FIELD_SQL` (calculated). The SQL types below are the storage targets these constants resolve to; follow both this section and the model field-type conventions when defining columns.
+
+**Flags/Booleans**
+
+* Flag fields should begin with `is`, for example: `isVisible`
+* Data type must be set as `UNSIGNED TINYINT` with `0` representing FALSE and `1` representing TRUE
+
+#### **Varchars**
+
+* A max of 255 chars, then you must switch to a text data type
+* Should allocate in binary intervals so the only options for length would be: 1, 2, 4, 8, 16, 32, 64, 128, 255
+
+#### **Blobs**
+
+| Type         | Max Length          |
+| ------------ | ------------------- |
+| `TINYBLOB`   | 255 bytes           |
+| `BLOB`       | 65,535 bytes        |
+| `MEDIUMBLOB` | 16,777,215 bytes    |
+| `LONGBLOB`   | 4,294,967,295 bytes |
+
+#### **Integers** When storing integers, make sure to answer the following questions:
+
+**Am I storing a foreign or primary key?**\
+All keys must be unsigned integers.
+
+**Do I need to store positives and negatives, or just positives?**\
+Signed integers can reference positive and negative numbers, but unsigned can only reference positive numbers.
+
+**How large are the numbers I'm storing?**
+
+| Type        | Bytes | Min **Signed** Value | Max **Signed** Value | Min **Unsigned** Value | Max **Unsigned** Value |
+| ----------- | ----- | -------------------- | -------------------- | ---------------------- | ---------------------- |
+| `TINYINT`   | 1     | `-128`               | `127`                | `0`                    | `255`                  |
+| `SMALLINT`  | 2     | `-32,768`            | `32,767`             | `0`                    | `65,535`               |
+| `MEDIUMINT` | 3     | `-8,388,608`         | `8,388,607`          | `0`                    | `16,777,215`           |
+| `INT`       | 4     | `-2,147,483,648`     | `2,147,483,647`      | `0`                    | `4,294,967,295`        |
+| `BIGINT`    | 8     | `-2^63`              | `2^63 - 1`           | `0`                    | `2^64 - 1`             |
+
+### SQL Injection Prevention
+
+* Never interpolate raw user input into a query string. Two acceptable approaches, in order of preference:
+  1. **Use the `_Model` layer.** The metadata-driven ORM builds and escapes queries for you — prefer it over hand-written SQL whenever possible.
+  2. **When you must write SQL by hand, escape every interpolated value with `_Database::escape()`** before placing it in the query string.
+* `_Database::escape()` adds MySQL escape characters (`\`, `'`, `"`, newlines, etc.) and is the correct helper for query interpolation. Do **not** confuse it with `_Database::protect()`, which *strips* `% \ / * " '` and the literal ` or` — that is lossy filtering, not escaping, and will corrupt data you intend to store intact.
+
+```php
+// Bad — raw interpolation
+$sql = "SELECT name FROM Users WHERE username = '$username'";
+
+// Good — escape before interpolating
+$username = _Database::escape($username);
+$sql = "
+    SELECT
+        name
+    FROM Users
+    WHERE
+        username = '$username'
+";
+
+// Better — let the model layer handle it
+$user = new _Model_Client_User();
+$user->username = $username;
+if ($user->load()) { /* found */ }
+```
+
+## PHP
+
+### PHP Tags
+
+* Short tags (`<?`) are not permitted.
+* All PHP files MUST NOT end in a closing tag like this `?>` but instead with PHP code or with an open `<?php` tag followed by a line break.
+
+```html
+</html>
+<?php
+
+```
+
+### Code Formatting
+
+#### **Indentation**
+
+* Use tabs for indentation, not spaces.
+
+#### **Braces**
+
+* Opening braces for classes, methods and control structures (`if`, `else`, `for`, `while`, etc.) should go on the same line.
+
+```php
+if ($condition) {
+    // code
+} else {
+    // code
+}
+```
+
+#### Naming Conventions
+
+**Variables**
+
+* Use camelCase for variable names.
+* Names should be descriptive, avoiding abbreviations unless they are well-known.
+
+**Functions**
+
+* Use camelCase for function names.
+* Function names should be descriptive and reflect what the function does.
+
+**Classes**
+
+* Use PascalCase for class names.
+* Class names should be nouns, in singular form, and clearly represent their purpose.
+
+#### Named Arguments
+
+* The 2.0 codebase uses PHP 8 **named arguments** pervasively for built-in and framework calls to make call sites self-documenting. Follow this convention.
+
+```php
+// Preferred
+$uuid = substr(string: $value, offset: 0, length: 8);
+$list = implode(separator: ",\n", array: $fields);
+
+// Avoid (positional, harder to read at the call site)
+$uuid = substr($value, 0, 8);
+```
+
+### Documentation
+
+#### **Comments**
+
+* Use comments to explain the "why" behind the code, not the "how".
+* Inline comments should be used sparingly.
+
+#### **DocBlocks**
+
+* Every class and method should have a DocBlock that describes its purpose.
+* Parameters and return types should be clearly documented.
+* This is the required standard for all new and modified code. Existing coverage is uneven (strong in utility classes, sparse in some model classes) — bring code up to standard as you touch it.
+
+```php
+/**
+ * Calculates the sum of two integers.
+ *
+ * @param int $a The first integer.
+ * @param int $b The second integer.
+ * @return int The sum of the two integers.
+ */
+function add($a, $b) {
+    return $a + $b;
+}
+```
+
+### Security
+
+* Validate and sanitize user inputs.
+
+### Performance
+
+* Use single quotes for strings unless interpolation is needed.
+
+```php
+// Bad
+$a = "Hello";
+
+// Good
+$a = 'Hello';
+$b = "Hello $world";
+$c = 'Hello ' . $world;
+```
+
+### Miscellaneous
+
+* Use `require_once` for including files that must only be included once.
+* Avoid using global variables and global state.
+
+### PHP Resources
+
+* [PHP The Right Way](https://phptherightway.com/)
+* [PHP Standards Recommendations](https://www.php-fig.org/psr/)
+
+## Error Handling
+
+### PHP Error Handling
+
+* Always use exceptions to handle unexpected conditions.
+
+### Comprehensive Error Handling
+
+* Implement comprehensive error handling to gracefully manage exceptions and provide meaningful error messages.
+
+### Logging
+
+* Use structured logging to capture detailed information about application behavior and errors.
+
+## Security Best Practices
+
+### Input Validation and Sanitization
+
+* Validate and sanitize all user inputs to prevent common vulnerabilities such as injection attacks.
+
+### Secure Communication
+
+* Always use HTTPS to encrypt data in transit.
+
+## Performance Optimization
+
+### Caching
+
+* To improve performance, store frequently accessed data in the appropriate layer: cookies, local storage, and sessions on the client/session side; variables within a request.
+* The framework provides **built-in query-result caching** in `_Database` (enabled by default). Reuse it rather than re-running identical reads; use `_Database::useQueryCache(false)` to disable it when you need a guaranteed-fresh read (e.g. immediately after a write in the same request).
+
+### Asynchronous Processing
+
+* Use asynchronous processing for tasks that can be performed in the background to improve responsiveness.
+* Use AJAX for front-end interactions.
+* For back-end background work, **dispatch a job to the Worker system** via `_Worker::runTask($action, $parameters)` (the `worker2` queue) — do not fork processes or run long tasks inline in a request. The action maps to a `_Worker_*` class/method; webhook and cron entry points are supported. See the Worker architecture for the queue, retry, and always-HTTP-200 conventions.
+
+## API Design
+
+### RESTful API Design
+
+* Follow RESTful principles for designing APIs, ensuring that they are stateless and provide clear, consistent endpoints.
+* TOGa 2.0 API is entirely RESTful but other clients' and third party APIs may not be.
+
+### Record Scripts
+
+* Use Record Scripts within our 2.0 API when you need to build custom logic for an action on a particular record and a standard table-based RESTful approach isn't feasible.
+* They should be used very sparingly as they require custom development. They should only be used when you have a need for a scalable solution but have complex logic which wouldn't make sense to use many API calls for and handling on the front-end.
+* A good use case of Record Scripts is for returning the meta data for a page or table. This is because without a record script, the front-end would need to perform dozens of API calls to be able to gather the data necessary to render the page.
+
+#### **Procedure**
+
+1. You will need to add a record to either the `Core.RecordScripts` or `Client.CustomRecordScripts` table.
+   * If you want the record script to apply to ALL records system-wide, add it to the `Core.RecordScripts` table.
+   * If you only want the record script to apply to one client, add it to the appropriate `Client.CustomRecordScripts` table.
+2. Determine these field values and insert into either the `Core.RecordScripts` or `Client.CustomRecordScripts` table.
+   * `recordId` - Foreign key of the `Records.id` for the record you want to add the script to
+   * `method` - HTTP method you want the script to apply to (eg: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`)
+   * `route` - The string in the URL route following the record name
+   * `phpMethod` - The PHP method name within the record's model which will be called
+3. In the \_underscore framework, open/create the PHP class for the model of the record you want to add the script to.
+4. Add a public static function to the PHP class.
+   1. Use the value in `phpMethod` for the name of the method/function.
+   2. Setup parameters
+      1. The first parameter of the method **MUST be `&$api`**, an object passed by reference which contains meta and record information regarding the API transaction.
+      2. The remaining parameters are of your choice but these will be passed into the function after having been parsed from the keys in the query string. For example, passing `?slug=hello&app=supply` in the query string will be passed to the PHP method under a variable called `$slug` and `$app`.
+5. The `return` value from this function will be directly JSON-encoded and returned in the `data` element of the response payload.
+   * Note that it will not be validated for content or security, but simply JSON-encoded and returned.
+
+```php
+public static function meta(&$api, string $slug) {
+	// do a bunch of stuff...
+
+	// return the response
+	return (object)[
+		'hello' => 'world',
+		'customVariable' => 'goodbye'
+	];
+}
+```
+
+### API Payload Interceptors
+
+* An API payload interceptor is similar to a Record Script however it is meant to be used to intercept payloads to/from the table-based features of our API.
+* It would be preferred to have clients alter their payloads or response handling but an API interceptor can be used in lieu of having a client alter their programs.
+* An API payload interceptor accepts exactly two parameters and does not return anything. Both parameters **MUST be passed by reference** (`&$api` and `&$payload`).
+  * `&$api` - An object, passed by reference, which contains meta and record information regarding the API transaction.
+  * `&$payload` - The payload, passed by reference, which can be read and modified.
+* Interception Options
+  * The table and fields you insert determines whether all or some clients and all or some APIs will be intercepted.
+    * **All Clients/All APIs** - Insert into `Core.ApiPayloadInterceptors` with a `clientId` and `apiId` set to *null*.
+    * **One Client/All APIs** - Insert into `Clients.ApiPayloadInterceptors` with an `apiId` set to *null*.
+    * **One Client/One API** - Insert into `Clients.ApiPayloadInterceptors` with an `apiId` set to the `Apis.id` record you want the interceptor applied to.
+  * Intercepting the *request* or *response* payload
+    1. `prePostProcessing` value of `PRE` - Intercepts a payload *BEFORE* it gets processed where you can read the incoming request payload, alter it, and let the request payload continue through the API as if the client had made the alteration.
+    2. `prePostProcessing` value of `POST` - Intercepts a payload *AFTER* it gets processed where you can read the outgoing response payload, alter it, and return the response payload to the client with your alterations.
+
+#### **Procedure**
+
+1. Determine these field values and insert into either the `Core.ApiPayloadInterceptors` or `Client.ApiPayloadInterceptors` table.
+   * `clientId` - The `Core.ApiPayloadInterceptors` table contains a `clientId` field which is a foreign key to `Core.Clients.id` and is meant to specify which client the next field, `apiId`, is referring to. Leave *null* to intercept all APIs for all clients.
+   * `apiId` - Foreign key of the `Apis.id` for the API key you want to intercept. Leave *null* to intercept all APIs for all clients.
+   * `recordId` - Foreign key of the `Records.id` for the record you want to intercept
+   * `prePostProcessing` - Can be either `PRE` or `POST`. This will determine whether the payload will be intercepted before or after the processing. In other words, `PRE` will intercept the *request* payload while `POST` will intercept the *response* payload.
+   * `httpMethod` - HTTP method you want to intercept (eg: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`)
+   * Note: unlike Record Scripts, the interceptor table has **no `phpMethod` field**. The method name is **derived by convention** from `prePostProcessing` + `httpMethod` (other relevant fields: `isActive`, `minDepth`).
+2. In the \_underscore framework, open/create the PHP class for the model of the record you want to add the interceptor to.
+3. Add a public static function to the PHP class.
+   1. Name the method by convention: `strtolower(prePostProcessing)` + `ucfirst(strtolower(httpMethod))`. So a `PRE`/`PUT` interceptor is `prePut`, a `POST`/`GET` interceptor is `postGet`, etc. The engine resolves and calls this name automatically — you do not register it anywhere.
+   2. Setup the two required parameters. Both **MUST be passed by reference**.
+      * `&$api` - An object, passed by reference, which contains meta and record information regarding the API transaction.
+      * `&$payload` - The payload, passed by reference, which can be read and modified. The method returns nothing.
+
+```php
+// Convention: PRE + PUT => prePut
+public static function prePut(&$api, &$payload) {
+	if (isset($payload->hello)) {
+		$payload->hello = 'world';	// overwrites value to world
+	}
+}
+```
+
+### API Versioning
+
+* Implement a new version (ie: `/v1`, `/v2`, `/v3`) when a major API framework is introduced to manage the new API framework without breaking existing clients.
+
+## Deployment and Scalability
+
+### Scalability
+
+* Design your application to scale horizontally by distributing the load across multiple cloud servers or instances.
+
+### Deployment Best Practices
+
+* Use continuous integration/continuous deployment (CI/CD) pipelines to automate the deployment process and ensure consistent deployments.
+
+## Logging and Monitoring
+
+### Structured Logging
+
+* Ensure logs are structured and include relevant context for easier debugging.
+
+### Monitoring and Alerts
+
+* Implement and alerting for your applications to catch issues early.
+
+## Configuration Management
+
+### Environment Configuration
+
+* Manage configuration through environment variables and configuration files.
+
+### Secrets Management
+
+* Use secret management tools to handle sensitive information like API keys and passwords.
+
+## Code Quality and Maintainability
+
+### Code Reviews
+
+* Establish a thorough code review process to ensure code quality and knowledge sharing.
+
+### Static Code Analysis
+
+* Integrate static code analysis tools to catch issue early.
+
+## Security
+
+### Authentication and Authorization
+
+* Implement robust authentication and authorization methods such as OAuth2 and JWT.
+* Ensure role-based access control (RBAC) is implemented.
+
+### Data Encryption
+
+* Ensure sensitive data is encrypted both in transit and at rest.
+
+## Documentation
+
+### API Documentation
+
+* Maintain clear and comprehensive API documentation.
+* Use Postman for API testing and storage of API scripts and clients' API documentation.
+
+### Code Documentation
+
+* Ensure code is well-documented with comments and usage examples.