conventions: add missing methods to interface (BC break!)

doc/conventions.texy

@@ -46,7 +46,7 @@ You are free to add your own mapping. Just call `setMapping($entityName, $storag
 
 /--code php
 use Nextras\Orm\Mapper\Mapper;
-use Nextras\Orm\Mapper\Conventions\IConventions;
+use Nextras\Orm\Mapper\Dbal\Conventions\IConventions;
 
 class EventsMapper extends Mapper
 {
@@ -76,7 +76,7 @@ class File extends Nextras\Orm\Entity\Entity
 
 class FilesMapper extends Nextras\Orm\Mapper\Dbal\DbalMapper
 {
-    protected function createConventions(): Nextras\Orm\Mapper\Conventions\IConventions
+    protected function createConventions(): Nextras\Orm\Mapper\Dbal\Conventions\IConventions
     {
         $conventions = parent::createConventions();
         $conventions->setMapping('isPublic', 'is_public', function ($val) {
@@ -93,7 +93,7 @@ class FilesMapper extends Nextras\Orm\Mapper\Dbal\DbalMapper
 Properties' modifiers for Nextras Dbal
 --------------------------------------
 
-The underlying layer Nextras Dbal takes care about converting and sanitizing the values for SQL INSERT/UPDATE query. By default, the `%any` modifier is used and the value is transformed by its type. However, you may want to force different behaviour and modifier for Nextras Dbal layer. To do that, use `addModifier($storageKey, $modifier)` method, which accepts the table's column name and Dbal's modifier. Let's see an example:
+The underlying layer Nextras Dbal takes care about converting and sanitizing the values for SQL INSERT/UPDATE query. By default, the `%any` modifier is used and the value is transformed by its type. However, you may want to force different behaviour and modifier for Nextras Dbal layer. To do that, use `setModifier($storageKey, $modifier)` method, which accepts the table's column name and Dbal's modifier. Let's see an example:
 
 /--code php
 /**
@@ -105,10 +105,10 @@ class File extends Nextras\Orm\Entity\Entity
 
 class FilesMapper extends Nextras\Orm\Mapper\Dbal\DbalMapper
 {
-    protected function createConventions(): Nextras\Orm\Mapper\Conventions\IConventions
+    protected function createConventions(): Nextras\Orm\Mapper\Dbal\Conventions\IConventions
     {
         $conventions = parent::createConventions();
-        $conventions->addModifier('contents', '%blob');
+        $conventions->setModifier('contents', '%blob');
         return $conventions;
     }
 }
@@ -122,13 +122,15 @@ There are many possibilities to change default table joining conventions. If you
 
 /--code php
 use Nextras\Orm\Mapper\Mapper;
-use Nextras\Orm\Mapper\Conventions\IConventions;
+use Nextras\Orm\Mapper\Dbal\Conventions\Conventions;
+use Nextras\Orm\Mapper\Dbal\Conventions\IConventions;
 
 class BaseMapper extends Mapper
 {
 	protected function createConventions(): IConventions
 	{
 		$conventions = parent::createConventions();
+		assert($conventions instanceof Conventions); // property is not available on interface
 		$conventions->manyHasManyStorageNamePattern = '%s_2_%s';
 		return $conventions;
 	}

src/Mapper/Dbal/Conventions/Conventions.php

@@ -61,8 +61,8 @@ class Conventions implements IConventions
 	/**
 	 * @var array
 	 * @phpstan-var array{
-	 *      array<string, array{string, 1?: callable|null}>,
-	 *      array<string, array{string, 1?: callable|null}>,
+	 *      array<string, array{string, 1?: (callable(mixed $value, string $newKey): mixed)|null}>,
+	 *      array<string, array{string, 1?: (callable(mixed $value, string $newKey): mixed)|null}>,
 	 *      array<string, array<string>>,
 	 * }
 	 */
@@ -277,16 +277,12 @@ public function getManyHasManyStoragePrimaryKeys(IConventions $targetConventions
 	}
 
 
-	/**
-	 * Adds mapping.
-	 * @throws InvalidStateException Throws exception if mapping was already defined.
-	 */
 	public function addMapping(
 		string $entity,
 		string $storage,
-		callable $toEntityCb = null,
-		callable $toStorageCb = null
-	): Conventions
+		?callable $toEntityCb = null,
+		?callable $toStorageCb = null
+	): IConventions
 	{
 		if (isset($this->mappings[self::TO_ENTITY][$storage])) {
 			throw new InvalidStateException("Mapping for $storage column is already defined.");
@@ -300,25 +296,19 @@ public function addMapping(
 	}
 
 
-	/**
-	 * Sets mapping.
-	 */
 	public function setMapping(
 		string $entity,
 		string $storage,
-		callable $toEntityCb = null,
-		callable $toStorageCb = null
-	): Conventions
+		?callable $toEntityCb = null,
+		?callable $toStorageCb = null
+	): IConventions
 	{
 		unset($this->mappings[self::TO_ENTITY][$storage], $this->mappings[self::TO_STORAGE][$entity]);
 		return $this->addMapping($entity, $storage, $toEntityCb, $toStorageCb);
 	}
 
 
-	/**
-	 * Adds parameter modifier for data-trasform to Nextras Dbal layer.
-	 */
-	public function addModifier(string $storageKey, string $saveModifier): Conventions
+	public function setModifier(string $storageKey, string $saveModifier): IConventions
 	{
 		$this->modifiers[$storageKey] = $saveModifier;
 		return $this;

src/Mapper/Dbal/Conventions/IConventions.php

@@ -4,6 +4,7 @@
 
 
 use Nextras\Dbal\Platforms\Data\Table;
+use Nextras\Orm\InvalidStateException;
 
 
 interface IConventions
@@ -67,4 +68,38 @@ public function getManyHasManyStorageName(IConventions $targetConventions): stri
 	 * @phpstan-return array{string, string}
 	 */
 	public function getManyHasManyStoragePrimaryKeys(IConventions $targetConventions): array;
+
+
+	/**
+	 * @param (callable(mixed $value, string $newKey): mixed)|null $toEntityCb
+	 * @param (callable(mixed $value, string $newKey): mixed)|null $toStorageCb
+	 * @return static
+	 * @throws InvalidStateException Throws exception if mapping was already defined.
+	 */
+	public function addMapping(
+		string $entity,
+		string $storage,
+		?callable $toEntityCb = null,
+		?callable $toStorageCb = null
+	): IConventions;
+
+
+	/**
+	 * @param (callable(mixed $value, string $newKey): mixed)|null $toEntityCb
+	 * @param (callable(mixed $value, string $newKey): mixed)|null $toStorageCb
+	 * @return static
+	 */
+	public function setMapping(
+		string $entity,
+		string $storage,
+		?callable $toEntityCb = null,
+		?callable $toStorageCb = null
+	): IConventions;
+
+
+	/**
+	 * Sets column modifier for data transformation to Nextras Dbal layer.
+	 * @return static
+	 */
+	public function setModifier(string $storageKey, string $saveModifier): IConventions;
 }

tests/inc/model/book/BooksMapper.php

@@ -5,7 +5,6 @@
 
 use Nextras\Orm\Collection\ICollection;
 use Nextras\Orm\Entity\IEntity;
-use Nextras\Orm\Mapper\Dbal\Conventions\Conventions;
 use Nextras\Orm\Mapper\Dbal\Conventions\IConventions;
 use Nextras\Orm\Mapper\Mapper;
 
@@ -29,7 +28,6 @@ public function findFirstBook(): ?IEntity
 	protected function createConventions(): IConventions
 	{
 		$reflection = parent::createConventions();
-		assert($reflection instanceof Conventions);
 		$reflection->setMapping('price->cents', 'price');
 		return $reflection;
 	}

tests/inc/model/tag/TagsMapper.php

@@ -3,7 +3,6 @@
 namespace NextrasTests\Orm;
 
 
-use Nextras\Orm\Mapper\Dbal\Conventions\Conventions;
 use Nextras\Orm\Mapper\Dbal\Conventions\IConventions;
 use Nextras\Orm\Mapper\Mapper;
 
@@ -12,13 +11,17 @@ final class TagsMapper extends Mapper
 {
 	protected function createConventions(): IConventions
 	{
-		$reflection = parent::createConventions();
-		assert($reflection instanceof Conventions);
-		$reflection->addMapping('isGlobal', 'is_global', function ($val): bool {
-			return $val === 'y';
-		}, function ($val) {
-			return $val ? 'y' : 'n';
-		});
-		return $reflection;
+		$conventions = parent::createConventions();
+		$conventions->addMapping(
+			'isGlobal',
+			'is_global',
+			function ($val): bool {
+				return $val === 'y';
+			},
+			function ($val) {
+				return $val === true ? 'y' : 'n';
+			}
+		);
+		return $conventions;
 	}
 }