Merge branch 'develop' into feature/introduce-aggregate-model

Author: mvorisek

.github/workflows/test-unit.yml

@@ -77,7 +77,9 @@ jobs:
     name: Unit
     runs-on: ubuntu-latest
     container:
-      image: ghcr.io/mvorisek/image-php:${{ matrix.php }}
+      # Alpine support for newer pdo_oci is broken, see https://github.com/mlocati/docker-php-extension-installer/issues/523
+      # remove once config.m4 checks are working on Alpine
+      image: ghcr.io/mvorisek/image-php:${{ matrix.php }}-debian
     strategy:
       fail-fast: false
       matrix:
@@ -152,6 +154,7 @@ jobs:
           php -r '(new PDO("mysql:host=mysql56", "root", "atk4_pass_root"))->exec("GRANT USAGE ON *.* TO '"'"'atk4_test_user'"'"'@'"'"'%'"'"' WITH MAX_USER_CONNECTIONS 5");'
           php -r '(new PDO("mysql:host=mariadb", "root", "atk4_pass_root"))->exec("ALTER USER '"'"'atk4_test_user'"'"'@'"'"'%'"'"' WITH MAX_USER_CONNECTIONS 5");'
           php -r '(new PDO("pgsql:host=postgres;dbname=atk4_test", "atk4_test_user", "atk4_pass"))->exec("ALTER ROLE atk4_test_user CONNECTION LIMIT 1");'
+          /usr/lib/oracle/setup.sh
           if [ -n "$LOG_COVERAGE" ]; then mkdir coverage; fi
 
       - name: "Run tests: SQLite"
@@ -206,7 +209,7 @@ jobs:
 
       - name: "Run tests: MSSQL"
         env:
-          DB_DSN: "sqlsrv:host=mssql;dbname=master"
+          DB_DSN: "sqlsrv:host=mssql;dbname=master;driverOptions[TrustServerCertificate]=1"
           DB_USER: sa
           DB_PASSWORD: atk4_pass
         run: |

README.md

