edalzell / laravel-features
Self-contained feature modules for Laravel with auto-registration of routes, migrations, views, events, and seeders
Requires
- php: ^8.3
- composer/composer: ^2.8
- edalzell/laravel-features-plugin: ^0.2
- illuminate/contracts: ^12.0 || ^13.0
Requires (Dev)
- brain/monkey: ^2.7
- larastan/larastan: ^3.0
- laravel/pint: ^1.14
- livewire/livewire: ^4.0
- nunomaduro/collision: ^8.8
- orchestra/testbench: ^10.0 || ^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-arch: ^4.0
- pestphp/pest-plugin-laravel: ^4.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- spatie/laravel-ray: ^1.40
Suggests
None
Provides
None
Conflicts
- livewire/livewire: <4.0
Replaces
None
This package is auto-updated.
Last update: 2026-11-11 00:18:56 UTC
README
Add self-contained features to your Laravel app or package, including all resources/routes/etc.
.
└── app/
...
└── features/
│ └── MyGreatFeature/
│ ├── config/
│ │ └── my-great-feature.php
│ ├── database/
│ │ ├── factories
│ │ ├── migrations
│ │ └── seeders
│ ├── lang
│ ├── resources
│ ├── routes
│ └── src/
│ ├── Models
│ ├── ...
│ └── ServiceProvider.php
Each feature behaves like a mini Laravel app. The following are auto-registered and booted:
| Phase | What |
|---|---|
| Register | Config, Migrations, Seeders, Translations, Views |
| Boot | Commands, Config publishing, Listeners, Policies, Routes, Seeders, View publishing, then any extensions — Livewire components ship as one |
Config and views are offered to vendor:publish as {slug}-config and {slug}-views; the views land in resources/views/vendor/{slug}, where Laravel already looks for overrides of the {slug}:: namespace.
Upgrade
1.x to 2.0
Edalzell\Features\Contracts\Extensioninterface is now an abstract classEdalzell\Features\Extensionwith no-op defaults. Only implement the methods you need.config/features.phpisn't used anymore, move any route group changes torouteGroups()(see Route groups), and deletefeatures.php.- A feature's
routeGroups()override now merges over the defaults instead of replacing them. One that returned only['api' => ...]used to dropweb; it now keeps it. Return'web' => nullto get the old behaviour.
Route groups
A feature's route files are put in a route group by filename, as the framework does for the app's own. Without it, loadRoutesFrom() is a bare require: no session or CSRF on web.php, no throttling or prefix on api.php.
| File | Group |
|---|---|
routes/web.php |
web middleware |
routes/api.php |
api middleware, api prefix |
| anything else | none |
Override routeGroups() on the feature's service provider to change a group. Entries merge over the defaults by key, so name only what changes. null removes a file's group; a closure or invokable class is handed the file's path and the Features instance and loads the file itself:
protected function routeGroups(): array { return [ 'api' => ['middleware' => ['api', 'auth:sanctum'], 'prefix' => 'api/internal'], 'admin' => fn (string $path) => Admin::routes(fn () => require $path), ]; }
To change a group for every feature, define routeGroups() on a tagged extension:
class ApiVersion extends Extension { public function routeGroups(): array { return ['api' => ['middleware' => 'api', 'prefix' => 'api/v1', 'as' => 'api.v1.']]; } }
Precedence, lowest to highest: defaults, extensions (last tagged wins), the feature's own routeGroups().
Livewire components
Class components go in src/Livewire; single- and multi-file components under resources/views, in livewire/ or pages/ as Livewire splits them for the app. The feature's slug is the Livewire namespace, and the directory becomes a dotted prefix:
MyGreatFeature/
├── resources/
│ └── views/
│ ├── livewire/
│ │ ├── greeting.blade.php -> <livewire:my-great-feature::livewire.greeting />
│ │ └── checklist/ -> <livewire:my-great-feature::livewire.checklist />
│ │ ├── checklist.php
│ │ └── checklist.blade.php
│ └── pages/
│ └── show.blade.php -> Route::livewire('show', 'my-great-feature::pages.show')
└── src/
└── Livewire/
├── PostList.php -> <livewire:my-great-feature::post-list />
└── Posts/
├── Index.php -> <livewire:my-great-feature::posts />
└── ShowPost.php -> <livewire:my-great-feature::posts.show-post />
Nothing is scanned: Livewire resolves a name the first time it is used. Change or drop the namespace through the feature's options:
protected function options(): array { return ['livewire.namespace' => '']; }
An empty string registers plain locations instead, so components answer to their bare names.
Full-page components
A feature routes one of its components as a full page from its own routes/web.php:
Route::livewire('posts/create', 'my-great-feature::create-post');
The page renders into the app's layout; #[Layout('my-great-feature::layout')] uses one from the feature's resources/views instead.
Needs Livewire 4. Livewire is not a dependency of this package; without it, nothing is registered.
Extensions
An extension autoloads what Laravel itself doesn't know about: Livewire components (built in, Edalzell\Features\Extensions\LivewireComponents), Statamic fieldtypes, and so on. Extend Edalzell\Features\Extension, tag it in your service provider's register(), and every feature hands itself over once its own Laravel pieces have booted:
use Edalzell\Features\Extension; use Edalzell\Features\Features; class StatamicExtensions extends Extension { public function boot(Features $features): void { // $features->rootPath(), rootNamespace(), slug(), app(), provider() // $features->has('src/Tags'), $features->pathTo('resources/blueprints') // $features->classes('Tags', Tags::class) // $features->option('statamic.something', $default) } } // in the package's service provider's register() $this->app->tag(StatamicExtensions::class, Extension::TAG);
A feature only sees extensions tagged before it boots. The tag resolves a fresh instance per feature unless you bind a singleton. Per-feature settings go through options() on the feature's service provider, keyed by dotted name; each extension reads its own. It is read at boot, after the feature's config is merged, so an option can depend on config(). An extension can also supply route groups.
Boot order
A feature is registered from inside its host's register(), so it boots before the host and before any package registered later. When the feature's own boot code must come after another provider's, put it in bootFeature() and name the provider to wait for:
use Edalzell\Features\Attributes\BootAfter; #[BootAfter(App\Providers\AppServiceProvider::class)] class ServiceProvider extends FeatureServiceProvider { protected function bootFeature(): void { $this->app['router']->pushMiddlewareToGroup('web', TrackVisits::class); } }
bootFeature() runs after the feature's conventions and the named provider's boot(). Naming a provider that isn't registered throws a LogicException. Overriding boot() still works, but it runs at the feature's own turn and can't wait.
Seeders
Every feature's database/seeders are collected into Edalzell\Features\Seeders; call it from the app's DatabaseSeeder to run them:
public function run(): void { $this->call(Seeders::class); }
They run in feature registration order. When one feature's data depends on another's, #[SeedAfter] names the seeders that must run first:
use Edalzell\Features\Attributes\SeedAfter; use Illuminate\Database\Seeder; #[SeedAfter(ListingSeeder::class)] class AvailabilitySeeder extends Seeder { public function run(): void { // ... } }
Registration order is the tiebreak. Naming a seeder outside the collected set is ignored for ordering. A cycle throws a LogicException naming the seeders involved.
Dependencies
A feature can't declare Composer dependencies of its own — it shares the app's vendor/ and lockfile, so there's nowhere for a feature's require to go. Add them to the app's composer.json, and list them in the feature's own README so it's clear which feature needs what, and nobody removes one as unused.
A feature that needs its own dependencies to travel with it — to be installed in several apps, say — should be a package instead.
Installation
You can install the package via composer:
composer require edalzell/laravel-features
Usage
To add a new feature in your app:
php artisan make:feature MyGreatFeature
To add feature to a package:
php artisan make:feature MyGreatFeature the-dev/my-package
This creates a ServiceProvider that extends FeatureServiceProvider — everything is auto-registered with no further code required.
Option 1: Extend FeatureServiceProvider
The zero-friction path. Your provider gets boot() and register() for free:
class MyGreatFeatureServiceProvider extends FeatureServiceProvider { // nothing needed — everything is auto-registered }
Override any of these protected methods to customise behaviour:
protected function bootFeature(): void // the feature's own boot code, after the conventions and any `#[BootAfter]` provider protected function configFileName(): string // default: kebab-cased feature name protected function configGroup(): string // default: package short name for package features, else none; merged at `{group}.{file}` protected function configPublishHandle(): string // default: kebab-cased feature name protected function publishesConfig(): bool // default: true unless `registerFeatures(publishesConfig: false)`; false still merges protected function featuresPath(): string // default: derived from the provider's own location protected function options(): array // default: []; settings for extensions, e.g. ['livewire.namespace' => ''] protected function routeGroups(): array // default: []; merged over the package defaults and any extension's groups
Option 2: Standalone Features object
When your provider already extends another class, wire up Features directly:
use Edalzell\Features\Features; class MyServiceProvider extends SomeOtherProvider { private Features $features; public function __construct(Application $app) { parent::__construct($app); $this->features = (new Features($this)) ->path($this->featuresPath()) ->name($this->name()) ->configFileName($this->configFileName()) ->configGroup($this->configGroup()) ->configPublishHandle($this->configPublishHandle()); } public function boot(): void { $this->features->options($this->options())->bootFeature(); } public function register(): void { $this->features->registerFeature(); } }
Features derives the path, namespace, and app from your provider via reflection. You only need to call the fluent setters when overriding the defaults.
Auto-discovering features
The HasFeatures trait registers every feature in a directory. In an app, add it to AppServiceProvider:
use Edalzell\Features\Concerns\HasFeatures; class AppServiceProvider extends ServiceProvider { use HasFeatures; public function register(): void { $this->registerFeatures(app_path('../features'), 'App\\Features'); } }
For a package, add it to your package's main service provider:
use Edalzell\Features\Concerns\HasFeatures; class MyPackageServiceProvider extends ServiceProvider { use HasFeatures; public function register(): void { $this->registerFeatures(); } }
In a package, registerFeatures() defaults to <package-root>/features/ and YourPackage\Features\FeatureName\ServiceProvider. Pass arguments to override either:
$this->registerFeatures('/path/to/features', 'My\\Namespace\\Features');
Where a package feature's config lives
A package feature's config is merged at {group}.{file}, the group being the package's Composer short name: the-dev/my-package + features/Maps/config/maps.php reads as config('my-package.maps.…'). A site overrides it in one of two places:
| Convention | Site overrides in | registerFeatures() |
|---|---|---|
| A directory per package | config/my-package/maps.php |
default |
| Nested in the package's own config | config/my-package.php under a maps key |
registerFeatures(publishesConfig: false) |
publishesConfig: false only skips vendor:publish; the defaults are still merged. Pick one: if a site has both files, Laravel loads the nested one last and it replaces the whole maps key.
Looking up registered features
registerFeatures() records each feature in FeatureRegistry, for when code outside the feature needs its path or namespace:
use Edalzell\Features\Feature; use Edalzell\Features\FeatureRegistry; app(FeatureRegistry::class) ->all() ->filter(fn (Feature $feature) => $feature->has('src/Setup')) ->each(function (Feature $feature) { $feature->path('src/Setup'); // absolute path $feature->namespace('Setup'); // App\Features\Mail\Setup });
path() and namespace() with no argument return the feature root; has() checks a relative path exists. FeatureRegistry::add() records a feature without registering its provider, for tests.
Finding classes in a feature
Commands, policies, listeners and seeders are found by scanning a directory for the classes its files declare. The same scan works for any directory under src/, so a convention of your own needs no second one:
use Edalzell\Features\FeatureRegistry; app(FeatureRegistry::class) ->classes('Setup', Writer::class) ->each(fn (string $writer) => $writer::run());
classes() is on FeatureRegistry for every feature, on Feature for one, and on Features inside a provider or extension. The directory is relative to src/, searched recursively, sorted by path; depth stops sooner (0 is the directory itself). A base class keeps only concrete classes that extend or implement it; without one every declared class is returned and nothing is autoloaded.
Features outside the app
A feature can live outside the app entirely, as in a monorepo where two apps share one set:
gym/
├── apps/
│ ├── server/
│ └── mobile/
└── shared/
└── features/
└── Scheduling/
Each app wires two things. Autoloading, in composer.json, where the plugin generates PSR-4 entries for every feature it finds:
"extra": { "laravel-features": { "paths": { "../../shared/features": "Shared\\Features" } } }
And registration, pointing registerFeatures() at the same directory:
$this->registerFeatures(base_path('../../shared/features'), 'Shared\\Features');
The app's own features/ directory is still scanned.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
License
The MIT License (MIT). Please see License File for more information.