Bagisto Health Check Guide: Using php artisan doctor to Diagnose Your Store
Running an enterprise e-commerce storefront like Bagisto requires several application and infrastructure components to work together reliably.
Bagisto uses a modular architecture, an EAV-based product catalog, Vite, Elasticsearch, Redis, and asynchronous queue workers.
With this architecture, issues such as missing PHP extensions, incorrect file permissions, broken storage links, or stopped queue workers can affect product images, search, background jobs, and checkout.
This is where php artisan doctor and php artisan bagisto:doctor come in. Inspired by diagnostic tools like flutter doctor and brew doctor, these commands check your Bagisto environment, validate important configurations, test service connections, and highlight potential issues with actionable guidance to help keep your store running smoothly.
The 6 Diagnostic Pillars Breakdown
| Pillar | Focus Area | Critical Checks |
|---|---|---|
| 1. PHP Environment | Core PHP & Extensions | PHP >= 8.2, ext-intl, ext-gd (with WebP support), ext-bcmath, memory_limit >= 512M |
| 2. Database & Cache | Persistence & Speed | MySQL 8.0+ , connection latency, Redis/Memcached availability |
| 3. Filesystem & Links | File Permissions & Storage | storage/ (775), bootstrap/cache/ (775), public/storage symlink target exists |
| 4. Queue & Scheduler | Background Processing | Pending queue jobs check, failed jobs audit, cron scheduler heartbeat |
| 5. Bagisto Modules & Cache | EAV & Concord Engine | Concord module registration, EAV attribute integrity, FPC cache driver status |
| 6. Frontend & Vite Assets | Storefront & Admin UI | public/themes/*/build/manifest.json existence, missing asset compilation warnings |
Implementing a Custom php artisan doctor Command in Bagisto
Let’s explore how to build a custom php artisan doctor diagnostic command for your Bagisto package using
packages/Webkul/Core/src/Console/Commands/BagistoDoctorCommand.php
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 |
<?php namespace Webkul\Core\Console\Commands; use Illuminate\Console\Command; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\File; use Illuminate\Support\Facades\Redis; class BagistoDoctorCommand extends Command { /** * The name and signature of the console command. * * @var string */ protected $signature = 'doctor {--quick : Run only essential environment checks}'; /** * The console command description. * * @var string */ protected $description = 'Perform a complete system diagnostic check for Bagisto e-commerce.'; /** * Required PHP extensions for Bagisto 2.x */ protected array $requiredExtensions = [ 'bcmath', 'ctype', 'fileinfo', 'gd', 'intl', 'json', 'mbstring', 'openssl', 'pdo', 'pdo_mysql', 'tokenizer', 'xml', 'zip' ]; /** * Execute the console command. */ public function handle(): int { $this->info("\n=============================================="); $this->info(" BAGISTO SYSTEM DOCTOR - HEALTH DIAGNOSIS "); $this->info("==============================================\n"); $hasError = false; $hasError |= ! $this->checkPhpEnvironment(); $hasError |= ! $this->checkDatabaseConnection(); $hasError |= ! $this->checkFilesystemPermissions(); $hasError |= ! $this->checkStorageSymlink(); if (! $this->option('quick')) { $hasError |= ! $this->checkQueueAndCache(); } $this->newLine(); if ($hasError) { $this->error("❌ Diagnostics completed with issues. Please review the recommended actions above."); return self::FAILURE; } $this->info("✔ All diagnostic checks passed successfully! Your Bagisto store is healthy."); return self::SUCCESS; } /** * Check PHP Version and required extensions. */ protected function checkPhpEnvironment(): bool { $this->line('<fg=cyan>--- 1. PHP Environment & Extensions ---</>'); $passed = true; if (version_compare(PHP_VERSION, '8.2.0', '<')) { $this->line(" <fg=red>[FAIL]</> PHP version 8.2.0 or higher is required. Current: " . PHP_VERSION); $passed = false; } else { $this->line(" <fg=green>[OK]</> PHP Version: " . PHP_VERSION); } $missingExts = []; foreach ($this->requiredExtensions as $ext) { if (! extension_loaded($ext)) { $missingExts[] = $ext; } } if (count($missingExts) > 0) { $this->line(" <fg=red>[FAIL]</> Missing PHP Extensions: " . implode(', ', $missingExts)); $passed = false; } else { $this->line(" <fg=green>[OK]</> All required PHP extensions are installed."); } return $passed; } /** * Verify Database Connection. */ protected function checkDatabaseConnection(): bool { $this->line('<fg=cyan>--- 2. Database Connection Check ---</>'); try { DB::connection()->getPdo(); $dbName = DB::connection()->getDatabaseName(); $this->line(" <fg=green>[OK]</> Connected to database: <comment>{$dbName}</comment>"); return true; } catch (\Exception $e) { $this->line(" <fg=red>[FAIL]</> Database connection error: " . $e->getMessage()); return false; } } /** * Verify Writable Permissions on Critical Folders. */ protected function checkFilesystemPermissions(): bool { $this->line('<fg=cyan>--- 3. Directory Permissions Check ---</>'); $paths = [ storage_path(), base_path('bootstrap/cache'), ]; $passed = true; foreach ($paths as $path) { if (! File::isWritable($path)) { $this->line(" <fg=red>[FAIL]</> Path is not writable: {$path}"); $this->line(" <fg=yellow>Fix:</> Run `chmod -R 775 {$path}`"); $passed = false; } else { $this->line(" <fg=green>[OK]</> Writable permission verified: " . basename($path)); } } return $passed; } /** * Verify Storage Symlink. */ protected function checkStorageSymlink(): bool { $this->line('<fg=cyan>--- 4. Storage Symlink Integrity ---</>'); $publicStoragePath = public_path('storage'); if (! file_exists($publicStoragePath)) { $this->line(" <fg=red>[FAIL]</> Storage symlink missing in public directory."); $this->line(" <fg=yellow>Fix:</> Run `php artisan storage:link`"); return false; } $this->line(" <fg=green>[OK]</> Symbolic link `public/storage` exists."); return true; } /** * Verify Cache Driver and Queue worker. */ protected function checkQueueAndCache(): bool { $this->line('<fg=cyan>--- 5. Cache & Queue Services ---</>'); $driver = config('cache.default'); $this->line(" <fg=green>[OK]</> Default Cache Driver: <comment>{$driver}</comment>"); return true; } } |
then register the following commands in CoreServiceProvider
|
1 |
use Webkul\Core\Console\Commands\BagistoDoctorCommand; |
|
1 2 3 4 5 6 7 8 |
protected function registerCommands(): void { if ($this->app->runningInConsole()) { $this->commands([ BagistoDoctorCommand::class ]); } } |
It will result the following Output as
Conclusion
Maintaining a healthy Bagisto installation requires more than checking individual components when something goes wrong. A diagnostic command like php artisan doctor
provides a centralized way to identify configuration, dependency, filesystem, cache, queue, and service-related issues before they impact your store.
By extending BagistoDoctorCommand with checks specific to your package and environment, you can make deployments easier to validate and troubleshooting much faster.
Whether you are setting up a new Bagisto store, deploying updates, or maintaining a production environment, a reliable health-check command can help keep your application stable and ready to serve customers.
You can also hire Laravel developers to build your custom solutions on Laravel. To explore the available extensions for Bagisto, you can check out the Bagisto extension marketplace.
Be the first to comment.