Add Hypervel Doctor

composer.json

@@ -48,6 +48,7 @@
         "aws/aws-sdk-php": "^3.322.9",
         "brick/math": "^1.0",
         "chillerlan/php-qrcode": "^6.0",
+        "composer/semver": "^3.5.1",
         "defuse/php-encryption": "^2.4",
         "doctrine/inflector": "^2.0.5",
         "dragonmantank/cron-expression": "^3.4",
@@ -60,6 +61,7 @@
         "guzzlehttp/uri-template": "^1.0 || ^2.0",
         "hypervel/guzzle": "^8.3",
         "hypervel/guzzle-promises": "^3.1",
+        "laravel/agent-detector": "^2.0.5",
         "laravel/serializable-closure": "^2.0.11",
         "lcobucci/jwt": "^5.6",
         "league/commonmark": "^2.10.3",
@@ -121,7 +123,6 @@
         "algolia/algoliasearch-client-php": "^4.49.0",
         "brianium/paratest": "^7.27.2",
         "composer/composer": "^2.10.3",
-        "composer/semver": "^3.4",
         "fakerphp/faker": "^1.24",
         "friendsofphp/php-cs-fixer": "^3.57.2",
         "intervention/image": "^4.2",
@@ -168,6 +169,7 @@
         "hypervel/database": "self.version",
         "hypervel/di": "self.version",
         "hypervel/docs": "self.version",
+        "hypervel/doctor": "self.version",
         "hypervel/encryption": "self.version",
         "hypervel/engine": "self.version",
         "hypervel/events": "self.version",
@@ -259,6 +261,7 @@
             "Hypervel\\Data\\": "src/data/src/",
             "Hypervel\\Database\\": "src/database/src/",
             "Hypervel\\Di\\": "src/di/src/",
+            "Hypervel\\Doctor\\": "src/doctor/src/",
             "Hypervel\\Encryption\\": "src/encryption/src/",
             "Hypervel\\Engine\\": "src/engine/src/",
             "Hypervel\\Events\\": "src/events/src/",
@@ -399,6 +402,7 @@
                 "Hypervel\\Cookie\\CookieServiceProvider",
                 "Hypervel\\Data\\DataServiceProvider",
                 "Hypervel\\Database\\DatabaseServiceProvider",
+                "Hypervel\\Doctor\\DoctorServiceProvider",
                 "Hypervel\\Encryption\\EncryptionServiceProvider",
                 "Hypervel\\Engine\\EngineServiceProvider",
                 "Hypervel\\Events\\EventServiceProvider",

src/cache/src/CacheManager.php

@@ -215,7 +215,7 @@ protected function createDatabaseDriver(array $config): Repository
             $config['connection'] ?? null,
             $config['table'],
             $this->getPrefix($config),
-            $config['lock_table'] ?? 'cache_locks',
+            $config['lock_table'] ?? DatabaseStore::DEFAULT_LOCK_TABLE,
             $config['lock_lottery'] ?? [2, 100],
             $config['lock_timeout'] ?? 86400,
             serializableClassPolicy: $this->serializableClassPolicy,
