Improved validation for collection key options

.github/workflows/php.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-versions: ["8.2", "8.3", "8.4"]
+        php-versions: ["8.3", "8.4"]
 
     steps:
       - name: Setup PHP

composer.json

@@ -19,7 +19,7 @@
     }
   ],
   "require": {
-    "php": ">=8.2",
+    "php": ">=8.3",
     "ext-json": "*",
     "guzzlehttp/guzzle": "^7.10",
     "symfony/service-contracts": "^3.6",

src/Collection/Collection.php

@@ -136,8 +136,7 @@
         'type' => 2,
         'keyOptions' => [
             'allowUserKeys' => true,
-            'type' => 'traditional',
-            'lastValue' => 0
+            'type' => KeyType::TRADITIONAL,
         ],
     ];
 
@@ -214,7 +213,7 @@
      * @return CursorInterface|bool Cursor if collection exists on database. False otherwise.
      * @throws GuzzleException|InvalidParameterException|CursorException
      */
-    public function all()
+    public function all(): bool|CollectionCursor
     {
         if (!$this->isNew()) {
             return new CollectionCursor($this);
@@ -272,7 +271,7 @@
      *
      * @return string|null String if collection exists on database. Null if not.
      */
-    public function getId()
+    public function getId(): ?string
     {
         return ($this->attributes['objectId'] === null) ? $this->attributes['id'] : $this->attributes['objectId'];
     }

src/Collection/KeyType.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace ArangoDB\Collection;
+
+/**
+ * Groups the available key generations for new collections
+ *
+ * @package ArangoDB\Collection
+ * @author Lucas S. Vieira
+ */
+class KeyType
+{
+    public const string TRADITIONAL = 'traditional';
+    public const string AUTOINCREMENT = 'autoincrement';
+    public const string PADDED = 'padded';
+    public const string UUID = 'uuid';
+}

src/Cursor/CollectionCursor.php

@@ -25,7 +25,7 @@ class CollectionCursor extends Cursor
      *
      * @var Collection
      */
-    protected $collection;
+    protected Collection $collection;
 
     /**
      * CollectionCursor constructor.

src/DataStructures/ArrayList.php

@@ -71,7 +71,7 @@ public function last()
     /**
      * Get a value by its key
      *
-     * @param int|string $key Key to verify on list.
+     * @param int|string $key KeyType to verify on list.
      * @return mixed
      */
     public function get($key)
@@ -96,7 +96,7 @@ public function push($value): void
     /**
      * Put a object into list on given key
      *
-     * @param string|integer $key Key for manage the value.
+     * @param string|integer $key KeyType for manage the value.
      * @param mixed $value Value to add.
      */
     public function put($key, $value): void

src/DataStructures/Contracts/ListInterface.php

@@ -44,7 +44,7 @@ public function push($value): void;
     /**
      * Put a object into list on given key
      *
-     * @param string|integer $key Key for manage the value.
+     * @param string|integer $key KeyType for manage the value.
      * @param mixed $value Value to add.
      */
     public function put($key, $value): void;

src/Validation/Admin/Task/TaskValidator.php

@@ -59,7 +59,7 @@ public function rules(): array
      *
      * @return \Closure
      */
-    private function validateParamsCallback()
+    private function validateParamsCallback(): \Closure
     {
         return function (array $params) {
             $validator = Rules::isPrimitive();

src/Validation/Collection/CollectionValidator.php

@@ -4,8 +4,10 @@
 
 namespace ArangoDB\Validation\Collection;
 
+use ArangoDB\Collection\KeyType;
 use ArangoDB\Validation\Validator;
 use ArangoDB\Validation\Rules\Rules;
+use ArangoDB\Validation\Exceptions\InvalidKeyOptionException;
 
 /**
  * Validate the collection options values. <br>
@@ -48,7 +50,33 @@ public function rules(): array
             'numberOfShards' => Rules::equalsOrGreaterThan(1),
             'isSystem' => Rules::boolean(),
             'type' => Rules::in([2, 3]),
-            'keyOptions' => Rules::arr(),
+            'keyOptions' => Rules::callbackValidation(self::validateKeyOptions()),
         ];
     }
+
+    /**
+     * Validate key options for collection creation
+     *
+     * @return \Closure
+     */
+    private static function validateKeyOptions(): \Closure
+    {
+        /**
+         * 'offset' and 'increment' options are only allowed when used with type 'autoincrement'
+         *
+         * @return bool
+         * @throws InvalidKeyOptionException
+         */
+        return function (array $keyOptions) {
+            if (array_key_exists('offset', $keyOptions) && $keyOptions['type'] != KeyType::AUTOINCREMENT) {
+                throw new InvalidKeyOptionException("offset", $keyOptions['type']);
+            }
+
+            if (array_key_exists('increment', $keyOptions) && $keyOptions['type'] != KeyType::AUTOINCREMENT) {
+                throw new InvalidKeyOptionException("increment", $keyOptions['type']);
+            }
+
+            return true;
+        };
+    }
 }

src/Validation/Exceptions/InvalidKeyOptionException.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArangoDB\Validation\Exceptions;
+
+use Throwable;
+use ArangoDB\Exceptions\BaseException;
+
+/**
+ * Invalid collection key option exception.
+ *
+ * @package ArangoDB\Validation\Exceptions
+ * @author Lucas S. Vieira
+ */
+class InvalidKeyOptionException extends BaseException
+{
+    /**
+     * Parameter name.
+     *
+     * @var string
+     */
+    protected string $parameter;
+
+    /**
+     * Parameter value.
+     *
+     * @var string
+     */
+    protected string $type;
+
+    /**
+     * InvalidKeyOptionException constructor.
+     *
+     * @param string $parameter Parameter name.
+     * @param string $value Parameter value.
+     * @param Throwable|null $previous Previous exception or error.
+     */
+    public function __construct(string $parameter, $value, Throwable $previous = null)
+    {
+        $message = "Parameter '$parameter' can not be used for collection with key type of '$value'.";
+        parent::__construct($message, $previous);
+    }
+}

src/Validation/Exceptions/InvalidParameterException.php

@@ -18,16 +18,16 @@
     /**
      * Parameter name.
      *
-     * @var string
+     * @var string|int
      */
-    protected $parameter;
+    protected string|int $parameter;
 
     /**
      * Parameter value.
      *
      * @var mixed
      */
-    protected $value;
+    protected mixed $value;
 
     /**
      * InvalidParameterException constructor.

src/Validation/Graph/GraphValidator.php

@@ -63,7 +63,7 @@ public function rules(): array
      *
      * @return \Closure
      */
-    private static function validateEdgeDefinitionsParameter()
+    private static function validateEdgeDefinitionsParameter(): \Closure
     {
         /**
          * @param $edgeDefinitions array|ArrayList

src/Validation/Rules/Rules.php

@@ -17,7 +17,7 @@ abstract class Rules
      *
      * @return RuleInterface
      */
-    public static function arr()
+    public static function arr(): RuleInterface
     {
         return new class () implements RuleInterface {
             /**
@@ -39,7 +39,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function string()
+    public static function string(): RuleInterface
     {
         return new class () implements RuleInterface {
             /**
@@ -61,7 +61,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function numeric()
+    public static function numeric(): RuleInterface
     {
         return new class () implements RuleInterface {
             /**
@@ -83,7 +83,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function integer()
+    public static function integer(): RuleInterface
     {
         return new class () implements RuleInterface {
             /**
@@ -105,7 +105,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function boolean()
+    public static function boolean(): RuleInterface
     {
         return new class () implements RuleInterface {
             /**
@@ -128,7 +128,7 @@ public function isValid($value): bool
      * @return RuleInterface
      * @see https://www.php.net/manual/en/language.types.intro.php
      */
-    public static function isPrimitive()
+    public static function isPrimitive(): RuleInterface
     {
         return new class () implements RuleInterface {
             /**
@@ -156,7 +156,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function equalsOrGreaterThan(int $reference)
+    public static function equalsOrGreaterThan(int $reference): RuleInterface
     {
         return new class ($reference) implements RuleInterface {
             /**
@@ -199,7 +199,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function uri()
+    public static function uri(): RuleInterface
     {
         return new class () implements RuleInterface {
             /**
@@ -224,7 +224,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function in(array $values)
+    public static function in(array $values): RuleInterface
     {
         return new class ($values) implements RuleInterface {
             /**
@@ -263,7 +263,7 @@ public function isValid($value): bool
      *
      * @return RuleInterface
      */
-    public static function callbackValidation(callable $callback)
+    public static function callbackValidation(callable $callback): RuleInterface
     {
         return new class ($callback) implements RuleInterface {
             /**

src/Validation/Transaction/TransactionOptionsValidator.php

@@ -55,10 +55,10 @@ public function rules(): array
      *
      * @return \Closure
      */
-    private static function validateCollectionsParameter()
+    private static function validateCollectionsParameter(): \Closure
     {
         return function (array $collections) {
-            // Must contains one or more of following attributes:
+            // Must contain one or more of following attributes:
             // 'write', 'read' or 'exclusive'
             if (!isset($collections['write']) && !isset($collections['read']) && !isset($collections['exclusive'])) {
                 // None of required keys on 'collections'.

tests/Collection/CollectionTest.php

@@ -3,6 +3,7 @@
 namespace Unit\Collection;
 
 use ArangoDB\Admin\Server;
+use ArangoDB\Collection\KeyType;
 use Unit\TestCase;
 use GuzzleHttp\Psr7\Response;
 use ArangoDB\Document\Vertex;
@@ -385,7 +386,7 @@ public function testDropIndexThrowDatabaseException()
 
         $list = $collection->getIndexes();
 
-        // Try to drop an non-existent index
+        // Try to drop a non-existent index
         $this->expectException(DatabaseException::class);
         $collection->dropIndex($list->last());
     }
@@ -520,6 +521,24 @@ public function testSave()
         $this->assertTrue($collection->drop());
     }
 
+    public function testSaveWithNonDefaultOptions()
+    {
+        $keyOptions = [
+            'allowUserKeys' => false,
+            'type' => KeyType::UUID,
+        ];
+
+        $db = new Database($this->getConnectionObject());
+        $collection = new Collection('test_save_coll', $db, ['keyOptions' => $keyOptions]);
+
+        // Check if collection is created.
+        $this->assertNull($collection->getId());
+
+        $this->assertTrue($collection->save());
+        $this->assertIsString($collection->getId());
+        $this->assertTrue($collection->drop());
+    }
+
     public function testSaveThrowDatabaseException()
     {
         // Mock error