Skip to content

Customization & Extensibility Overview ​

Introduction ​

Reyhan Commerce is engineered from the ground up to be 100% extensible without ever modifying core framework files. In traditional monolithic e-commerce software, customizing critical business rulesβ€”such as altering the checkout flow, swapping out payment gateways, or adding custom columns and relationships to modelsβ€”often required risky core modifications or fragile monkey-patching that broke upon future upgrades.

In Reyhan, every core domain entity, computational pipeline, notification channel, and administrative component is resolved through dedicated contracts and dynamic registries. When you upgrade Reyhan via ./reyhan update, all of your sovereign business logic, custom models, and modular plugins remain completely intact and functional.


The Zero Core Modification Principle ​

The core architectural tenet of Reyhan is:

All application-specific logic lives exclusively within your application space (app/, config/, or extensions/). The vendor/reyhan-commerce/core package is strictly read-only and immutable.

By adhering to this principle:

  1. Zero-Breaking Upgrades: You can update the framework seamlessly using ./reyhan update with automated database backups and zero downtime.
  2. Clean Separation of Concerns: Core commerce mechanics (PostgreSQL 17 JSONB matrices, atomic Redis Lua stock locks, ledger accounting) are maintained upstream, while your specialized business rules live in your repository.
  3. Strict Type Safety & Pest Verification: All customization points adhere to strongly typed PHP 8.4 contracts and can be verified using Pest 4 architecture and feature tests.

Extensibility Points at a Glance ​

Reyhan provides dedicated extension vectors for every layer of your commerce stack:

Customization VectorMechanismTypical Use Cases
Dynamic Model Swappingconfig/reyhan.php['models'] & Reyhan::useModel()Adding custom relationships, custom scopes, loyalty point calculators, or national ID attributes to Order, Product, User, etc.
Business PipelinesPipeline pattern & config/reyhan.php['pipelines']Injecting custom fraud checks, ERP inventory verification (Sepidar/Holo), custom tiered B2B pricing, or VIP discounts.
Payment GatewaysPaymentGatewayManager & GatewayDriverContractAdding Iranian bank gateways (Saman, Mellat, Zarinpal, Sadad), crypto payments, or in-house corporate credit wallets.
SMS & OTP DriversSmsManager & SmsGatewayContractIntegrating Kavenegar, FarazSMS, Ghasedak, or specialized corporate SMS aggregators with custom fast-pattern templates.
Shipping & CarriersShippingRateCalculatorContractCalculating dynamic freight based on volumetric weight, province/city tariffs (Tipax, Post, Chapar), or local courier APIs (SnappBox).
Filament Admin PanelAdminPanelProvider & Filament v5 PluginsAdding custom Resources, Pages, interactive Widgets, custom themes, or granular RBAC permission gates (filament-shield).
Modular ExtensionsDrop-in extensions/ directory & PSR-4 AutoloadingBuilding isolated, distributable modules with their own routes, migrations, and service providers without editing root files.
Domain Events & ListenersLaravel Event Dispatcher & Async QueuesReacting to events like OrderCreated, PaymentVerified, or StockDecremented for real-time CRM and accounting syncs.

Resolution Architecture ​

Reyhan utilizes central contract registries within the service container. When an incoming HTTP request or queue job executes an Action, the framework resolves dependencies through contracts rather than concrete implementations:


Best Practices for Sovereign Extensions ​

When customizing your Reyhan application, adhere to the following best practices:

1. Always Implement Core Contracts ​

When extending models or services, ensure your class implements the corresponding domain contract (e.g. Reyhan\Core\Contracts\Models\OrderContract). This ensures static analysis tools like Larastan and PHPStan (level 9/max) guarantee type consistency.

2. Encapsulate Business Logic in Single-Use Actions ​

Avoid bloating Eloquent models or controller methods with complex mutation logic. Follow the Reyhan Action pattern: create final, strongly typed classes in app/Actions/ with an execute() method.

3. Write Pest Feature & Concurrency Tests ​

Whenever you override a pipeline or model, write automated tests using Pest 4 to verify that the container resolves your custom implementation and that edge cases are guarded against regressions.

bash
# Run tests after adding customizations
php artisan test --filter=CustomizationTest

Released under the MIT License.