Update docs

Author: phpfui

README.md

@@ -1,7 +1,7 @@
 # PHPFUI\ORM [![Tests](https://github.com/phpfui/ORM/actions/workflows/tests.yml/badge.svg)](https://github.com/phpfui/ORM/actions?query=workflow%3Atests) [![Latest Packagist release](https://img.shields.io/packagist/v/phpfui/ORM.svg)](https://packagist.org/packages/phpfui/ORM) ![](https://img.shields.io/badge/PHPStan-level%205-brightgreen.svg?style=flat)
 
 ### PHPFUI\ORM a minimal Object Relational Mapper (ORM) for MySQL, MariaDB and SQLite3
-Why another PHP ORM? In writing minimal and fast websites, it was determined that existing PHP ORM solutions were overly complex. **PHPFUI\ORM** is less than 6k lines of code in under 50 files.  It is designed to have a minimal memory footprint and excellent execution times for most database needs.
+Why another PHP ORM? In writing minimal and fast websites, it was determined that existing PHP ORM solutions were overly complex. **PHPFUI\ORM** is a little more than 6K lines of code in under 50 files.  It is designed to have a minimal memory footprint and excellent execution times for most database needs.
 
 **PHPFUI\ORM** is not an attempt to write an abstraction around SQL as other ORMs do, rather it is a way to work with SQL that closely matches the semantics of SQL, with the power of PHP objects.  It allows PHP to manipulate SQL queries without having to write SQL in plain text. This is very useful for queries generated via user interfaces where the user is given a lot of flexability in how a query is defined.
 

docs/1. Setup.md

@@ -23,7 +23,7 @@ Deletion of unused models should be done manually when the table is removed from
 ## PHP Class Naming Conventions
 All **PHPFUI\ORM** classes and namespaces use StudlyCase naming conventions.  SQL table names are used the generate the PHP class names.  Case is preserved except the first letter is the converted to upper case.  Table names with underscores are converted to StudlyCase and underscores are removed. Field names are not affected and left unchanged.
 
-Each table will generate 3 classes (4 if validators are generated) with the same class name, but in the specified namespaces (see below).  **Definition** and **Validation** namespaces are children of the record namespace.
+Each table will generate 3 classes (4 if validators are generated) with the same class name, but in the specified namespaces (see below).  **Definition** and **Validation** namespaces are children of the **Record** namespace.
 
 ## Configuration
 **PHPFUI\ORM** needs the following information to work with your code:

docs/10. Miscellaneous.md

@@ -31,7 +31,7 @@ Returne the value from the first field in the first row returned by the querry,
 Returns the data values of the first element in each row of the query.
 
 ## **\PHPFUI\ORM\Record** Data Cleaning Helpers