@@ -149,7 +149,7 @@ class JobReport extends Job {
         $timesheet->getRef('client_id')->addField('hourly_rate');
 
         // calculate timesheet cost expression
-        $timesheet->addExpression('cost', '[hours]*[hourly_rate]');
+        $timesheet->addExpression('cost', ['expr' => '[hours] * [hourly_rate]']);
 
         // build relation between Job and Timesheets
         $this->hasMany('Timesheets', ['model' => $timesheet])
@@ -159,10 +159,10 @@ class JobReport extends Job {
             );
 
         // finally lets calculate profit
-        $this->addExpression('profit', '[invoiced]-[reported]');
+        $this->addExpression('profit', ['expr' => '[invoiced] - [reported]']);
 
         // profit margin could be also useful
-        $this->addExpression('profit_margin', 'coalesce([profit] / [invoiced], 0)');
+        $this->addExpression('profit_margin', ['expr' => 'coalesce([profit] / [invoiced], 0)']);
     }
 }
 ```
@@ -189,7 +189,7 @@ $chart = new \Atk4\Chart\BarChart();
 $data = new JobReport($db);
 
 // BarChart wants aggregated data
-$data->addExpression('month', 'month([date])');
+$data->addExpression('month', ['expr' => 'month([date])']);
 $aggregate = new AggregateModel($data);
 $aggregate->setGroupBy('month', ['profit_margin' => 'sum']);
 

docs/advanced.rst

@@ -549,7 +549,7 @@ that shows how much amount is closed and `amount_due`::
     // define field to see closed amount on invoice
     $this->hasMany('InvoicePayment')
         ->addField('total_payments', ['aggregate' => 'sum', 'field' => 'amount_closed']);
-    $this->addExpression('amount_due', '[total]-coalesce([total_payments],0)');
+    $this->addExpression('amount_due', ['expr' => '[total] - coalesce([total_payments], 0)']);
 
 Note that I'm using coalesce because without InvoicePayments the aggregate sum
 will return NULL. Finally let's build allocation method, that allocates new
@@ -699,7 +699,7 @@ If you wish to use a different value instead, you can create an expression::
     if($m->_isset('category') && !$m->_isset('category_id')) {
         $c = $this->refModel('category_id');
         $c->addCondition($c->title_field, 'like', $m->get('category'));
-        $m->set('category_id', $this->expr('coalesce([],[])',[
+        $m->set('category_id', $this->expr('coalesce([], [])',[
             $c->action('field',['id']),
             $m->getField('category_id')->default
         ]));

docs/design.rst

@@ -319,7 +319,7 @@ Code::
             $this->addField('password_change_date');
 
             $this->addExpression('is_password_expired', [
-                '[password_change_date] < (NOW() - INTERVAL 1 MONTH)',
+                'expr' => '[password_change_date] < (NOW() - INTERVAL 1 MONTH)',
                 'type' => 'boolean',
             ]);
         }

docs/expressions.rst

@@ -15,14 +15,14 @@ use result as an output.
 Expressions solve this problem by adding a read-only field to your model that
 corresponds to an expression:
 
-.. php:method:: addExpression($link, $model);
+.. php:method:: addExpression($name, $seed);
 
 Example will calculate "total_gross" by adding up values for "net" and "vat"::
 
     $m = new Model_Invoice($db);
     $m->addFields(['total_net', 'total_vat']);
 
-    $m->addExpression('total_gross', '[total_net]+[total_vat]');
+    $m->addExpression('total_gross', ['expr' => '[total_net] + [total_vat]']);
     $m = $m->load(1);
 
     echo $m->get('total_gross');
@@ -45,9 +45,9 @@ values for the other fields including other expressions.
 
 There are other ways how you can specify expression::
 
-    $m->addExpression('total_gross',
-        $m->expr('[total_net]+[total_vat] + [fee]', ['fee' => $fee])
-    );
+    $m->addExpression('total_gross', [
+        'expr' => $m->expr('[total_net] + [total_vat] + [fee]', ['fee' => $fee])
+    ]);
 
 This format allow you to supply additional parameters inside expression.
 You should always use parameters instead of appending values inside your
@@ -64,7 +64,7 @@ unite a few statistical queries. Let's start by looking a at a very basic
 example::
 
     $m = new Model($db, ['table' => false]);
-    $m->addExpression('now', 'now()');
+    $m->addExpression('now', ['expr' => 'now()']);
     $m = $m->loadAny();
     echo $m->get('now');
 
@@ -80,9 +80,9 @@ can be gained when you need to pull various statistical values from your
 database at once::
 
     $m = new Model($db, ['table' => false]);
-    $m->addExpression('total_orders', (new Model_Order($db))->action('count'));
-    $m->addExpression('total_payments', (new Model_Payment($db))->action('count'));
-    $m->addExpression('total_received', (new Model_Payment($db))->action('fx0', ['sum', 'amount']));
+    $m->addExpression('total_orders', ['expr' => (new Model_Order($db))->action('count')]);
+    $m->addExpression('total_payments', ['expr' => (new Model_Payment($db))->action('count')]);
+    $m->addExpression('total_received', ['expr' => (new Model_Payment($db))->action('fx0', ['sum', 'amount'])]);
 
     $data = $m->loadOne()->get();
 
@@ -101,9 +101,9 @@ Expression Callback
 
 You can use a callback method when defining expression::
 
-    $m->addExpression('total_gross', function($m, $q) {
-        return '[total_net]+[total_vat]';
-    });
+    $m->addExpression('total_gross', ['expr' => function ($m, $q) {
+        return '[total_net] + [total_vat]';
+    }, 'type' => 'float']);
 
 Model Reloading after Save
 --------------------------
@@ -123,7 +123,7 @@ the following model::
 
             $this->addFields(['a', 'b']);
 
-            $this->addExpression('sum', '[a]+[b]');
+            $this->addExpression('sum', ['expr' => '[a] + [b]']);
         }
     }
 

docs/model.rst

@@ -167,13 +167,13 @@ You may safely rely on `$this->persistence` property to make choices::
    if ($this->persistence instanceof \Atk4\Data\Persistence\Sql) {
 
       // Calculating on SQL server is more efficient!!
-      $this->addExpression('total', '[amount] + [vat]');
+      $this->addExpression('total', ['expr' => '[amount] + [vat]']);
    } else {
 
       // Fallback
-      $this->addCalculatedField('total', function($m) {
+      $this->addCalculatedField('total', ['expr' => function ($m) {
          return $m->get('amount') + $m->get('vat');
-      } );
+      }, 'type' => 'float']);
    }
 
 To invoke code from `init()` methods of ALL models (for example soft-delete logic),
@@ -251,20 +251,20 @@ Although you may make any field read-only::
 
 There are two methods for adding dynamically calculated fields.
 
-.. php:method:: addExpression($name, $definition)
+.. php:method:: addExpression($name, $seed)
 
 Defines a field as server-side expression (e.g. SQL)::
 
-   $this->addExpression('total', '[amount] + [vat]');
+   $this->addExpression('total', ['expr' => '[amount] + [vat]']);
 
 The above code is executed on the server (SQL) and can be very powerful.
 You must make sure that expression is valid for current `$this->persistence`::
 
-   $product->addExpression('discount', $this->refLink('category_id')->fieldQuery('default_discount'));
+   $product->addExpression('discount', ['expr' => $this->refLink('category_id')->fieldQuery('default_discount')]);
    // expression as a sub-select from referenced model (Category) imported as a read-only field
    // of $product model
 
-   $product->addExpression('total', 'if([is_discounted], ([amount]+[vat])*[discount], [amount] + [vat])');
+   $product->addExpression('total', ['expr' => 'if ([is_discounted], ([amount] + [vat])*[discount], [amount] + [vat])']);
    // new "total" field now contains complex logic, which is executed in SQL
 
    $product->addCondition('total', '<', 10);
@@ -273,17 +273,17 @@ You must make sure that expression is valid for current `$this->persistence`::
 
 For the times when you are not working with SQL persistence, you can calculate field in PHP.
 
-.. php:method:: addCalculatedField($name, $callback)
+.. php:method:: addCalculatedField($name, ['expr' => $callback])
 
 Creates new field object inside your model. Field value will be automatically
 calculated by your callback method right after individual record is loaded by the model::
 
    $this->addField('term', ['caption' => 'Repayment term in months', 'default' => 36]);
    $this->addField('rate', ['caption' => 'APR %', 'default' => 5]);
 
-   $this->addCalculatedField('interest', function($m) {
+   $this->addCalculatedField('interest', ['expr' => function ($m) {
       return $m->calculateInterest();
-   });
+   }, 'type' => 'float']);
 
 .. important:: always use argument `$m` instead of `$this` inside your callbacks. If model is to be
    `clone`d, the code relying on `$this` would reference original model, but the code using
@@ -292,14 +292,14 @@ calculated by your callback method right after individual record is loaded by th
 This can also be useful for calculating relative times::
 
    class MyModel extends Model {
-      use HumanTiming; // See https://stackoverflow.com/questions/2915864/php-how-to-find-the-time-elapsed-since-a-date-time
+      use HumanTiming; // see https://stackoverflow.com/questions/2915864/php-how-to-find-the-time-elapsed-since-a-date-time
 
       function init(): void {
          parent::init();
 
-         $this->addCalculatedField('event_ts_human_friendly', function($m) {
+         $this->addCalculatedField('event_ts_human_friendly', ['expr' => function ($m) {
             return $this->humanTiming($m->get('event_ts'));
-         });
+         }]);
 
       }
    }
@@ -742,6 +742,6 @@ Setting limit and sort order
     You can also use \Atk4\Data\Persistence\Sql\Expression or array of expressions instead of field name here.
     Or even mix them together::
 
-        $m->setOrder($m->expr('[net]*[vat]'));
-        $m->setOrder([$m->expr('[net]*[vat]'), $m->expr('[closing]-[opening]')]);
-        $m->setOrder(['net', $m->expr('[net]*[vat]', 'ref_no')]);
+        $m->setOrder($m->expr('[net] * [vat]'));
+        $m->setOrder([$m->expr('[net] * [vat]'), $m->expr('[closing] - [opening]')]);
+        $m->setOrder(['net', $m->expr('[net] * [vat]', 'ref_no')]);

docs/overview.rst

@@ -160,7 +160,7 @@ This is a type of code which may change if you decide to switch from one
 persistence to another. For example, this is how you would define `gross` field
 for SQL::
 
-    $model->addExpression('gross', '[net]+[vat]');
+    $model->addExpression('gross', ['expr' => '[net] + [vat]']);
 
 If your persistence does not support expressions (e.g. you are using Redis or
 MongoDB), you would need to define the field differently::
@@ -180,7 +180,7 @@ you want it to work with NoSQL, then your solution might be::
     if ($model->hasMethod('addExpression')) {
 
         // method is injected by Persistence
-        $model->addExpression('gross', '[net]+[vat]');
+        $model->addExpression('gross', ['expr' => '[net] + [vat]']);
 
     } else {
 

docs/persistence.rst

@@ -830,13 +830,13 @@ This operation is actually consisting of 3 following operations::
 Here is a way how to intervene with the process::
 
     $client->hasMany('Invoice');
-    $client->addExpression('last_sale', function($m) {
+    $client->addExpression('last_sale', ['expr' => function ($m) {
         return $m->refLink('Invoice')
             ->setOrder('date desc')
             ->setLimit(1)
             ->action('field', ['total_gross'], 'getOne');
 
-    });
+    }, 'type' => 'float']);
 
 The code above uses refLink and also creates expression, but it tweaks
 the action used.

docs/persistence/sql/expressions.rst

@@ -306,9 +306,9 @@ parts of the query. You must not call them in normal circumstances.
   a nasty back-ticks or commas in the field names. I generally **discourage**
   you from using this method. Example use would be::
 
-      $query->field('foo,bar');  // escapes and adds 2 fields to the query
-      $query->field($query->escape('foo,bar')); // adds field `foo,bar` to the query
-      $query->field(['foo,bar']);  // adds single field `foo,bar`
+      $query->field('foo, bar');  // escapes and adds 2 fields to the query
+      $query->field($query->escape('foo, bar')); // adds field `foo, bar` to the query
+      $query->field(['foo, bar']);  // adds single field `foo, bar`
 
       $query->order('foo desc');  // escapes and add `foo` desc to the query
       $query->field($query->escape('foo desc')); // adds field `foo desc` to the query
@@ -332,7 +332,7 @@ parts of the query. You must not call them in normal circumstances.
 
       $query->escapeIdentifierSoft('first_name');  // `first_name`
       $query->escapeIdentifierSoft('first.name');  // `first`.`name`
-      $query->escapeIdentifierSoft('(2+2)');       // (2+2)
+      $query->escapeIdentifierSoft('(2 + 2)');     // (2 + 2)
       $query->escapeIdentifierSoft('*');           // *
 
 .. php:method:: escapeParam($value)

docs/persistence/sql/queries.rst

@@ -104,11 +104,11 @@ The example above will perform a select query first:
 
 If a single row can be retrieved, then the update will be performed:
 
- - `update user set name="John", surname="Smith", revision=revision+1 where id=123`
+ - `update user set name="John", surname="Smith", revision=revision + 1 where id=123`
 
 Otherwise an insert operation will be performed:
 
- - `insert into user (name,surname,revision) values ("John", "Smith", 1)`
+ - `insert into user (name, surname, revision) values ("John", "Smith", 1)`
 
 Chaining
 ========
@@ -151,7 +151,7 @@ This query will perform `select name from (select * from employee)`::
     $u = $c->dsql("[] union []", [$q1, $q2]);
 
     $q = $c->dsql()
-        ->field('date,debit,credit')
+        ->field('date, debit, credit')
         ->table($u, 'derrivedTable');
 
     $q->getRows();
@@ -255,8 +255,8 @@ Basic Examples::
     $query->field('first_name');
         // SELECT `first_name` from `user`
 
-    $query->field('first_name,last_name');
-        // SELECT `first_name`,`last_name` from `user`
+    $query->field('first_name, last_name');
+        // SELECT `first_name`, `last_name` from `user`
 
     $query->field('employee.first_name')
         // SELECT `employee`.`first_name` from `user`
@@ -338,9 +338,9 @@ Starting with the basic examples::
     $q->where('id', null);   // same as above
 
     $q->where('now()', 1);   // will not use backticks
-    $q->where($c->expr('now()'),1);  // same as above
+    $q->where($c->expr('now()'), 1); // same as above
 
-    $q->where('id', [1,2]);  // renders as id in (1,2)
+    $q->where('id', [1, 2]);  // renders as id in (1, 2)
 
 You may call where() multiple times, and conditions are always additive (uses AND).
 The easiest way to supply OR condition is to specify multiple conditions
@@ -435,7 +435,7 @@ Few examples::
 
     $q->group('gender');
 
-    $q->group('gender,age');
+    $q->group('gender, age');
 
     $q->group(['gender', 'age']);
 

docs/persistence/sql/transactions.rst

@@ -20,8 +20,8 @@ It is recommended to always use atomic() in your code.
     exception, whole transaction will be automatically rolled back::
 
         $c->atomic(function () use ($c) {
-            $c->dsql('user')->set('balance=balance+10')->where('id', 10)->mode('update')->execute();
-            $c->dsql('user')->set('balance=balance-10')->where('id', 14)->mode('update')->execute();
+            $c->dsql('user')->set('balance=balance + 10')->where('id', 10)->mode('update')->execute();
+            $c->dsql('user')->set('balance=balance - 10')->where('id', 14)->mode('update')->execute();
         });
 
     atomic() can be nested.