Upgrade Guide
- Introduction
- Release Frequency & SemVer Support
- Upgrading to 1.0.0 from Legacy Skeleton
- Automated Updates via CLI (
./reyhan update)
Introduction
This guide outlines breaking changes, deprecations, database migrations, and step-by-step procedures for upgrading your Reyhan Commerce applications between releases.
Release Frequency & SemVer Support
Reyhan Commerce adheres strictly to Semantic Versioning (SemVer):
- Major Releases (
X.0.0): May include breaking changes, signature alterations to public interfaces/actions, or architectural decoupling. - Minor Releases (
1.X.0): Deliver new domain features, payment/logistics drivers, new pipeline stages, and additive non-breaking database schema changes. - Patch Releases (
1.0.X): Provide critical security fixes, tax calculation patches, and performance optimizations with 100% backward compatibility.
Upgrading to 1.0.0 from Legacy Skeleton
Estimated Upgrade Duration: 10 – 15 minutes
Impact Level: High
The v1.0.0 milestone transforms Reyhan from a monolithic starter kit into an independent, upstream-upgradable e-commerce framework (reyhan-commerce/core).
Dependency & Namespace Migration
All core e-commerce classes previously residing under App\ have moved to the framework vendor namespace Reyhan\Core\:
| Previous Class | New Framework Class |
|---|---|
App\Models\Order | Reyhan\Core\Models\Order |
App\Models\Product | Reyhan\Core\Models\Product |
App\Models\Cart | Reyhan\Core\Models\Cart |
App\Actions\Checkout\CreateOrderAction | Reyhan\Core\Actions\Checkout\CreateOrderAction |
App\Pipelines\Checkout\OrderCreationPipeline | Reyhan\Core\Pipelines\Checkout\OrderCreationPipeline |
Update your namespace imports in your application's app/ directory:
// [Before]
use App\Models\Product;
use App\Actions\Checkout\CreateOrderAction;
// [After]
use Reyhan\Core\Models\Product;
use Reyhan\Core\Actions\Checkout\CreateOrderAction;Admin Panel & Plugin Registration
Core Filament resources, pages, and widgets are now distributed via the official ReyhanCorePlugin.
In app/Providers/Filament/AdminPanelProvider.php, register the plugin:
use Filament\Panel;
use Reyhan\Core\ReyhanCorePlugin;
public function panel(Panel $panel): Panel
{
return $panel
->default()
->id('admin')
->path('admin')
// Automatically registers all core e-commerce resources & widgets
->plugin(ReyhanCorePlugin::make())
// Discover any custom userland resources created in app/Filament
->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')
->discoverPages(in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages');
}Action Signatures & Dynamic Contracts
CreateOrderAction::execute() now accepts UserContract|User instead of a concrete class, permitting seamless substitution of customized customer models:
// [Before]
public function execute(User $user, CreateOrderData $data): CreateOrderResultData
// [After]
public function execute(UserContract|User $user, CreateOrderData $data): CreateOrderResultDataAutomated Migrations
Core database migrations are loaded automatically from the framework package. You no longer need to copy migration files into your root database/migrations directory.
Run pending migrations:
php artisan migrate --forceAutomated Updates via CLI (./reyhan update)
Reyhan includes an automated update command to streamline upstream package updates:
./reyhan updateThis command executes the following zero-downtime routine:
- Puts the application into maintenance mode (
php artisan down). - Pulls upstream packages via Composer.
- Automatically executes database migrations (
php artisan migrate --force). - Recompiles and publishes updated assets.
- Clears stale application, route, and Redis caches.
- Restores application traffic (
php artisan up).