Merge pull request #994 from bavix/identifier

[11.3] UUID7. IdentifierFactoryServiceInterface

Author: rez1dent3

config/config.php

@@ -22,6 +22,7 @@
 use Bavix\Wallet\Internal\Service\ConnectionService;
 use Bavix\Wallet\Internal\Service\DatabaseService;
 use Bavix\Wallet\Internal\Service\DispatcherService;
+use Bavix\Wallet\Internal\Service\IdentifierFactoryService;
 use Bavix\Wallet\Internal\Service\JsonService;
 use Bavix\Wallet\Internal\Service\LockService;
 use Bavix\Wallet\Internal\Service\MathService;
@@ -209,8 +210,18 @@
          * The service for generating UUIDs.
          *
          * @var string
+         *
+         * @deprecated use identifier.
+         * @see IdentifierFactoryService
          */
         'uuid' => UuidFactoryService::class,
+
+        /**
+         * The service for generating identifiers.
+         *
+         * @var string
+         */
+        'identifier' => IdentifierFactoryService::class,
     ],
 
     /**

database/2021_11_02_202021_update_wallets_uuid_table.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-use Bavix\Wallet\Internal\Service\UuidFactoryServiceInterface;
+use Bavix\Wallet\Internal\Service\IdentifierFactoryServiceInterface;
 use Bavix\Wallet\Models\Wallet;
 use Illuminate\Database\Migrations\Migration;
 use Illuminate\Database\Schema\Blueprint;
@@ -27,7 +27,7 @@ public function up(): void
 
         Wallet::query()->chunk(10000, static function (Collection $wallets) {
             $wallets->each(function (Wallet $wallet) {
-                $wallet->uuid = app(UuidFactoryServiceInterface::class)->uuid4();
+                $wallet->uuid = app(IdentifierFactoryServiceInterface::class)->generate();
                 $wallet->save();
             });
         });

docs/guide/cqrs/create-wallet.md

@@ -50,7 +50,7 @@ public function __invoke(CreateWalletCommandMessage $message): void
 }
 ```
 
-You receive requests to create a wallet on the backend, and you create them asynchronously. UUID4 is generated on the client side and the client already knows it. You will not be able to create two wallets with one uuid, because the column in the database is unique.
+You receive requests to create a wallet on the backend, and you create them asynchronously. UUID is generated on the client side and the client already knows it. You will not be able to create two wallets with one uuid, because the column in the database is unique.
 
 The user no longer needs to wait for the creation of a wallet, it is enough to know the uuid. You get the most stable application.
 

src/Internal/Assembler/TransactionDtoAssembler.php

@@ -7,13 +7,13 @@
 use Bavix\Wallet\Internal\Dto\TransactionDto;
 use Bavix\Wallet\Internal\Dto\TransactionDtoInterface;
 use Bavix\Wallet\Internal\Service\ClockServiceInterface;
-use Bavix\Wallet\Internal\Service\UuidFactoryServiceInterface;
+use Bavix\Wallet\Internal\Service\IdentifierFactoryServiceInterface;
 use Illuminate\Database\Eloquent\Model;
 
 final readonly class TransactionDtoAssembler implements TransactionDtoAssemblerInterface
 {
     public function __construct(
-        private UuidFactoryServiceInterface $uuidService,
+        private IdentifierFactoryServiceInterface $identifierFactoryService,
         private ClockServiceInterface $clockService,
     ) {
     }
@@ -28,7 +28,7 @@ public function create(
         ?string $uuid
     ): TransactionDtoInterface {
         return new TransactionDto(
-            $uuid ?? $this->uuidService->uuid4(),
+            $uuid ?? $this->identifierFactoryService->generate(),
             $payable->getMorphClass(),
             $payable->getKey(),
             $walletId,

src/Internal/Assembler/TransferDtoAssembler.php

@@ -7,13 +7,13 @@
 use Bavix\Wallet\Internal\Dto\TransferDto;
 use Bavix\Wallet\Internal\Dto\TransferDtoInterface;
 use Bavix\Wallet\Internal\Service\ClockServiceInterface;
-use Bavix\Wallet\Internal\Service\UuidFactoryServiceInterface;
+use Bavix\Wallet\Internal\Service\IdentifierFactoryServiceInterface;
 use Illuminate\Database\Eloquent\Model;
 
 final readonly class TransferDtoAssembler implements TransferDtoAssemblerInterface
 {
     public function __construct(
-        private UuidFactoryServiceInterface $uuidService,
+        private IdentifierFactoryServiceInterface $identifierFactoryService,
         private ClockServiceInterface $clockService,
     ) {
     }
@@ -33,7 +33,7 @@ public function create(
         ?array $extra,
     ): TransferDtoInterface {
         return new TransferDto(
-            $uuid ?? $this->uuidService->uuid4(),
+            $uuid ?? $this->identifierFactoryService->generate(),
             $depositId,
             $withdrawId,
             $status,

src/Internal/Service/IdentifierFactoryService.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bavix\Wallet\Internal\Service;
+
+use Ramsey\Uuid\Exception\InvalidArgumentException;
+use Ramsey\Uuid\Exception\InvalidUuidStringException;
+use Ramsey\Uuid\Exception\UnsupportedOperationException;
+use Ramsey\Uuid\Exception\UuidExceptionInterface;
+use Ramsey\Uuid\UuidFactory;
+
+final readonly class IdentifierFactoryService implements IdentifierFactoryServiceInterface
+{
+    /**
+     * @param UuidFactory $uuidFactory Service for generating UUIDs.
+     * @param ClockServiceInterface $clockService Service for getting the current time.
+     */
+    public function __construct(
+        private UuidFactory $uuidFactory,
+        private ClockServiceInterface $clockService,
+    ) {
+    }
+
+    /**
+     * Generate a ID string using the uuid7 algorithm.
+     *
+     * uuid7 is a time-based UUID algorithm that uses the current time in milliseconds,
+     * combined with a random number to generate a unique ID.
+     *
+     * @return non-empty-string The generated ID string.
+     *
+     * @throws InvalidArgumentException If a field is invalid in the UUID.
+     * @throws InvalidUuidStringException If the string we are parsing is not a valid UUID.
+     * @throws UnsupportedOperationException If the UUID implementation can't support a feature.
+     * @throws UuidExceptionInterface If there is an error generating the UUID.
+     */
+    public function generate(): string
+    {
+        return $this->uuidFactory->uuid7($this->clockService->now())
+            ->toString();
+    }
+}