-The Record class provides some simple data cleaning functions you can use where needed.
+The [\PHPFUI\ORM\Record](http://phpfui.com/?n=PHPFUI%5CORM&c=Record) class provides some simple data cleaning functions you can use where needed.
 * **cleanUpperCase**(string $field) Converts the field to all upper case
 * **cleanLowerCase**(string $field) Converts the field to all lower case
 * **cleanNumber**(string $field) removes all non-digits (0-9 and -) from string representation of a number

docs/2. Active Record.md

@@ -31,7 +31,7 @@ A **Record** constructor attempts to read the specified row from the table. It c
 - **array** record is attempted to be read from database using the values of the fields provided.
 - **null** (default) constructs an empty object.
 
-Both int and string parameters to the constructor are type checked. Calling the constructor with a parameter can be see as the same as, but with type checking:
+Both int and string parameters to the constructor are type checked. Calling the constructor with a parameter can be see as the same as the following, but with type checking:
 ```php
 $customer = new \App\Record\Customer();
 $customer->read($value);
@@ -41,7 +41,7 @@ $customer->read($value);
 - **insert**() or **create**()
  * Adds the current record to the database. If the primary key already exists in the database, the insert fails. The auto increment primary key is updated with the value inserted.
  * insert() returns the primary key value inserted, true if no primary key and the record was successfully inserted or false on error.
-- **insertOrUpdate**()
+- **insertOrUpdate**() or **save**()
  * Will try to insert the record and on a duplicate key, will update the record with the current values.
  * insertOrUpdate() returns the same values as insert().
  * If the record only consists of primary keys, then this method is equivalent to insertOrIgnore().
@@ -80,7 +80,7 @@ $customer->read($value);
  * Returns an array of errors indexed by field name. Empty array means the record has correctly validated.
 
 ## Related Records
-Related records are indicated by field name ending in the id suffix (default: 'Id').  The field name before the 'Id' must be the same as the corresponding table name. See See [Virtual Fields](<https://github.com/phpfui/ORM/blob/main/docs/5. Virtual Fields.md>) for more advanced Related Records.
+Related records are indicated by field name ending in the id suffix (default: 'Id').  The field name before the 'Id' must be the same as the corresponding table name. See See [Virtual Fields](https://github.com/phpfui/ORM/blob/main/docs/5.%20Virtual%20Fields.md) for more advanced Related Records.
 
 ### Accessing Related Records
 You access the related record by the base field name (without the id suffix). The field with the id suffix is the primary key of the related record.
@@ -145,7 +145,7 @@ Notice that we did not have to save the customer record.  By assigning it to the
 You can always just assign the id's directly: `$orderDetail->purchase_order_id = $purchase_order->purchase_order_id;`. Saving the OrderDetail record is up to you.
 
 ### Other Types Of Related Records
-See [Virtual Fields](<https://github.com/phpfui/ORM/blob/main/docs/5. Virtual Fields.md>) for information on how to impliment child or many to many relationships.
+See [Virtual Fields](https://github.com/phpfui/ORM/blob/main/docs/5.%20Virtual%20Fields.md) for information on how to impliment child or many to many relationships.
 
 ### Multi Database Support
 Related Records will always return a record from the currently selected database. Care must be taken when using multiple databases that any references to related records are done while the correct database instance is active. Cursors will continue to use the database in effect when they were created.

docs/3. Active Table.md

@@ -1,5 +1,5 @@
 # PHPFUI\ORM Active Table
-While an **Active Record** represents a single row in the database table, an **Active Table** represents the entire table. [\PHPFUI\ORM\Table](http://phpfui.com/?n=PHPFUI%5CORM&c=Table) allows you to find, select, update and delete multiple records at a time.
+While an **Active Record** represents a single row in the database table, an **Active Table** represents the entire table. [\PHPFUI\ORM\Table](http://phpfui.com/?n=PHPFUI%5CORM&c=Table) allows you to find, select, update, insert and delete multiple records at a time.
 
 **Active Tables** are easy to manipulate in code and free you from constructing SQL statements with plain text.
 
@@ -72,7 +72,7 @@ $condition->or($conditionB);
 ```
 The above will produce the PDO equivalent of `(lastName >= 'R' AND lastName < 'S') OR (lastName >= 'F' AND lastName < 'G')`
 
-The [In](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=In) and [NotIn](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=NotIn) operators require the second parameter to [Condition](http://phpfui.com/?n=PHPFUI\ORM&c=Condition).  The [Like](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=Like) and [NotLike](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=NotLike) operators will respect the % and _ characters, but you are responsible for putting them in the correct positions.
+The [In](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=In) and [NotIn](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=NotIn) operators require the second parameter to [Condition](http://phpfui.com/?n=PHPFUI\ORM&c=Condition) to be an array.  The [Like](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=Like) and [NotLike](http://phpfui.com/?n=PHPFUI\ORM\Operator&c=NotLike) operators will respect the % and _ characters, but you are responsible for putting them in the correct positions.
 
 #### Literal and Field classes
 Sometimes you need to compare something to a SQL constant or call a function.  You can use `new \PHPFUI\ORM\Literal('CURRENT_TIMESTAMP()')`.

docs/4. Cursors.md

@@ -35,7 +35,7 @@ foreach ($customerTable->getDataObjectCursor() as $record)
   }
 ```
 ### RecordCursor
-A **RecordCursor** returns a **\PHPFUI\ORM\Record** typed from the table. It is a fully functional **Active Record**. It also implements [ArrayAccess](https://www.php.net/manual/en/class.arrayaccess.php), but is not an array.
+A **RecordCursor** returns a [\PHPFUI\ORM\Record](http://phpfui.com/?n=PHPFUI%5CORM&c=Record) typed from the table. It is a fully functional **Active Record**. It also implements [ArrayAccess](https://www.php.net/manual/en/class.arrayaccess.php), but is not an array.
 ```php
 $customerTable = new \App\Table\Customer();
 $customerTable->setWhere(new \PHPFUI\ORM\Condition('first_name', 'Fred'));
@@ -49,5 +49,5 @@ foreach ($customerTable->getDataObjectCursor() as $record)
   }
 ```
 
-Please note that the **RecordCursor** reuses the same **\PHPFUI\ORM\Record** instance to conserve memory, so they will need to be cloned if added to an array or cursor.  **DataObjectCursor** and **ArrayCursor** return new objects.
+Please note that the [\PHPFUI\ORM\Record](http://phpfui.com/?n=PHPFUI%5CORM&c=Record) reuses the same **\PHPFUI\ORM\Record** instance to conserve memory, so they will need to be cloned if added to an array or cursor.  **DataObjectCursor** and **ArrayCursor** return new objects.
 

docs/5. Virtual Fields.md

@@ -5,7 +5,7 @@ You can define virtual fields with get and set semantics for any **\App\Record**
 
 Every **\App\Record** class has a static $virtualFields array defined. The key of the array is the name of the virtual key.  The value for each virtual field is an array of strings. The first string is the virtual field class name. Subsequent parameters are are passed the the **getValue** and **setValue** methods.
 
-Note that virtual fields are created each time they are accessed and not stored or cached in the \PHPFUI\ORM\Record object.  This means you can not change the virtual field on the Record object itself. You can only assign it to the Record object, which will store the value represented by the virtual field in the object, but not the virtual field itself.
+Note that virtual fields are created each time they are accessed and not stored or cached in the [\PHPFUI\ORM\Record](http://phpfui.com/?n=PHPFUI%5CORM&c=Record) object.  This means you can not change the virtual field on the **Record** object itself. You can only assign it to the Record object, which will store the value represented by the virtual field in the object, but not the virtual field itself.
 
 The **VirtualField** class has two properties that will always be defined for use by the derived class:
 * $currentRecord is the current record that the virtual field should be based on.
@@ -35,13 +35,13 @@ Sometimes you can't name a related record with the name of the table.  For examp
 You can make them all return employees with the following virtual field definitions:
 ```php
 class Order extends \Tests\App\Record\Definition\Order
-	{
-	protected static array $virtualFields = [
-		'salesPerson' => [\PHPFUI\ORM\RelatedRecord::class, \App\Record\Employee::class],
-		'packedBy' => [\PHPFUI\ORM\RelatedRecord::class, \App\Record\Employee::class],
-		'inspectedBy' => [\PHPFUI\ORM\RelatedRecord::class, \App\Record\Employee::class],
-	];
-	}
+  {
+  protected static array $virtualFields = [
+    'salesPerson' => [\PHPFUI\ORM\RelatedRecord::class, \App\Record\Employee::class],
+    'packedBy' => [\PHPFUI\ORM\RelatedRecord::class, \App\Record\Employee::class],
+    'inspectedBy' => [\PHPFUI\ORM\RelatedRecord::class, \App\Record\Employee::class],
+    ];
+  }
 ```
 ### Usage
 ```php
@@ -88,7 +88,7 @@ class Order extends \Tests\App\Record\Definition\Order
   }
 ```
 
-By default, child records will be automatically deleted when the parent record is deleted. You can disable this functionality for a specific record class by setting the static property $deleteChildren to false, or using your own Children class.
+By default, child records will be automatically deleted when the parent record is deleted. You can disable this functionality for a specific [\PHPFUI\ORM\Record](http://phpfui.com/?n=PHPFUI%5CORM&c=Record) class by setting the static property $deleteChildren to false, or using your own Children class.
 
 ### Usage
 ```php