@@ -235,6 +235,8 @@ protected function createDatabaseDriver(array $config): Repository
      */
     protected function createFailoverDriver(array $config): Repository
     {
+        $this->ensureStoresAreAcyclic($config);
+
         return $this->repository(new FailoverStore(
             $this,
             $this->app->make(DispatcherContract::class),
@@ -357,6 +359,8 @@ protected function createSwooleDriver(array $config): Repository
      */
     protected function createStackDriver(array $config): Repository
     {
+        $this->ensureStoresAreAcyclic($config);
+
         $stores = collect($config['stores'])->map(function ($config, $name) {
             if (! is_array($config)) {
                 $name = $config;
@@ -371,6 +375,44 @@ protected function createStackDriver(array $config): Repository
         return $this->repository(new StackStore($stores), $config);
     }
 
+    /**
+     * Reject circular built-in store definitions before resolving their layers.
+     *
+     * @param list<string> $path
+     */
+    protected function ensureStoresAreAcyclic(array $config, array $path = []): void
+    {
+        $driver = $config['driver'] ?? null;
+
+        if (! in_array($driver, ['stack', 'failover'], true)
+            || isset($this->customCreators[$driver])
+            || ! is_array($config['stores'] ?? null)) {
+            return;
+        }
+
+        foreach ($config['stores'] as $name => $options) {
+            $name = $driver === 'stack' && is_array($options) ? $name : $options;
+            $name = $name instanceof UnitEnum ? (string) enum_value($name) : $name;
+            $name ??= $this->getDefaultDriver();
+
+            if (! is_string($name)) {
+                continue;
+            }
+
+            if (($cycleStart = array_search($name, $path, true)) !== false) {
+                $cycle = [...array_slice($path, $cycleStart), $name];
+
+                throw new InvalidArgumentException(
+                    'Circular cache store definition detected: ' . implode(' -> ', $cycle) . '.'
+                );
+            }
+
+            if (($child = $this->getConfig($name)) !== null) {
+                $this->ensureStoresAreAcyclic($child, [...$path, $name]);
+            }
+        }
+    }
+
     /**
      * Create a new cache repository with the given implementation.
      */

src/cache/src/Console/CacheTableCommand.php

@@ -4,12 +4,15 @@
 
 namespace Hypervel\Cache\Console;
 
+use Hypervel\Cache\DatabaseStore;
 use Hypervel\Console\MigrationGeneratorCommand;
 use Symfony\Component\Console\Attribute\AsCommand;
 
 #[AsCommand(name: 'make:cache-table', aliases: ['cache:table'])]
 class CacheTableCommand extends MigrationGeneratorCommand
 {
+    public const string TABLE = 'cache';
+
     /**
      * The name and signature of the console command.
      */
@@ -33,8 +36,8 @@ class CacheTableCommand extends MigrationGeneratorCommand
     public function handle(): int
     {
         $tables = [
-            'cache' => __DIR__ . '/stubs/cache.stub',
-            'cache_locks' => __DIR__ . '/stubs/cache-locks.stub',
+            self::TABLE => __DIR__ . '/stubs/cache.stub',
+            DatabaseStore::DEFAULT_LOCK_TABLE => __DIR__ . '/stubs/cache-locks.stub',
         ];
 
         foreach ($tables as $table => $stub) {
@@ -56,7 +59,7 @@ public function handle(): int
      */
     protected function migrationTableName(): string
     {
-        return 'cache';
+        return self::TABLE;
     }
 
     /**

src/cache/src/DatabaseStore.php

@@ -23,6 +23,8 @@ class DatabaseStore implements CanFlushLocks, LockProvider, Store
 {
     use InteractsWithTime;
 
+    public const string DEFAULT_LOCK_TABLE = 'cache_locks';
+
     /**
      * The database connection resolver.
      */
@@ -81,7 +83,7 @@ public function __construct(
         ?string $connectionName,
         string $table,
         string $prefix = '',
-        string $lockTable = 'cache_locks',
+        string $lockTable = self::DEFAULT_LOCK_TABLE,
         array $lockLottery = [2, 100],
         int $defaultLockTimeoutInSeconds = 86400,
         array|bool|null $serializableClasses = null,

src/cache/src/FailoverStore.php

@@ -19,6 +19,7 @@
 use Swoole\Coroutine\CanceledException;
 use Throwable;
 use UnitEnum;
+use WeakReference;
 
 use function Hypervel\Support\enum_value;
 
@@ -27,8 +28,8 @@ class FailoverStore extends TaggableStore implements AuthoritativeRawReadable, C
     /**
      * Context key prefix for the caches which failed on the last action.
      *
-     * Scoped per instance via spl_object_id() so multiple failover stores
-     * in the same coroutine don't share failure history.
+     * Entries pair a weak owner with its failure list. A dead or different owner
+     * means no history, since released object IDs may be reused within a coroutine.
      *
      * Stored in coroutine Context instead of an instance property because this
      * store is a worker-lifetime singleton (cached in CacheManager::$stores).
@@ -348,8 +349,7 @@ public function getPrefix(): string
     protected function attemptOnAllStores(Closure|string $method, array $arguments = []): mixed
     {
         $contextKey = self::FAILING_CACHES_CONTEXT_PREFIX . spl_object_id($this);
-
-        $failingCaches = CoroutineContext::get($contextKey, []);
+        $failingCaches = $this->failingCaches($contextKey);
 
         [$lastException, $failedCaches] = [null, []];
 
@@ -382,7 +382,7 @@ protected function attemptOnAllStores(Closure|string $method, array $arguments =
                 }
             }
         } finally {
-            CoroutineContext::set($contextKey, $failedCaches);
+            $this->rememberFailingCaches($contextKey, $failedCaches);
         }
 
         throw $lastException ?? new RuntimeException('All failover cache stores failed.');
@@ -396,7 +396,7 @@ protected function attemptOnAllStores(Closure|string $method, array $arguments =
     protected function attemptOnEveryStore(string $method, array $arguments): array
     {
         $contextKey = self::FAILING_CACHES_CONTEXT_PREFIX . spl_object_id($this);
-        $failingCaches = CoroutineContext::get($contextKey, []);
+        $failingCaches = $this->failingCaches($contextKey);
         $results = [];
         $lastException = null;
         $failedCaches = [];
@@ -425,12 +425,34 @@ protected function attemptOnEveryStore(string $method, array $arguments): array
                 }
             }
         } finally {
-            CoroutineContext::set($contextKey, $failedCaches);
+            $this->rememberFailingCaches($contextKey, $failedCaches);
         }
 
         return [$results, $lastException];
     }
 
+    /**
+     * Get failure history belonging to this store instance.
+     *
+     * @return list<string>
+     */
+    private function failingCaches(string $contextKey): array
+    {
+        $state = CoroutineContext::get($contextKey);
+
+        return $state !== null && $state[0]->get() === $this ? $state[1] : [];
+    }
+
+    /**
+     * Remember the stores that failed during the current operation.
+     *
+     * @param list<string> $failedCaches
+     */
+    private function rememberFailingCaches(string $contextKey, array $failedCaches): void
+    {
+        CoroutineContext::set($contextKey, [WeakReference::create($this), $failedCaches]);
+    }
+
     /**
      * Build failure history after an interrupted failover attempt.
      *

src/cache/src/Redis/Console/Doctor/Checks/HashFieldExpirationCheck.php

@@ -6,6 +6,7 @@
 
 use Hypervel\Cache\Redis\Console\Doctor\CheckResult;
 use Hypervel\Redis\RedisConnection;
+use Hypervel\Redis\RedisRequirements;
 use Throwable;
 
 /**
@@ -82,7 +83,9 @@ public function getFixInstructions(): ?string
         }
 
         if (! $this->available) {
-            return 'Any tagging mode requires Redis 8.0+ or Valkey 9.0+ for hash-field expiration commands such as HSETEX and HEXPIRE. Upgrade your Redis/Valkey server, or switch to all tagging mode.';
+            return 'Any tagging mode requires Redis ' . RedisRequirements::HASH_FIELD_EXPIRATION_REDIS_VERSION
+                . '+ or Valkey ' . RedisRequirements::HASH_FIELD_EXPIRATION_VALKEY_VERSION
+                . '+ for hash-field expiration commands such as HSETEX and HEXPIRE. Upgrade your Redis/Valkey server, or switch to all tagging mode.';
         }
 
         return null;

src/cache/src/Redis/Console/Doctor/Checks/PhpRedisCheck.php

@@ -5,16 +5,13 @@
 namespace Hypervel\Cache\Redis\Console\Doctor\Checks;
 
 use Hypervel\Cache\Redis\Console\Doctor\CheckResult;
+use Hypervel\Redis\RedisRequirements;
 
 /**
  * Checks that PHPRedis is installed with the version required by the tag mode.
  */
 final class PhpRedisCheck implements EnvironmentCheckInterface
 {
-    private const string MINIMUM_VERSION = '6.1.0';
-
-    private const string ANY_TAG_MINIMUM_VERSION = '6.3.0';
-
     private ?string $installedVersion = null;
 
     /**
@@ -84,7 +81,7 @@ public function getFixInstructions(): ?string
     private function requiredVersion(): string
     {
         return $this->taggingMode === 'any'
-            ? self::ANY_TAG_MINIMUM_VERSION
-            : self::MINIMUM_VERSION;
+            ? RedisRequirements::HASH_FIELD_EXPIRATION_PHPREDIS_VERSION
+            : RedisRequirements::MINIMUM_PHPREDIS_VERSION;
     }
 }

src/cache/src/Redis/Console/Doctor/Checks/RedisVersionCheck.php

@@ -6,21 +6,17 @@
 
 use Hypervel\Cache\Redis\Console\Doctor\CheckResult;
 use Hypervel\Redis\RedisConnection;
+use Hypervel\Redis\RedisRequirements;
 use Throwable;
 
 /**
  * Checks that Redis/Valkey version meets requirements.
  *
- * For any mode: Requires Redis 8.0+ or Valkey 9.0+ for hash-field
- * expiration commands including HSETEX and HEXPIRE.
+ * For any mode: Requires hash-field expiration commands including HSETEX and HEXPIRE.
  * For all mode: Any version is acceptable (just verifies connection).
  */
 final class RedisVersionCheck implements EnvironmentCheckInterface
 {
-    private const string REDIS_REQUIRED_VERSION = '8.0.0';
-
-    private const string VALKEY_REQUIRED_VERSION = '9.0.0';
-
     private ?string $serviceName = null;
 
     private ?string $serviceVersion = null;
@@ -57,11 +53,11 @@ public function run(): CheckResult
             if (isset($info['valkey_version'])) {
                 $this->serviceName = 'Valkey';
                 $this->serviceVersion = $info['valkey_version'];
-                $requiredVersion = self::VALKEY_REQUIRED_VERSION;
+                $requiredVersion = RedisRequirements::HASH_FIELD_EXPIRATION_VALKEY_VERSION;
             } elseif (isset($info['redis_version'])) {
                 $this->serviceName = 'Redis';
                 $this->serviceVersion = $info['redis_version'];
-                $requiredVersion = self::REDIS_REQUIRED_VERSION;
+                $requiredVersion = RedisRequirements::HASH_FIELD_EXPIRATION_REDIS_VERSION;
             } else {
                 $result->assert(false, 'Could not determine Redis/Valkey version');
 
@@ -72,7 +68,7 @@ public function run(): CheckResult
 
             // Version requirement only applies to any mode
             if ($this->taggingMode === 'any') {
-                $versionIsSupported = version_compare($this->serviceVersion, $requiredVersion, '>=');
+                $versionIsSupported = RedisRequirements::hashFieldExpirationServerError($info) === null;
                 $result->assert(
                     $versionIsSupported,
                     "{$this->serviceName} version >= {$requiredVersion} (required for any tagging mode)"
@@ -105,14 +101,14 @@ public function getFixInstructions(): ?string
         }
 
         if ($this->serviceName === 'Redis' && $this->serviceVersion !== null) {
-            if (version_compare($this->serviceVersion, self::REDIS_REQUIRED_VERSION, '<')) {
-                return 'Upgrade to Redis ' . self::REDIS_REQUIRED_VERSION . '+ or Valkey ' . self::VALKEY_REQUIRED_VERSION . '+ for any tagging mode';
+            if (version_compare($this->serviceVersion, RedisRequirements::HASH_FIELD_EXPIRATION_REDIS_VERSION, '<')) {
+                return 'Upgrade to Redis ' . RedisRequirements::HASH_FIELD_EXPIRATION_REDIS_VERSION . '+ or Valkey ' . RedisRequirements::HASH_FIELD_EXPIRATION_VALKEY_VERSION . '+ for any tagging mode';
             }
         }
 
         if ($this->serviceName === 'Valkey' && $this->serviceVersion !== null) {
-            if (version_compare($this->serviceVersion, self::VALKEY_REQUIRED_VERSION, '<')) {
-                return 'Upgrade to Valkey ' . self::VALKEY_REQUIRED_VERSION . '+ for any tagging mode';
+            if (version_compare($this->serviceVersion, RedisRequirements::HASH_FIELD_EXPIRATION_VALKEY_VERSION, '<')) {
+                return 'Upgrade to Valkey ' . RedisRequirements::HASH_FIELD_EXPIRATION_VALKEY_VERSION . '+ for any tagging mode';
             }
         }
 

src/console/src/Application.php

@@ -226,6 +226,7 @@ public static function forgetBootstrappers(): void
      * Run an Artisan console command by name.
      *
      * @throws CommandNotFoundException
+     * @throws Throwable when command execution fails
      */
     public function call(string|SymfonyCommand $command, array $parameters = [], ?OutputInterface $outputBuffer = null): int
     {

src/contracts/src/Console/Application.php

@@ -9,6 +9,7 @@
 use Symfony\Component\Console\Exception\CommandNotFoundException;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
+use Throwable;
 
 interface Application
 {
@@ -48,6 +49,7 @@ public function run(?InputInterface $input = null, ?OutputInterface $output = nu
      * Run an Artisan console command by name.
      *
      * @throws CommandNotFoundException
+     * @throws Throwable when command execution fails
      */
     public function call(string|SymfonyCommand $command, array $parameters = [], ?OutputInterface $outputBuffer = null): int;