src/Internal/Service/IdentifierFactoryServiceInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bavix\Wallet\Internal\Service;
+
+use Ramsey\Uuid\Exception\InvalidArgumentException;
+use Ramsey\Uuid\Exception\InvalidUuidStringException;
+use Ramsey\Uuid\Exception\UnsupportedOperationException;
+use Ramsey\Uuid\Exception\UuidExceptionInterface;
+
+interface IdentifierFactoryServiceInterface
+{
+    /**
+     * Generate a unique identifier string.
+     *
+     * This method generates a unique identifier string using internal algorithm.
+     *
+     * @return non-empty-string The generated ID string.
+     *
+     * @throws InvalidArgumentException If a field is invalid in the UUID.
+     * @throws InvalidUuidStringException If the string we are parsing is not a valid UUID.
+     * @throws UnsupportedOperationException If the UUID implementation can't support a feature.
+     * @throws UuidExceptionInterface If there is an error generating the UUID.
+     */
+    public function generate(): string;
+}

src/Internal/Service/UuidFactoryService.php

@@ -6,6 +6,9 @@
 
 use Ramsey\Uuid\UuidFactory;
 
+/**
+ * @codeCoverageIgnore
+ */
 final readonly class UuidFactoryService implements UuidFactoryServiceInterface
 {
     public function __construct(

src/Internal/Service/UuidFactoryServiceInterface.php

@@ -4,6 +4,11 @@
 
 namespace Bavix\Wallet\Internal\Service;
 
+/**
+ * @deprecated use IdentifierFactoryServiceInterface instead.
+ * @see IdentifierFactoryServiceInterface
+ * @since 11.3.0
+ */
 interface UuidFactoryServiceInterface
 {
     /**

src/Models/Wallet.php

@@ -12,8 +12,8 @@
 use Bavix\Wallet\Interfaces\WalletFloat;
 use Bavix\Wallet\Internal\Exceptions\ExceptionInterface;
 use Bavix\Wallet\Internal\Exceptions\TransactionFailedException;
+use Bavix\Wallet\Internal\Service\IdentifierFactoryServiceInterface;
 use Bavix\Wallet\Internal\Service\MathServiceInterface;
-use Bavix\Wallet\Internal\Service\UuidFactoryServiceInterface;
 use Bavix\Wallet\Services\AtomicServiceInterface;
 use Bavix\Wallet\Services\RegulatorServiceInterface;
 use Bavix\Wallet\Traits\CanConfirm;
@@ -193,6 +193,6 @@ public function getCurrencyAttribute(): string
 
     protected function initializeMorphOneWallet(): void
     {
-        $this->uuid ??= app(UuidFactoryServiceInterface::class)->uuid4();
+        $this->uuid ??= app(IdentifierFactoryServiceInterface::class)->generate();
     }
 }