@@ -137,12 +137,12 @@ Use \PHPFUI\ORM\Cast virtual field to accommplish this. The Cast virtual field w
 ### Usage
 ```php
 class Invoice extends \Tests\App\Record\Definition\Order
-	{
-	protected static array $virtualFields = [
-  	'due_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
-		'invoice_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
-	];
-	}
+  {
+  protected static array $virtualFields = [
+    'due_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
+    'invoice_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
+    ];
+  }
 $invoice = new Invoice(20);
 echo 'Lead Weeks: ' . $invoice->invoice_date->diffInWeeks($invoice->due_date);
 ```

docs/7. Validation.md

@@ -1,7 +1,7 @@
 # PHPFUI\ORM Validation
 *__Note__: Referenced namespaces in this document refer to the **PHPFUI\ORM** defaults.*
 
-Validator is an abstract class for Record validation See [\PHPFUI\ORM\Validator](http://phpfui.com/?n=PHPFUI%5CORM&c=Validator) namespace for examples.
+Validator is an abstract class for **\App\Record** validation See [\PHPFUI\ORM\Validator](http://phpfui.com/?n=PHPFUI%5CORM&c=Validator) namespace for examples.
 
 Individual validators are listed in the table below. Validators can be combined.  For example, a field can be **required**, and have a **minlength** and **maxlength**. Validators can have parameters. Parameters are separated by a colon (:) and then commas for each separate parameter.
 
@@ -22,9 +22,9 @@ foreach ($validationErrors as $field => $fieldErrors)
   {
   echo "Field {$field} has the following errors:\n";
   foreach ($fieldErrors as $error)
-	  {
-	  echo $error . "\n";
-	  }
+    {
+    echo $error . "\n";
+    }
   }
 ```
 
@@ -73,7 +73,7 @@ foreach ($validationErrors as $field => $fieldErrors)
 | year_month     | Loosely formatted Year Month | None |
 
 ## Field Comparison Validators
-You can compare one field to another on the same Record with the field validators.
+You can compare one field to another on the same **\App\Record** with the field validators.
 * gt_field
 * lt_field
 * gte_field
@@ -113,10 +113,10 @@ You can also pass an optional method to validate to perform more complex validat
 ## Multi Validator Example
 ```php
 class Order extends \PHPFUI\ORM\Validator
-	{
-	/** @var array<string, string[]> */
-	public static array $validators = [
-		'order_date' => ['required', 'maxlength', 'datetime', 'minvalue:2000-01-01', 'maxvalue:2099-12-31'],
-		];
-	}
+  {
+  /** @var array<string, string[]> */
+  public static array $validators = [
+    'order_date' => ['required', 'maxlength', 'datetime', 'minvalue:2000-01-01', 'maxvalue:2099-12-31'],
+    ];
+  }
 ```

docs/9. Transactions.md

@@ -7,11 +7,11 @@ $transaction = new \PHPFUI\ORM\Transaction();
 if ($allGood)
   {
   $transaction->commit();
-	}
+  }
 else
   {
   $transaction->rollBack();
-	}
+  }
 ```
 The above creates a transaction on the current database.  Commit and rollback will also be called on the correct database even if you are working on another database at the time.
 

src/PHPFUI/ORM/Table.php

@@ -826,6 +826,9 @@ public function setOrderBy(string $field, string $ascending = 'ASC') : self
 		return $this->addOrderBy($field, $ascending);
 		}
 
+	/**
+	 * Set user defined select fields.
+	 */
 	public function setSelectFields(string $clause) : static
 		{
 		$fields = \explode(',', $clause);