itmosoft / laravel-stores
Multi-store storefront management for Laravel applications, with domains, branding, settings, default-store support, and request store resolution.
Requires
- php: ^8.3
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/routing: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- orchestra/testbench: ^10.0 || ^11.0
- phpunit/phpunit: ^11.5 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Multi-store storefront management for Laravel applications. Manage store records, custom domains, branding, settings, default-store selection, and request-time store resolution.
Requirements
- PHP 8.3+
- Laravel 12 or 13
Installation
composer require itmosoft/laravel-stores php artisan vendor:publish --tag=itmosoft-stores-config php artisan vendor:publish --tag=itmosoft-stores-migrations php artisan migrate
Create a store
use ItmoSoft\Stores\Services\StoreManager; $store = app(StoreManager::class)->create([ 'name' => 'Gemini Traders', 'description' => 'Retail storefront', 'is_active' => true, 'is_default' => true, 'settings' => [ 'currency' => 'PKR', 'timezone' => 'Asia/Karachi', ], 'branding' => [ 'logo' => 'stores/gemini/logo.svg', 'primary_color' => '#18243A', ], ]);
Register domains
$domain = app(StoreManager::class)->addDomain( store: $store, domain: 'shop.example.com', primary: true, verified: true, );
Domains are normalized to lowercase, with the port and trailing DNS dot removed. The database enforces global domain uniqueness.
Resolve the current store
Add the middleware to storefront routes:
Route::middleware('store.resolve')->group(function () { Route::get('/', function (Request $request) { $store = $request->attributes->get('itmosoft_store'); return response()->json([ 'store' => $store->name, 'settings' => $store->settings, ]); }); });
The middleware resolves the request host against registered, verified domains and returns HTTP 404 when no active store matches by default. Mark a domain verified only after your application has completed its DNS or ownership verification process.
Default store
$defaultStore = app(StoreManager::class)->default(); app(StoreManager::class)->setDefault($store);
Setting a store as default clears the previous default within a database transaction.
Configuration
Published file: config/itmosoft-stores.php.
| Setting | Default | Purpose |
|---|---|---|
stores_table |
stores |
Store table |
domains_table |
store_domains |
Domain table |
require_active_store |
true |
Resolve only active stores in middleware |
request_attribute |
itmosoft_store |
Request attribute containing resolved store |
default_store_fallback |
false |
Fall back to default store when host is unknown |
Scope and architecture
This package models storefronts. It does not implement tenant isolation, catalog, inventory, orders, checkout, customer membership, store staff permissions, domain DNS verification, SSL provisioning, or storefront themes. Use the ITMOSOFT multitenancy package or application-level policies for data isolation. Domain verification must be implemented by the host application before setting is_verified to true. Unverified domains are not resolved by default.
A store may be associated with a tenant by an application-level integration. Store and tenant are deliberately separate concepts.
Testing
composer install
composer test
License
MIT. See LICENSE.