Rename Field negated mandatory to nullable (#1041)

Author: mvorisek

docs/fields.rst

@@ -135,9 +135,9 @@ Similar with $enum, but difference is that this array is a hash array so
 array keys will be used as values and array values will be used as titles
 for these values.
 
-.. php:attr:: mandatory
+.. php:attr:: nullable
 
-Set this to true if field value must not be NULL. Attempting to set field
+Set this to false if field value must NOT be NULL. Attempting to set field
 value to "NULL" will result in exception.
 Example::
 
@@ -211,11 +211,11 @@ Set the value of the field. Same as $model->set($fieldName, $value);
 
 .. php:method:: setNull
 
-Set field value to NULL. This will bypass "mandatory" and "required" checks and
+Set field value to NULL. This will bypass "nullable" and "required" checks and
 should only be used if you are planning to set a different value to the field
 before executing save().
 
-If you do not set non-null value to a mandatory field, save() will fail with
+If you do not set non-null value to a not-nullable field, save() will fail with
 exception.
 
 Example::

docs/joins.rst

@@ -57,7 +57,7 @@ Strong and Weak joins
 ---------------------
 
 When you are joining tables, then by default a strong join is used. That means
-that both records are mandatory and when adding records, they will both be added
+that both records are not-nullable and when adding records, they will both be added
 and linked.
 
 Weak join is used if you do not really want to modify the other table.

src/Field.php

@@ -202,7 +202,7 @@ public function normalize($value)
             $value = $this->normalizeUsingTypecast($value);
 
             if ($value === null) {
-                if ($this->required || $this->mandatory) {
+                if (!$this->nullable || $this->required) {
                     throw new Exception('Must not be null');
                 }
 

src/Model/FieldPropertiesTrait.php

@@ -15,8 +15,8 @@ trait FieldPropertiesTrait
 
     /** @var string|null DBAL type registered in \Doctrine\DBAL\Types\Type. */
     public ?string $type = null;
-    /** @var bool Mandatory field must not be null. The value must be set, even if it's an empty value. */
-    public bool $mandatory = false;
+    /** @var bool Nullable field can be null, otherwise the value must be set, even if it is an empty value. */
+    public bool $nullable = true;
     /** @var bool Required field must have non-empty value. A null value is considered empty too. */
     public bool $required = false;
 
@@ -63,8 +63,6 @@ trait FieldPropertiesTrait
      *
      * By default hasOne relation ID field should be editable in forms,
      * but not visible in grids. UI should respect these flags.
-     *
-     * @var array
      */
-    public $ui = [];
+    public array $ui = [];
 }

src/Persistence/Sql/Query.php

@@ -157,9 +157,8 @@ public function table($table, $alias = null)
             throw new \TypeError('Array input is no longer accepted');
         }
 
-        // if table is set as sub-Query, then alias is mandatory
         if ($table instanceof self && $alias === null) {
-            throw new Exception('If table is set as Query, then table alias is mandatory');
+            throw new Exception('If table is set as subquery, then table alias is required');
         }
 
         if (is_string($table) && $alias === null) {

src/Reference/ContainsBase.php

@@ -14,7 +14,7 @@ abstract class ContainsBase extends Reference
     use ContainsSeedHackTrait;
 
     /** @var string Field type. */
-    public $type = 'json';
+    public string $type = 'json';
 
     /** @var bool Is it system field? */
     public $system = true;
@@ -24,10 +24,8 @@ abstract class ContainsBase extends Reference
      *
      * By default hasOne relation ID field should be editable in forms,
      * but not visible in grids. UI should respect these flags.
-     *
-     * @var array
      */
-    public $ui = [];
+    public array $ui = [];
 
     /** @var string Required! We need table alias for internal use only. */
     protected $tableAlias = 'tbl';

src/Schema/Migrator.php

@@ -235,7 +235,7 @@ public function field(string $fieldName, array $options = []): self
 
         $column = $this->table->addColumn($this->getDatabasePlatform()->quoteSingleIdentifier($fieldName), $options['type']);
 
-        if (!($options['mandatory'] ?? false) && $refType !== self::REF_TYPE_PRIMARY) {
+        if (($options['nullable'] ?? true) && $refType !== self::REF_TYPE_PRIMARY) {
             $column->setNotnull(false);
         }
 
@@ -267,7 +267,7 @@ public function id(string $name = 'id'): self
         $options = [
             'type' => 'integer',
             'ref_type' => self::REF_TYPE_PRIMARY,
-            'mandatory' => true,
+            'nullable' => false,
         ];
 
         $this->field($name, $options);
@@ -299,9 +299,9 @@ public function setModel(Model $model): Model
             }
 
             $options = [
-                'type' => $refype !== self::REF_TYPE_NONE && empty($persistField->type) ? 'integer' : $persistField->type,
+                'type' => $refype !== self::REF_TYPE_NONE && $persistField->type === null ? 'integer' : $persistField->type,
                 'ref_type' => $refype,
-                'mandatory' => ($field->mandatory || $field->required) && ($persistField->mandatory || $persistField->required),
+                'nullable' => ($field->nullable && !$field->required) || ($persistField->nullable && !$persistField->required),
             ];
 
             $this->field($field->getPersistenceName(), $options);

tests/FieldTest.php

@@ -67,10 +67,10 @@ public function testCompare(): void
         $this->assertTrue($m->compare('foo', 'zzz'));
     }
 
-    public function testMandatory1(): void
+    public function testNotNullable1(): void
     {
         $m = new Model();
-        $m->addField('foo', ['mandatory' => true]);
+        $m->addField('foo', ['nullable' => false]);
         $m = $m->createEntity();
         $m->set('foo', 'abc');
         $m->set('foo', '');
@@ -99,7 +99,7 @@ public function testRequired11(): void
         $m->set('foo', null);
     }
 
-    public function testMandatory2(): void
+    public function testNotNullable2(): void
     {
         $this->setDb([
             'user' => [
@@ -108,7 +108,7 @@ public function testMandatory2(): void
         ]);
 
         $m = new Model($this->db, ['table' => 'user']);
-        $m->addField('name', ['mandatory' => true]);
+        $m->addField('name', ['nullable' => false]);
         $m->addField('surname');
         $this->expectException(Exception::class);
         $m->insert(['surname' => 'qq']);
@@ -129,7 +129,7 @@ public function testRequired2(): void
         $m->insert(['surname' => 'qq', 'name' => '']);
     }
 
-    public function testMandatory3(): void
+    public function testNotNullable3(): void
     {
         $this->setDb([
             'user' => [
@@ -138,14 +138,14 @@ public function testMandatory3(): void
         ]);
 
         $m = new Model($this->db, ['table' => 'user']);
-        $m->addField('name', ['mandatory' => true]);
+        $m->addField('name', ['nullable' => false]);
         $m->addField('surname');
         $m = $m->load(1);
         $this->expectException(Exception::class);
         $m->save(['name' => null]);
     }
 
-    public function testMandatory4(): void
+    public function testNotNullable4(): void
     {
         $this->setDb([
             'user' => [
@@ -154,7 +154,7 @@ public function testMandatory4(): void
         ]);
 
         $m = new Model($this->db, ['table' => 'user']);
-        $m->addField('name', ['mandatory' => true, 'default' => 'NoName']);
+        $m->addField('name', ['nullable' => false, 'default' => 'NoName']);
         $m->addField('surname');
         $m->insert(['surname' => 'qq']);
         $this->assertEquals([
@@ -779,7 +779,7 @@ public function testSetNull(): void
     {
         $m = new Model();
         $m->addField('a');
-        $m->addField('b', ['mandatory' => true]);
+        $m->addField('b', ['nullable' => false]);
         $m->addField('c', ['required' => true]);
         $m = $m->createEntity();
 
@@ -814,7 +814,7 @@ public function testEntityFieldPair(): void
     {
         $m = new Model();
         $m->addField('foo');
-        $m->addField('bar', ['mandatory' => true]);
+        $m->addField('bar', ['nullable' => false]);
 
         $entity = $m->createEntity();
         $entityFooField = new Model\EntityFieldPair($entity, 'foo');

tests/Persistence/Sql/QueryTest.php

@@ -147,73 +147,53 @@ public function testFieldDuplicateAliasException(): void
     }
 
     /**
-     * Alias is NOT mandatory when pass table as Expression.
-     *
      * @doesNotPerformAssertions
      */
-    public function testTableException3(): void
+    public function testTableNoAliasExpressionException(): void
     {
         // $this->expectException(Exception::class); // no more
         $this->q()->table($this->q()->expr('test'));
     }
 
-    /**
-     * Alias is IS mandatory when pass table as Query.
-     */
-    public function testTableException4(): void
+    public function testTableNoAliasQueryException(): void
     {
         $this->expectException(Exception::class);
         $this->q()->table($this->q()->table('test'));
     }
 
-    /**
-     * Table aliases should be unique.
-     */
-    public function testTableException5(): void
+    public function testTableAliasNotUniqueException(): void
     {
         $this->expectException(Exception::class);
         $this->q()
             ->table('foo', 'a')
             ->table('bar', 'a');
     }
 
-    /**
-     * Table aliases should be unique.
-     */
-    public function testTableException6(): void
+    public function testTableAliasNotUniqueException2(): void
     {
         $this->expectException(Exception::class);
         $this->q()
             ->table('foo', 'bar')
             ->table('bar');
     }
 
-    /**
-     * Table aliases should be unique.
-     */
-    public function testTableException7(): void
+    public function testTableAliasNotUniqueException3(): void
     {
         $this->expectException(Exception::class);
         $this->q()
             ->table('foo')
             ->table('foo');
     }
 
-    /**
-     * Table aliases should be unique.
-     */
-    public function testTableException8(): void
+    public function testTableAliasNotUniqueException4(): void
     {
         $this->expectException(Exception::class);
         $this->q()
             ->table($this->q()->table('test'), 'foo')
             ->table('foo');
     }
 
-    /**
-     * Table aliases should be unique.
-     */
-    public function testTableException9(): void
+    public function testTableAliasNotUniqueException5(): void
     {
         $this->expectException(Exception::class);
         $this->q()

tests/Persistence/StaticTest.php

@@ -75,8 +75,8 @@ protected function init(): void
             {
                 parent::init();
 
+                $this->getField('id')->nullable = false;
                 $this->getField('id')->required = false;
-                $this->getField('id')->mandatory = true;
             }
         };
 

tests/Util/DeepCopyTest.php

@@ -88,7 +88,7 @@ protected function init(): void
         $this->addField('type', ['enum' => ['invoice', 'quote']]);
         $this->addCondition('type', '=', 'invoice');
 
-        $this->addField('qty', ['type' => 'integer', 'mandatory' => true]);
+        $this->addField('qty', ['type' => 'integer', 'nullable' => false]);
         $this->addField('price', ['type' => 'atk4_money']);
         $this->addField('vat', ['type' => 'float', 'default' => 0.21]);