docs

README.md

@@ -18,13 +18,25 @@
 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=chevere_sql2p&metric=sqale_index)](https://sonarcloud.io/dashboard?id=chevere_sql2p)
 [![CodeFactor](https://www.codefactor.io/repository/github/chevere/sql2p/badge)](https://www.codefactor.io/repository/github/chevere/sql2p)
 
+![SQL2P](.github/banner/sql2p-logo.svg)
+
 ## Summary
 
-SQL2P generates [Parameter(s)](https://chevere.org/library/parameter) for MySQL schemas.
+SQL2P generates [Parameter(s)](https://chevere.org/library/parameter) for MySQL schemas. It represents database tables and its columns using the Parameter package.
+
+## Installing
+
+SQL2P is available through [Packagist](https://packagist.org/packages/chevere/sql2p) and the repository source is at [chevere/sql2p](https://github.com/chevere/sql2p).
+
+```sh
+composer require chevere/sql2p
+```
 
-From a `CREATE TABLE` statement like this:
+## How it works?
 
-```SQL
+From a `CREATE TABLE` statement like this one below.
+
+```sql
 CREATE TABLE `invoice` (
   `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
   `client_id` INT UNSIGNED NOT NULL,
@@ -34,10 +46,10 @@ CREATE TABLE `invoice` (
   `rate` DECIMAL(10,2) NOT NULL,
   `total` DECIMAL(19,4) GENERATED ALWAYS AS (quantity*rate),
   PRIMARY KEY (`id`)
-ENGINE = InnoDB;
+) ENGINE = InnoDB;
 ```
 
-It generates the following PHP code:
+SQL2P generates the following PHP code.
 
 ```php
 use Chevere\Parameter\Interfaces\ArrayParameterInterface;
@@ -66,17 +78,27 @@ function invoiceTable(): ArrayParameterInterface
 }
 ```
 
-## Installing
+The `invoiceTable()` function returns table `invoice` schema in PHP code using [Array](https://chevere.org/packages/parameter#array) Parameter where each column is represented by another Parameter.
 
-SQL2P is available through [Packagist](https://packagist.org/packages/chevere/sql2p) and the repository source is at [chevere/sql2p](https://github.com/chevere/sql2p).
+From this you can add your own validation rules on top of generated code.
 
-```sh
-composer require chevere/sql2p
+For example, you limit `quantity` to a range of `100, 200` by adding `max` and `min` arguments. Add a regex to `details` to validate string shape.
+
+```diff
+details: union(
+    null(),
+-    string()
++    string('/^(?!\s*$)./')
+),
+-quantity: int(min: 0),
++quantity: int(max: 200, min: 100),
 ```
 
+The Array Parameter object returned by this function can be also used to dynamic interact with one or more of these columns.
+
 ## Creating SQL2P
 
-Create a `SQL2P` instance by passing the SQL and a [WriterInterface](https://chevere.org/packages/writer) instance. On instance creation the SQL is parsed and the writer is used to write the generated code.
+Create a `SQL2P` instance by passing the SQL and a [Writer](https://chevere.org/packages/writer) instance. On instance creation the SQL is parsed and the writer is used to write the generated code.
 
 ```php
 use Chevere\SQL2P\SQL2P;
@@ -101,6 +123,145 @@ echo <<<PLAIN
 PLAIN;
 ```
 
+## Data validation
+
+Use SQL2P to validate data against table Parameter schema.
+
+For example, on a single fetch result you may get the following array for a database row.
+
+```sql
+SELECT * FROM invoice WHERE id = 1
+```
+
+```php
+$fetch = [
+    'id' => 1,
+    'client_id' => 1234,
+    'datetime' => '2023-10-22 19:58:44',
+    'details' => null,
+    'quantity' => 100,
+    'rate' => 16.5,
+    'total' => 1650,
+];
+```
+
+Function `invoiceTable()` can be used to validate `$fetch` by invoking it.
+
+```php
+$table = invoiceTable();
+$table($fetch); // validation
+```
+
+Use `arrayFrom` function to create an array taking only the columns you need.
+
+```sql
+SELECT id, total FROM invoice WHERE id = 1
+```
+
+```php
+use function Chevere\Parameter\arrayFrom;
+
+$fetch = [
+    'id' => 1,
+    'total' => 1650,
+];
+$table = arrayFrom(invoiceTable(), 'id', 'total');
+$table($fetch);
+```
+
+Use `arguments` function to get typed access to fetched array members.
+
+```php
+use function Chevere\Parameter\arguments;
+
+$invoice = arguments($table, $fetch);
+$total = $invoice->required('total')->int(); // 1650
+```
+
+When fetching multiple rows wrap Array table with [iterable](https://chevere.org/packages/parameter.html#iterable) function.
+
+```sql
+SELECT id, total FROM invoice WHERE id > 0
+```
+
+```php
+$fetchAll = [
+    0 => [
+        'id' => 1,
+        'total' => 1650,
+    ],
+    1 => [
+        'id' => 2,
+        'total' => 1820,
+    ],
+];
+$iterable = iterable($table);
+$iterable($fetchAll);
+```
+
+Note that `arguments` function supports iterable.
+
+```php
+$invoices = arguments($iterable, $fetchAll);
+$secondRow = $invoices->required('1')->array();
+```
+
+## Composing Array
+
+Parameter provides a set of tools to work with arrays, enabling to dynamically add, remove or modify values. It also enables to compose arrays from other arrays.
+
+For example to add a `total_usd` virtual column to `invoiceTable()`.
+
+```sql
+SELECT
+    id,
+    total,
+    total/100 total_usd
+FROM invoice WHERE id = 1
+```
+
+```php
+$fetch = [
+    'id' => 1,
+    'total' => 1650,
+    'total_usd' => 16.5,
+];
+$table = arrayFrom(invoiceTable(), 'id', 'total');
+$table = $table
+    ->withRequired(
+        total_usd: float(),
+    );
+$table($fetch);
+```
+
+When `JOIN` tables you may want to take columns based on joined tables. Use `takeFrom` function to create a iterable with `column => parameter` pairs.
+
+```sql
+SELECT
+    invoice.id,
+    invoice.total,
+    client.name,
+    client.email
+FROM invoice
+JOIN client ON client.id = invoice.client_id
+WHERE invoice.id = 1
+```
+
+```php
+$fetch = [
+    'id' => 1,
+    'total' => 1650,
+    'name' => 'Rodolfo',
+    'email' => '[email protected]'
+];
+$invoice = arrayFrom(invoiceTable(), 'id', 'total');
+$client = takeFrom(clientTable(), 'name', 'email');
+$table = $invoice->withRequired(...$client);
+$table($fetch);
+```
+
+For this code `$client` is assigned to an iterable containing `name` and `email` column pairs from `clientTable()`. Then by calling `withRequired` on `$invoice` it gets these columns on spread.
+
 ## Documentation
 
 Documentation is available at [chevere.org](https://chevere.org/packages/sql2p).