feat!: expanded key generator selection

Author: Deploy

composer.json

@@ -24,8 +24,8 @@
     "require": {
         "php": "^8.2",
         "ext-json": "*",
-        "composer/composer": "^2.7.0",
-        "laravel-freelancer-nl/arangodb-php-client": "^2.7.0",
+        "composer/composer": "^2.8.0",
+        "laravel-freelancer-nl/arangodb-php-client": "^2.8.0",
         "laravel-freelancer-nl/fluentaql": "^2.0",
         "laravel/framework": "^11.0",
         "spatie/laravel-data": "^4.4.0",

config/arangodb.php

@@ -5,9 +5,22 @@
 return [
     'datetime_format' => 'Y-m-d\TH:i:s.vp',
     'schema' => [
+        /*
+         * @see https://docs.arangodb.com/stable/develop/http-api/collections/#create-a-collection_body_keyOptions_allowUserKeys
+         */
         'keyOptions' => [
             'allowUserKeys' => true,
             'type' => 'traditional',
         ],
+        'key_handling' => [
+            'prioritize_configured_key_type' => false,
+            'use_traditional_over_autoincrement' => true,
+        ],
+        // Key type prioritization takes place in the following order:
+        // 1: table config within the migration file (this always takes priority)
+        // 2: The id column methods such as id() and ...Increments() methods in the migration file
+        // 3: The configured key type above.
+        // The order of 2 and 3 can be swapped; in which case the configured key takes priority over column methods.
+        // These settings are merged, individual keyOptions can be overridden in this way.
     ],
 ];

docs/key-options.md

@@ -0,0 +1,55 @@
+# Key generator options
+Tables in ArangoDB can be created using one of the available key generators. You can read up about them
+[here](https://docs.arangodb.com/stable/concepts/data-structure/documents/#document-keys) 
+and [here](https://docs.arangodb.com/stable/develop/http-api/collections/#create-a-collection_body_keyOptions).
+
+The following assumes you have knowledge about ArangoDB keys as can be obtained through the above links.
+
+## Column defined key generators
+Laravel has several column methods which can be used to set a primary key. If the given field is equal to:
+'id', '_key' or '_id', the key generator will be set according to the mapping below.
+
+If these column methods are not found, or not called on these fields, the configured default generator is used.
+You can also ignore the column methods by setting the config value 
+'arangodb.schema.key_handling.prioritize_configured_key_type' to true.
+
+By default, we map the key methods to the following ArangoDB key generators:
+
+| Laravel column method | ArangoDB key generator |
+|:----------------------|:-----------------------|
+| autoIncrement()       | traditional            |
+| id()				     | traditional            |
+| increments('id')	     | traditional            |
+| smallIncrements	     | traditional            |
+| bigIncrements		 | traditional            |
+| mediumIncrements	     | traditional            |
+| uuid(id)              | uuid                   |
+| ulid(id)              | _n/a_                  |
+
+## Traditional vs autoincrement key generators
+Even though ArangoDB has an autoincrement key generator we don't use it by default as it is not cluster safe.
+The traditional key generator is similar to autoincrement: it is cluster safe although there may be gaps between
+the _key increases.
+
+If you want the column methods to set the generator to autoincrement you can override the default behaviour by setting
+the config value 'arangodb.schema.key_handling.use_traditional_over_autoincrement' to false.
+In which case any given offset in the 'from' method is also used.
+
+## ulid
+There is no ulid key generator in ArangoDB. The 'padded' generator may be used if you want
+a lexigraphical sort order. You can do so by setting it in the config as the default key, and using configured keys only.
+Or by setting it within the migration in the table options.
+
+## Table option key generators
+You can set the key options for the table in the migration. This overrides both the default key options and the one defined by column methods.
+
+```
+        Schema::create('taggables', function (Blueprint $collection) {
+            //
+        }, [
+            'keyOptions' => [
+                'type' => 'padded',
+            ],
+        ]);
+ ```
+

src/Connection.php

@@ -27,7 +27,10 @@ class Connection extends IlluminateConnection
     use ManagesTransactions;
     use RunsQueries;
 
-    protected ?ArangoClient $arangoClient = null;
+    /**
+     * @var ArangoClient|null
+     */
+    protected $arangoClient;
 
     /**
      * The ArangoDB driver name.

src/Schema/Blueprint.php

@@ -276,36 +276,22 @@ public function __call($method, $args = [])
             'unsignedTinyInteger', 'uuid', 'year',
         ];
 
-        $keyMethods = ['bigIncrements', 'increments', 'mediumIncrements', ];
-
         if (in_array($method, $columnMethods)) {
             if (isset($args[0]) && is_string($args[0])) {
                 $this->columns[] = $args[0];
             }
         }
 
-        $autoIncrementMethods = ['increments', 'autoIncrement'];
-        if (in_array($method, $autoIncrementMethods)) {
-            $this->setKeyGenerator('autoincrement');
-        }
-
-        if ($method === 'uuid') {
-            $this->setKeyGenerator('uuid');
+        $keyMethods = ['autoIncrement', 'bigIncrements', 'increments', 'mediumIncrements', 'tinyIncrements', 'uuid'];
+        if (in_array($method, $keyMethods)) {
+            $this->handleKeyCommands($method, $args);
         }
 
         $this->ignoreMethod($method);
 
         return $this;
     }
 
-    protected function setKeyGenerator(string $generator = 'traditional'): void
-    {
-        $column = end($this->columns);
-        if ($column === '_key' || $column === 'id') {
-            $this->keyGenerator = $generator;
-        }
-    }
-
     protected function ignoreMethod(string $method)
     {
         $info = [];
@@ -320,4 +306,26 @@ public function renameIdField(mixed $fields)
             return $value === 'id' ? '_key' : $value;
         }, $fields);
     }
+
+    /**
+     * @param mixed[] $options
+     * @return mixed[]
+     */
+    protected function setKeyOptions($tableOptions)
+    {
+        $configuredKeyOptions = config('arangodb.schema.keyOptions');
+
+        $columnOptions = [];
+        $columnOptions['type'] = $this->keyGenerator;
+
+        $mergedKeyOptions = (config('arangodb.schema.key_handling.prioritize_configured_key_type'))
+            ? array_merge($columnOptions, $configuredKeyOptions, $tableOptions)
+            : array_merge($configuredKeyOptions, $columnOptions, $tableOptions);
+
+        if ($mergedKeyOptions['type'] === 'autoincrement' && $this->incrementOffset !== 0) {
+            $mergedKeyOptions['offset'] = $this->incrementOffset;
+        }
+
+        return $mergedKeyOptions;
+    }
 }

src/Schema/Concerns/TableCommands.php

@@ -17,35 +17,55 @@ trait TableCommands
     public function create($options = [])
     {
         $parameters = [];
-        $parameters['options'] = array_merge(
-            [
-                'keyOptions' => config('arangodb.schema.keyOptions'),
-            ],
-            $options,
-        );
+        $parameters['options'] = $options;
         $parameters['explanation'] = "Create '{$this->table}' table.";
         $parameters['handler'] = 'table';
 
         return $this->addCommand('create', $parameters);
     }
 
-    public function executeCreateCommand($command)
+    /**
+     * @param string $command
+     * @param mixed[] $args
+     * @return void
+     */
+    public function handleKeyCommands($command, $args)
     {
-        if ($this->connection->pretending()) {
-            $this->connection->logQuery('/* ' . $command->explanation . " */\n", []);
+        $acceptedKeyFields = ['id', '_id', '_key'];
+
+        $columns = ($command === 'autoIncrement') ? end($this->columns) : $args;
+        $columns = (is_array($columns)) ? $columns : [$columns];
 
+        if (count($columns) !== 1 || ! in_array($columns[0], $acceptedKeyFields)) {
             return;
         }
-        $options = $command->options;
 
-        if ($this->keyGenerator !== 'traditional') {
-            $options['keyOptions']['type'] = $this->keyGenerator;
+        if ($command === 'uuid') {
+            $this->keyGenerator = 'uuid';
+
+            return;
         }
 
-        if ($this->keyGenerator === 'autoincrement' && $this->incrementOffset !== 0) {
-            $options['keyOptions']['offset'] = $this->incrementOffset;
+        if (config('arangodb.schema.key_handling.use_traditional_over_autoincrement') === false) {
+            $this->keyGenerator = 'autoincrement';
+
+            return;
         }
 
+        $this->keyGenerator = 'traditional';
+    }
+
+    public function executeCreateCommand($command)
+    {
+        if ($this->connection->pretending()) {
+            $this->connection->logQuery('/* ' . $command->explanation . " */\n", []);
+
+            return;
+        }
+
+        $options = $command->options;
+        $options['keyOptions'] = $this->setKeyOptions($options['keyOptions'] ?? []);
+
         if (!$this->schemaManager->hasCollection($this->table)) {
             $this->schemaManager->createCollection($this->table, $options);
         }

tests/Schema/TableKeyTest.php

@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+use LaravelFreelancerNL\Aranguent\Schema\Blueprint;
+
+test('creating table with default key generator', function () {
+    $schema = DB::connection()->getSchemaBuilder();
+
+    $schema->create('white_walkers', function (Blueprint $table) use (& $creating) {});
+
+    $schemaManager = $this->connection->getArangoClient()->schema();
+
+    $collectionProperties = $schemaManager->getCollectionProperties('white_walkers');
+
+    expect($collectionProperties->keyOptions->type)->toBe('traditional');
+
+    Schema::drop('white_walkers');
+});
+
+test('creating table with different default key generator', function () {
+    Config::set('arangodb.schema.keyOptions.type', 'padded');
+    $schema = DB::connection()->getSchemaBuilder();
+
+    $schema->create('white_walkers', function (Blueprint $table) use (& $creating) {});
+
+    $schemaManager = $this->connection->getArangoClient()->schema();
+
+    $collectionProperties = $schemaManager->getCollectionProperties('white_walkers');
+
+    expect($collectionProperties->keyOptions->type)->toBe('padded');
+
+    Schema::drop('white_walkers');
+});
+
+test('creating table with autoincrement key generator', function () {
+    Config::set('arangodb.schema.key_handling.use_traditional_over_autoincrement', false);
+
+    $schema = DB::connection()->getSchemaBuilder();
+
+    $schema->create('white_walkers', function (Blueprint $table) use (& $creating) {
+        $table->increments('id');
+    });
+
+    $schemaManager = $this->connection->getArangoClient()->schema();
+
+    $collectionProperties = $schemaManager->getCollectionProperties('white_walkers');
+
+    expect($collectionProperties->keyOptions->type)->toBe('autoincrement');
+
+    Schema::drop('white_walkers');
+    Config::set('arangodb.schema.key_handling.use_traditional_over_autoincrement', true);
+});
+
+test('creating table with autoIncrement offset', function () {
+    Config::set('arangodb.schema.key_handling.use_traditional_over_autoincrement', false);
+
+    $schema = DB::connection()->getSchemaBuilder();
+
+    $schema->create('white_walkers', function (Blueprint $table) use (& $creating) {
+        $table->string('id')->autoIncrement()->from(5);
+    });
+
+    $schemaManager = $this->connection->getArangoClient()->schema();
+
+    $collectionProperties = $schemaManager->getCollectionProperties('white_walkers');
+
+    expect($collectionProperties->keyOptions->type)->toBe('autoincrement');
+    expect($collectionProperties->keyOptions->offset)->toBe(5);
+
+    Schema::drop('white_walkers');
+});
+
+test('create table with uuid key generator', function () {
+    $schema = DB::connection()->getSchemaBuilder();
+
+    $schema->create('white_walkers', function (Blueprint $table) use (& $creating) {
+        $table->uuid('id');
+    });
+
+    $schemaManager = $this->connection->getArangoClient()->schema();
+
+    $collectionProperties = $schemaManager->getCollectionProperties('white_walkers');
+
+    expect($collectionProperties->keyOptions->type)->toBe('uuid');
+
+    Schema::drop('white_walkers');
+});
+
+test('table options override column key generator', function () {
+    $schema = DB::connection()->getSchemaBuilder();
+
+    $schema->create('white_walkers', function (Blueprint $table) use (& $creating) {
+        $table->uuid('id');
+    }, [
+        'keyOptions' => [
+            'type' => 'padded',
+        ],
+    ]);
+
+    $schemaManager = $this->connection->getArangoClient()->schema();
+
+    $collectionProperties = $schemaManager->getCollectionProperties('white_walkers');
+
+    expect($collectionProperties->keyOptions->type)->toBe('padded');
+
+    Schema::drop('white_walkers');
+});
+
+test('table options override default key generator', function () {
+    $schema = DB::connection()->getSchemaBuilder();
+
+    $schema->create('white_walkers', function (Blueprint $table) use (& $creating) {}, [
+        'keyOptions' => [
+            'type' => 'padded',
+            'allowUserKeys' => false,
+        ],
+    ]);
+
+    $schemaManager = $this->connection->getArangoClient()->schema();
+
+    $collectionProperties = $schemaManager->getCollectionProperties('white_walkers');
+
+    expect($collectionProperties->keyOptions->type)->toBe('padded');
+    expect($collectionProperties->keyOptions->allowUserKeys)->toBeFalse();
+
+    Schema::drop('white_walkers');
+});