Laravel Modules

https://github.com/mozex/laravel-modules
Admin
Full-featured module system for Laravel — auto-discovery, isolated tests, Livewire & Filament...
Tokens:71,427
Snippets:587
Trust Score:8.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run Install Command: php artisan modules:install

Source: https://github.com/mozex/laravel-modules/blob/main/README.md

Optionally publish config/modules.php to change defaults.

```bash
php artisan modules:install
```

--------------------------------

### Example migration file

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/migrations.md

Example migration file for creating a posts table. Write migrations exactly as you would in database/migrations/.

```php
// Modules/Blog/Database/Migrations/2024_01_10_100000_create_posts_table.php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('body');
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};
```

--------------------------------

### Web routes example

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/routes.md

Example of a standard web route file for a module. Uses the web middleware group and defines GET routes for blog posts.

```php
// Modules/Blog/Routes/web.php
use Illuminate\Support\Facades\Route;

Route::get('/blog', [PostController::class, 'index']);
Route::get('/blog/{post}', [PostController::class, 'show']);
```

--------------------------------

### API routes example

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/routes.md

Example of a standard API route file for a module. These routes get the /api prefix automatically, so the endpoints become /api/posts and /api/posts.

```php
// Modules/Blog/Routes/api.php
use Illuminate\Support\Facades\Route;

Route::get('/posts', [PostApiController::class, 'index']);
Route::post('/posts', [PostApiController::class, 'store']);
```

--------------------------------

### Example console.php route file

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/routes.md

Defines an Artisan command and a scheduled task using the Schedule facade.

```php
// Modules/Blog/Routes/console.php
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Schedule;

Artisan::command('blog:cleanup', function () {
    // Clean up old draft posts
});

Schedule::command('blog:cleanup')->daily();
```

--------------------------------

### Example fortify.php route file

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/routes.md

Defines a route group with Fortify middleware and prefix, including a Livewire login route.

```php
// Modules/User/Routes/fortify.php
Route::group([
    'middleware' => config('fortify.middleware', ['web']),
    'prefix' => 'dashboard',
], function () {
    Route::livewire('/login', Login::class)
        ->middleware(['guest:'.config('fortify.guard')])
        ->name('login');
    // ...
});
```

--------------------------------

### Define Module Route

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Example of a route file that returns a view from the blog namespace.

```php
use Illuminate\Support\Facades\Route;
use Modules\Blog\Models\Post;

Route::get('/blog', function () {
    return view('blog::index', ['posts' => Post::all()]);
});
```

--------------------------------

### Writing a module service provider

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/service-providers.md

Example of a module service provider extending Illuminate\Support\ServiceProvider, with register() for container bindings and boot() for boot logic.

```php
namespace Modules\Blog\Providers;

use Illuminate\Support\ServiceProvider;
use Modules\Blog\Services\PostRepository;
use Modules\Blog\Contracts\PostRepositoryInterface;

class BlogServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(PostRepositoryInterface::class, PostRepository::class);
    }

    public function boot(): void
    {
        // Additional boot logic specific to this module
    }
}
```

--------------------------------

### Example directory structure for Routes folder

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/routes.md

Shows a possible file layout for a User module with separate route files for Fortify, Jetstream, and web routes.

```text
Modules/User/
└── Routes/
    ├── fortify.php    // Fortify login, registration, password reset routes
    ├── jetstream.php  // Jetstream team management routes
    └── web.php        // the module's own public routes
```

--------------------------------

### Example directory tree for a module's Filament structure

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/filament.md

Shows the expected directory layout for a module's Filament components. The package discovers components based on the outer pattern `Filament/{Panel}/{Resources|Pages|Widgets|Clusters}/`. The internal structure of resources is flexible; the example uses the newer `Pages`, `Schemas`, and `Tables` subdirectories, but a flatter layout with `form()` and `table()` methods also works.

```text
Modules/Blog/
└── Filament/
    ├── Admin/
    │   ├── Resources/
    │   │   └── Posts/
    │   │       ├── PostResource.php
    │   │       ├── Pages/
    │   │       │   ├── CreatePost.php
    │   │       │   ├── EditPost.php
    │   │       │   └── ListPosts.php
    │   │       ├── Schemas/
    │   │       │   └── PostForm.php
    │   │       └── Tables/
    │   │           └── PostsTable.php
    │   ├── Pages/
    │   │   └── BlogSettings.php
    │   └── Widgets/
    │       └── PostStatsWidget.php
    └── Dashboard/
        └── Widgets/
            └── RecentPostsWidget.php
```

--------------------------------

### Get module and base paths with Modules facade

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Use the Modules facade to retrieve absolute paths to the modules directory, a specific location within modules, or the project base path with an optional suffix. The examples show expected return values for each call.

```php
use Mozex\Modules\Facades\Modules;

// Absolute path to the modules directory
Modules::modulesPath();
// e.g., /var/www/app/Modules

// Path to a specific location within modules
Modules::modulesPath('Blog/Config');
// e.g., /var/www/app/Modules/Blog/Config

// Project base path with optional suffix
Modules::basePath('storage');
// e.g., /var/www/app/storage
```

--------------------------------

### Directory layout for Nova resources

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/nova-resources.md

Example directory structure showing where Nova resource classes should be placed in modules.

```text
Modules/Blog/
└── Nova/
    ├── Post.php
    └── Category.php

Modules/Shop/
└── Nova/
    ├── Product.php
    └── Order.php
```

--------------------------------

### Run the module command

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/commands.md

Bash commands to execute the example command normally or with the --dry-run option.

```bash
php artisan blog:publish-posts
php artisan blog:publish-posts --dry-run
```

--------------------------------

### Directory layout for modules with Events and Listeners

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/events-listeners.md

Example directory structure showing events and listeners, including nested subdirectories like Analytics and Notifications.

```text
Modules/Blog/
├── Events/
│   ├── PostPublished.php
│   └── PostDeleted.php
└── Listeners/
    ├── NotifyFollowers.php
    └── Analytics/
        └── TrackPageView.php

Modules/Shop/
├── Events/
│   └── OrderPlaced.php
└── Listeners/
    ├── SendReceipt.php
    ├── UpdateInventory.php
    └── Notifications/
        └── NotifyWarehouse.php
```

--------------------------------

### Example module config file

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/configs.md

A standard Laravel config file that returns an array of configuration values.

```php
// Modules/Blog/Config/blog.php
return [
    'posts_per_page' => 15,
    'allow_comments' => true,
    'cache_ttl' => 3600,
];
```

--------------------------------

### Example Pest test for a module

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/pest.md

Shows how to write Pest tests in a module, using factories and assertions.

```php
// Modules/Blog/Tests/Feature/PostTest.php

use Modules\Blog\Models\Post;

it('can list published posts', function () {
    Post::factory()->published()->count(3)->create();
    Post::factory()->draft()->create();

    $response = $this->get('/blog');

    $response->assertOk();
    $response->assertViewHas('posts', fn ($posts) => $posts->count() === 3);
});

it('can view a single post', function () {
    $post = Post::factory()->published()->create();

    $response = $this->get("/blog/{$post->slug}");

    $response->assertOk();
    $response->assertSee($post->title);
});
```

--------------------------------

### Define Module Model

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Example of a model class using the Modules\Blog namespace.

```php
namespace Modules\Blog\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    protected $fillable = ['title', 'body'];
}
```

--------------------------------

### Install with Composer: composer require mozex/laravel-modules

Source: https://github.com/mozex/laravel-modules/blob/main/README.md

Install the package via Composer. Requires PHP 8.3 or higher.

```bash
composer require mozex/laravel-modules
```

--------------------------------

### Directory layout for helper files

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/helpers.md

Illustrates the expected directory structure for helper files within modules, with examples for Blog and Shop modules.

```text
Modules/Blog/
└── Helpers/
    ├── formatting.php
    └── strings.php

Modules/Shop/
└── Helpers/
    └── pricing.php
```

--------------------------------

### Example output of modules:list

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/listing.md

Shows the expected output format. Each module header indicates enabled/disabled status and order number, followed by a table of asset types with counts. Disabled modules show 'No assets discovered'.

```text
  Shared [Enabled | Order: 1]
  +---------------------+-------+
  | Asset               | Count |
  +---------------------+-------+
  | Helpers             | 3     |
  | Service Providers   | 1     |
  | Configs             | 2     |
  +---------------------+-------+

  Blog [Enabled | Order: 2]
  +---------------------+-------+
  | Asset               | Count |
  +---------------------+-------+
  | Commands            | 1     |
  | Migrations          | 4     |
  | Views               | 8     |
  | Routes              | 2     |
  | Blade Components    | 3     |
  +---------------------+-------+

  Legacy [Disabled]
  No assets discovered
```

--------------------------------

### JSON translation file example

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/translations.md

Example of a JSON translation file for French, mapping original strings to translations.

```json
{
    "Read more": "Lire la suite",
    "Published on :date": "Publié le :date"
}
```

--------------------------------

### PHP array translation file example

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/translations.md

Example of a PHP translation file returning an associative array with keys and values.

```php
// Modules/Blog/Lang/en/messages.php
return [
    'welcome' => 'Welcome to the blog',
    'post_created' => 'Your post ":title" has been published.',
    'comments' => '{0} No comments|{1} :count comment|[2,*] :count comments',
];
```

--------------------------------

### Module command directory layout

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/commands.md

Example directory structure showing where module commands are placed. Files extending Command are discovered, while abstract base classes are ignored.

```text
Modules/Blog/
└── Console/
    └── Commands/
        ├── PublishPosts.php          // discovered (extends Command)
        ├── PruneDrafts.php           // discovered (extends Command)
        └── BaseCommand.php           // ignored (abstract class)
```

--------------------------------

### Access Module View

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Example of a Blade view file located within the module resources.

```blade
{{-- Modules/Blog/Resources/views/index.blade.php --}}
@foreach($posts as $post)
    <h2>{{ $post->title }}</h2>
    <p>{{ $post->body }}</p>
@endforeach
```

--------------------------------

### Example module command class

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/commands.md

A complete Artisan command class with signature, description, and handle method. Uses the --dry-run option to preview without changes, and returns self::SUCCESS.

```php
namespace Modules\Blog\Console\Commands;

use Illuminate\Console\Command;

class PublishPosts extends Command
{
    protected $signature = 'blog:publish-posts
                            {--dry-run : Show what would be published without making changes}';

    protected $description = 'Publish all scheduled posts that are past their publish date';

    public function handle(): int
    {
        $query = Post::where('publish_at', '<=', now())
            ->where('status', 'draft');

        if ($this->option('dry-run')) {
            $this->info("Would publish {$query->count()} posts.");
            return self::SUCCESS;
        }

        $count = $query->update(['status' => 'published']);
        $this->info("Published {$count} posts.");

        return self::SUCCESS;
    }
}
```

--------------------------------

### Example helper file with function_exists guards

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/helpers.md

Shows a complete helper file defining two functions, each wrapped in function_exists() to prevent redeclaration errors.

```php
// Modules/Blog/Helpers/formatting.php

if (! function_exists('format_reading_time')) {
    function format_reading_time(string $text): string
    {
        $words = str_word_count(strip_tags($text));
        $minutes = max(1, (int) ceil($words / 200));

        return "{$minutes} min read";
    }
}

if (! function_exists('excerpt')) {
    function excerpt(string $text, int $limit = 150): string
    {
        return Str::limit(strip_tags($text), $limit);
    }
}
```

--------------------------------

### Usage examples for module model factories

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/models-factories.md

Demonstrates calling factory() on module models: creating a single instance, creating multiple with state, and creating with relationships. Requires the module model to be imported.

```php
use Modules\Blog\Models\Post;

// Create a single instance
$post = Post::factory()->create();

// Create multiple with state
$posts = Post::factory()
    ->count(10)
    ->published()
    ->create();

// With relationships
$post = Post::factory()
    ->has(Comment::factory()->count(3))
    ->create();
```

--------------------------------

### Real-world example: User module service provider

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/service-providers.md

A complete service provider for a User module that enforces a morph map and registers policies for Spatie Permission models. It demonstrates using Relation::enforceMorphMap() and Gate::policy() in boot().

```php
namespace Modules\User\Providers;

use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\ServiceProvider;
use Modules\User\Models\EmployeeTeam;
use Modules\User\Models\User;
use Modules\User\Policies\PermissionPolicy;
use Modules\User\Policies\RolePolicy;
use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;

class UserServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Relation::enforceMorphMap([
            'user' => User::class,
            'employee-team' => EmployeeTeam::class,
            'role' => Role::class,
            'permission' => Permission::class,
        ]);

        Gate::policy(Role::class, RolePolicy::class);
        Gate::policy(Permission::class, PermissionPolicy::class);
    }
}
```

--------------------------------

### Listener example: Modules\Blog\Listeners\NotifyFollowers with handle()

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/events-listeners.md

Listener class with a handle() method type-hinting the PostPublished event, demonstrating auto-discovery. Notifies the author's followers.

```php
namespace Modules\Blog\Listeners;

use Modules\Blog\Events\PostPublished;

class NotifyFollowers
{
    public function handle(PostPublished $event): void
    {
        // Send notifications to the post author's followers
        $event->post->author->followers->each(function ($follower) use ($event) {
            $follower->notify(new NewPostNotification($event->post));
        });
    }
}
```

--------------------------------

### Single-file component (SFC) example

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/livewire-components.md

Place this in a .blade.php file under the module's view_path. It defines a Livewire component with a count property and increment method, and renders a button that triggers the increment action.

```blade
{{-- Modules/Blog/Resources/views/livewire/counter.blade.php --}}
<?php

use Livewire\Component;

new class extends Component {
    public int $count = 0;

    public function increment(): void
    {
        $this->count++;
    }
};
?>

<div>
    <span>Count: {{ $count }}</span>
    <button wire:click="increment">+</button>
</div>
```

--------------------------------

### Directory layout for Blade components

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/blade-components.md

Example directory structure showing where component classes reside and the resulting aliases. Nested directories become dot-separated aliases.

```text
Modules/Blog/
└── View/
    └── Components/
        ├── Card.php              // <x-blog::card />
        ├── Filter.php            // <x-blog::filter />
        └── Post/
            ├── Card.php          // <x-blog::post.card />
            └── Summary.php       // <x-blog::post.summary />
```

--------------------------------

### Example Nova resource class in module

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/nova-resources.md

Standard Nova resource class with the module namespace. It uses the model, title, search, and fields method. The resource is automatically discovered and appears in the Nova sidebar.

```php
namespace Modules\Blog\Nova;

use Laravel\Nova\Resource;
use Laravel\Nova\Fields\ID;
use Laravel\Nova\Fields\Text;
use Laravel\Nova\Fields\Markdown;
use Laravel\Nova\Http\Requests\NovaRequest;
use Modules\Blog\Models\Post;

class Post extends Resource
{
    public static $model = Post::class;

    public static $title = 'title';

    public static $search = ['id', 'title'];

    public function fields(NovaRequest $request): array
    {
        return [
            ID::make()->sortable(),
            Text::make('Title')->sortable()->rules('required'),
            Markdown::make('Body')->rules('required'),
        ];
    }
}
```

--------------------------------

### Example module policy class

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/policies.md

Shows a typical module policy class with view, update, and delete methods. The update and delete methods check that the user's ID matches the post's author_id.

```php
namespace Modules\Blog\Policies;

use Modules\Blog\Models\Post;
use App\Models\User;

class PostPolicy
{
    public function view(User $user, Post $post): bool
    {
        return true;
    }

    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->author_id;
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->author_id;
    }
}
```

--------------------------------

### Cross-module translation access

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/translations.md

Shows how one module can reference another module's translations, using a Shared module as an example.

```php
// In a Shop module controller, using a Shared module's translations
__('shared::common.save')
__('shared::common.cancel')
```

--------------------------------

### Event class example: Modules\Blog\Events\PostPublished

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/events-listeners.md

Plain PHP class for an event, with no special base class or interface. Uses constructor property promotion to hold the Post instance.

```php
namespace Modules\Blog\Events;

class PostPublished
{
    public function __construct(
        public Post $post,
    ) {}
}
```

--------------------------------

### Custom modules directory glob pattern

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/phpstan.md

If you changed modules_directory in the package config, update the glob patterns to match. This example shows how to include modules from src/Domains/ instead of the default Modules/ directory.

```php
// If modules live in src/Domains/
...glob(__DIR__ . '/src/Domains/*', GLOB_ONLYDIR),
```

--------------------------------

### Example Blade component class

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/blade-components.md

A class-based component extending Illuminate\View\Component. Accepts data via constructor and returns a view from render().

```php
namespace Modules\Blog\View\Components;

use Illuminate\View\Component;

class Card extends Component
{
    public function __construct(
        public string $title,
        public string $excerpt,
        public ?string $image = null,
    ) {}

    public function render()
    {
        return view('blog::components.card');
    }
}
```

--------------------------------

### Directory layout for module with Livewire components

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/livewire-components.md

Shows the recommended directory structure for a module using class-based, single-file, and multi-file Livewire components.

```text
Modules/Blog/
├── Livewire/
│   ├── PostEditor.php                         // Class-based
│   └── Comments/
│       └── CommentList.php                    // Nested class-based
└── Resources/
    └── views/
        └── livewire/
            ├── post-editor.blade.php          // View for PostEditor
            ├── counter.blade.php              // SFC
            ├── toggle/                        // MFC
            │   ├── toggle.php
            │   └── toggle.blade.php
            └── comments/
                └── comment-list.blade.php     // View for CommentList
```

--------------------------------

### Directory layout for module models and policies

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/policies.md

Illustrates the expected directory structure for module models and policies, showing nested subdirectories for both.

```text
Modules/Blog/
├── Models/
│   ├── Post.php
│   └── Comments/
│       └── Comment.php
└── Policies/
    ├── PostPolicy.php
    └── Comments/
        └── CommentPolicy.php
```

--------------------------------

### Calling helper functions after discovery

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/helpers.md

Demonstrates how to call the defined helper functions anywhere in the application after they are loaded.

```php
$readTime = format_reading_time($post->body);
$summary = excerpt($post->body, 200);
```

--------------------------------

### Directory layout for module models and factories

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/models-factories.md

Illustrates the expected directory structure under a module (e.g., Modules/Blog) with Models and Database/Factories subdirectories, including nested Comments subdirectory.

```text
Modules/Blog/
├── Models/
│   ├── Post.php
│   ├── Tag.php
│   └── Comments/
│       └── Comment.php
└── Database/
    └── Factories/
        ├── PostFactory.php
        ├── TagFactory.php
        └── Comments/
            └── CommentFactory.php
```

--------------------------------

### Build all caches with php artisan optimize

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/caching.md

Builds the module cache along with config, events, routes, and views. If your deploy script already runs optimize, you're covered.

```bash
php artisan optimize
```

--------------------------------

### Custom modules directory path in phpunit.xml

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/phpunit.md

If the 'modules_directory' configuration is changed, update the test suite directory path accordingly. This example uses './src/Domains/*/Tests'.

```xml
<directory>./src/Domains/*/Tests</directory>
```

--------------------------------

### Get all module seeder classes

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Retrieve all discovered module seeder classes using the Modules facade. The method returns an array of fully-qualified class names.

```php
// Get all discovered module seeder classes
Modules::seeders();
// returns ['Modules\Blog\Database\Seeders\BlogDatabaseSeeder', ...]
```

--------------------------------

### Accessing module config values

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/configs.md

Shows how to retrieve the module config values using the config() helper.

```php
config('blog.posts_per_page');  // 15
config('blog.allow_comments');  // true
```

--------------------------------

### Module Directory Structure

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

The standard directory layout for a new module named Blog.

```text
Modules/
└── Blog/
    ├── Models/
    │   └── Post.php
    ├── Resources/
    │   └── views/
    │       └── index.blade.php
    └── Routes/
        └── web.php
```

--------------------------------

### Generate PHPStan baseline

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/phpstan.md

Run the baseline composer script to generate phpstan-baseline.php. This suppresses existing issues so you can start fresh. The script appends baseline flags to the test:types command.

```bash
composer baseline
```

--------------------------------

### Running seeders via artisan commands

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/seeders.md

Commands to run all seeders, a specific module seeder, or fresh migrate with seed. Use --class to target a specific seeder.

```bash
# Run all seeders (app + modules)
php artisan db:seed

# Run a specific module seeder
php artisan db:seed --class="Modules\Blog\Database\Seeders\BlogDatabaseSeeder"

# Fresh migrate + seed
php artisan migrate:fresh --seed
```

--------------------------------

### Run all module migrations

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/migrations.md

Standard artisan commands to run, rollback, and fresh migrations across all modules.

```bash
# Run all pending migrations (app + all modules)
php artisan migrate

# Roll back the last batch
php artisan migrate:rollback

# Reset and re-run all migrations
php artisan migrate:fresh
```

--------------------------------

### Default helpers configuration

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/helpers.md

Shows the default 'helpers' configuration array with 'active' flag and 'patterns' for discovering helper files.

```php
'helpers' => [
    'active' => true,
    'patterns' => [
        '*/Helpers/*.php',
    ],
],
```

--------------------------------

### Define props in anonymous Blade component

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/views.md

Defining props at the top of an anonymous component file, just like any Laravel anonymous component. This example shows the alert component with a default type and required message.

```blade
{{-- Modules/Blog/Resources/views/components/alert.blade.php --}}
@props(['type' => 'info', 'message'])

<div class="alert alert-{{ $type }}">
    {{ $message }}
</div>
```

--------------------------------

### Config: listeners.active and patterns

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/events-listeners.md

Default configuration to enable listener discovery and set the scan pattern for module Listeners directories.

```php
'listeners' => [
    'active' => true,
    'patterns' => [
        '*/Listeners',
    ],
],
```

--------------------------------

### Module Directory Structure

Source: https://github.com/mozex/laravel-modules/blob/main/README.md

Minimal module structure with a route and a view.

```text
Modules/
└── Blog/
    ├── Routes/
    │   └── web.php
    └── Resources/
        └── views/
            └── index.blade.php
```

--------------------------------

### Run modules:list Artisan command

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/listing.md

Use this command to display every module with its status, load order, and asset counts. The output is grouped by module and sorted by load order.

```bash
php artisan modules:list
```

--------------------------------

### React module directory structure

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/inertia.md

Shows the identical structure for React, with .tsx files and the Composable/ directory replaced by Hooks/.

```text
Modules/Blog/Resources/ts/
├── Pages/
│   ├── Post/
│   │   ├── Index.tsx
│   │   └── Show.tsx
│   └── Home.tsx
├── Layouts/
├── Components/
├── Hooks/       (React hooks: useX.ts)
├── Icons/
├── Interfaces/
└── Stores/      (Zustand/Redux stores)
```

--------------------------------

### React Inertia page resolver with @Modules/ prefix

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/inertia.md

Use this resolver in a React app to support module-scoped Inertia pages. It uses two import.meta.glob calls to bundle application and module pages, and resolves names starting with @Modules/ to the correct module path. Application pages are referenced normally, while module pages use the @Modules/{Module}/{Path} format.

```tsx
// resources/ts/app.tsx
import type { ResolvedComponent } from '@inertiajs/react';
import { createInertiaApp } from '@inertiajs/react';
import { createRoot } from 'react-dom/client';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

type Glob = Record<string, () => Promise<ResolvedComponent>>;

const appPages = import.meta.glob<ResolvedComponent>('./Pages/**/*.tsx');
const modulePages = import.meta.glob<ResolvedComponent>('../../Modules/**/Resources/ts/Pages/**/*.tsx');

function resolveInertiaPage(name: string): [string, Glob] {
    if (name.startsWith('@Modules/')) {
        const withoutPrefix = name.replace('@Modules/', '');
        const module = withoutPrefix.substring(0, withoutPrefix.indexOf('/'));
        const pagePath = withoutPrefix.slice(module.length + 1);

        return [
            `../../Modules/${module}/Resources/ts/Pages/${pagePath}.tsx`,
            modulePages,
        ];
    }

    return [`./Pages/${name}.tsx`, appPages];
}

createInertiaApp({
    resolve: (name) => resolvePageComponent(...resolveInertiaPage(name)),
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />);
    },
});
```

--------------------------------

### Vue Inertia page resolver with @Modules/ prefix

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/inertia.md

Use this resolver in a Vue app to support module-scoped Inertia pages. It uses two import.meta.glob calls to bundle application and module pages, and resolves names starting with @Modules/ to the correct module path. Application pages are referenced normally, while module pages use the @Modules/{Module}/{Path} format.

```ts
// resources/ts/app.ts
import type { DefineComponent } from 'vue';
import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

type Glob = Record<string, () => Promise<DefineComponent>>;

const appPages = import.meta.glob<DefineComponent>('./Pages/**/*.vue');
const modulePages = import.meta.glob<DefineComponent>('../../Modules/**/Resources/ts/Pages/**/*.vue');

function resolveInertiaPage(name: string): [string, Glob] {
    if (name.startsWith('@Modules/')) {
        const withoutPrefix = name.replace('@Modules/', '');
        const module = withoutPrefix.substring(0, withoutPrefix.indexOf('/'));
        const pagePath = withoutPrefix.slice(module.length + 1);

        return [
            `../../Modules/${module}/Resources/ts/Pages/${pagePath}.vue`,
            modulePages,
        ];
    }

    return [`./Pages/${name}.vue`, appPages];
}

createInertiaApp({
    resolve: (name) => resolvePageComponent(...resolveInertiaPage(name)),
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) }).use(plugin).mount(el);
    },
});
```

--------------------------------

### Default Livewire components configuration

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/livewire-components.md

Configuration array for enabling Livewire components, setting discovery patterns for class-based components, and the view path for SFC/MFC components.

```php
'livewire-components' => [
    'active' => true,
    'patterns' => [
        '*/Livewire',
    ],
    'view_path' => 'Resources/views/livewire',
],
```

--------------------------------

### Render module views with namespace::path

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/views.md

Rendering views using the namespace::path syntax. Dots replace directory separators; blog::pages.show resolves to Modules/Blog/Resources/views/pages/show.blade.php.

```php
// In a controller
return view('blog::home');
return view('blog::pages.show', ['post' => $post]);

// In a route closure
Route::get('/blog', fn () => view('blog::pages.index'));
```

--------------------------------

### Reset cache driver factory to default

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/caching.md

Pass null to use the default file-backed driver again. If you swap the factory after the package has booted, call BaseScout::clearInstances() so scout singletons pick up the new driver on their next access.

```php
BaseScout::useCacheDriverFactory(null);
```

--------------------------------

### Define Module Route: Route::get('/blog', fn () => view('blog::index'))

Source: https://github.com/mozex/laravel-modules/blob/main/README.md

Route file works like any Laravel route file. The route loads with the 'web' middleware group because the file is named web.php, and the view is accessible via the 'blog::' namespace.

```php
use Illuminate\Support\Facades\Route;

Route::get('/blog', fn () => view('blog::index'));
```

--------------------------------

### Default nova-resources configuration

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/nova-resources.md

Configuration array for enabling Nova resource discovery. Set 'active' to false to disable, or adjust 'patterns' to change the directory pattern.

```php
'nova-resources' => [
    'active' => true,
    'patterns' => [
        '*/Nova',
    ],
],
```

--------------------------------

### Directory layout for Lang/

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/translations.md

Shows the standard directory structure for module translations, with locale subdirectories and JSON files.

```text
Modules/Blog/
└── Lang/
    ├── en/
    │   ├── messages.php
    │   └── validation.php
    ├── fr/
    │   ├── messages.php
    │   └── validation.php
    └── fr.json
```

--------------------------------

### Directory layout for module configs

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/configs.md

Shows the expected directory structure for module config files.

```text
Modules/Blog/
└── Config/
    └── blog.php

Modules/Shop/
└── Config/
    ├── shop.php
    └── app.php      // merges with Laravel's config/app.php
```

--------------------------------

### Register baseline in PHPStan config

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/phpstan.md

Add the generated baseline file to the includes array. Only add this line after the baseline exists; otherwise PHPStan fails at startup because the file is missing.

```php
return [
    'includes' => [
        './vendor/larastan/larastan/extension.neon',
        './phpstan-baseline.php',
    ],
    // ...
];
```

--------------------------------

### Default routes configuration

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/routes.md

Default configuration for route discovery. The 'active' key enables route loading, 'patterns' defines the file pattern, and 'commands_filenames' and 'channels_filenames' specify filenames for console and channel routes.

```php
'routes' => [
    'active' => true,
    'patterns' => [
        '*/Routes/*.php',
    ],
    'commands_filenames' => [
        'console',
    ],
    'channels_filenames' => [
        'channels',
    ],
],
```

--------------------------------

### Default configuration for models and factories

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/models-factories.md

Shows the default 'models' and 'factories' configuration arrays with 'active' flags and namespace settings. These settings enable the custom guessing callbacks and define the expected sub-namespaces.

```php
'models' => [
    'active' => true,
    'namespace' => 'Models\\',
],

'factories' => [
    'active' => true,
    'namespace' => 'Database\\Factories\\',
],
```

--------------------------------

### Configure auto-discovery for modules in typescript-transformer.php

Source: https://github.com/mozex/laravel-modules/blob/main/docs/integrations/inertia.md

PHP configuration for spatie/laravel-typescript-transformer to include module paths. Add this to config/typescript-transformer.php so the transformer discovers types in the Modules directory.

```php
// config/typescript-transformer.php
return [
    'auto_discover_types' => [
        app_path(),
        base_path('Modules/*'),
    ],
    // ...
];
```

--------------------------------

### Using the Livewire component in a template

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/livewire-components.md

Blade syntax to include the PostEditor component with a post parameter.

```blade
<livewire:blog::post-editor :post="$post" />
```

--------------------------------

### Modules Facade Methods

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Code snippets for the Modules facade methods.

```APIDOC
## Modules::modulesPath()

### Description
Returns the absolute path to the modules directory, optionally with a suffix appended.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **suffix** (string) - Optional - A path suffix to append to the modules directory path.

### Request Example
```php
Modules::modulesPath();
Modules::modulesPath('Blog/Config');
```

### Response
#### Success Response
- **string** - The absolute path to the modules directory or the specified subpath.

#### Response Example
```php
'/var/www/app/Modules'
'/var/www/app/Modules/Blog/Config'
```
```

```APIDOC
## Modules::basePath()

### Description
Returns the project base path with an optional suffix.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **suffix** (string) - Optional - A path suffix to append to the base path.

### Request Example
```php
Modules::basePath('storage');
```

### Response
#### Success Response
- **string** - The project base path with the suffix appended.

#### Response Example
```php
'/var/www/app/storage'
```
```

```APIDOC
## Modules::moduleNameFromNamespace()

### Description
Extracts the module name from a fully-qualified class name.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **namespace** (string) - Required - The fully-qualified class name.

### Request Example
```php
Modules::moduleNameFromNamespace('Modules\\Blog\\Models\\Post');
```

### Response
#### Success Response
- **string** - The module name.

#### Response Example
```php
'Blog'
```
```

```APIDOC
## Modules::moduleNameFromPath()

### Description
Extracts the module name from a file path.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **path** (string) - Required - The file path.

### Request Example
```php
Modules::moduleNameFromPath('/var/www/app/Modules/Blog/Models/Post.php');
```

### Response
#### Success Response
- **string** - The module name.

#### Response Example
```php
'Blog'
```
```

```APIDOC
## Modules::seeders()

### Description
Returns all discovered module seeder classes.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
Modules::seeders();
```

### Response
#### Success Response
- **array** - An array of seeder class names.

#### Response Example
```php
['Modules\\Blog\\Database\\Seeders\\BlogDatabaseSeeder', ...]
```
```

```APIDOC
## Modules::routeGroup()

### Description
Defines a new route group for discovering custom route files in modules. The group name must match the filename. Once defined, any module's route file with that name will be loaded with the specified attributes.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The route group name (must match the route file name).
- **prefix** (string|Closure) - Optional - The route prefix. Can be a closure for lazy evaluation.
- **middleware** (array) - Optional - Middleware to apply to the group.
- **as** (string) - Optional - Route name prefix.

### Request Example
```php
Modules::routeGroup('admin',
    prefix: 'admin',
    middleware: ['web', 'auth', 'is-admin'],
    as: 'admin.',
);

Modules::routeGroup('api',
    prefix: fn () => config('app.api_prefix', 'api'),
    middleware: ['api'],
);
```

### Response
#### Success Response
No return value (void).
```

```APIDOC
## Modules::registerRoutesUsing()

### Description
Registers a custom route registration closure for a specific route group. The closure receives the group's attributes and the route file and can wrap them in custom logic.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The route group name.
- **callback** (Closure) - Required - A closure that receives `array $attributes` and `$routes` and handles route registration.

### Request Example
```php
Modules::registerRoutesUsing('localized', function (array $attributes, $routes) {
    Route::localized(fn () => Route::group($attributes, $routes));
});
```

### Response
#### Success Response
No return value (void).
```

--------------------------------

### Directory layout for module providers

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/service-providers.md

Shows the expected directory structure for a module's Providers directory, containing BlogServiceProvider.php, EventServiceProvider.php, and RouteServiceProvider.php.

```text
Modules/Blog/
└── Providers/
    ├── BlogServiceProvider.php
    ├── EventServiceProvider.php
    └── RouteServiceProvider.php
```

--------------------------------

### Custom namespace configuration for models and policies

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/policies.md

Shows how to configure custom namespaces for models and policies when using non-standard directories, such as 'Entities\\' and 'Auth\\Policies\\'.

```php
// Models in Modules/Blog/Entities/
'models' => [
    'active' => true,
    'namespace' => 'Entities\\',
],

// Policies in Modules/Blog/Auth/Policies/
'policies' => [
    'active' => true,
    'namespace' => 'Auth\\Policies\\',
],
```

--------------------------------

### Configure per-module active and order settings

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Per-module settings in config/modules.php. Modules not listed default to active true with order 9999; active false skips the module entirely.

```php
'modules' => [
    'Shared' => [
        'active' => true,
        'order' => 1,    // lower numbers load first
    ],
    'Blog' => [
        'active' => true,
        'order' => 2,
    ],
    'Legacy' => [
        'active' => false, // completely ignored during discovery
    ],
],
```

--------------------------------

### Run migrations for a single module

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/migrations.md

Run migrations for a single module only by specifying the path.

```bash
php artisan migrate --path=Modules/Blog/Database/Migrations
```

--------------------------------

### Configure global modules directory and namespace

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Global settings in config/modules.php. Update both values and composer.json autoload mapping if renaming the modules directory.

```php
'modules_directory' => 'Modules',     // where modules live (relative to project root)
'modules_namespace' => 'Modules\\',   // PSR-4 namespace prefix
```

--------------------------------

### Default service-providers configuration

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/service-providers.md

Configuration snippet showing the default 'service-providers' array with 'active' set to true and patterns for discovering providers in '*/Providers' directories.

```php
'service-providers' => [
    'active' => true,
    'patterns' => [
        '*/Providers',
    ],
],
```

--------------------------------

### Default configuration for policies and models

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/policies.md

Shows the default configuration for the 'policies' and 'models' features. Both are active by default with namespaces 'Policies\\' and 'Models\\' respectively.

```php
'policies' => [
    'active' => true,
    'namespace' => 'Policies\\',
],

'models' => [
    'active' => true,
    'namespace' => 'Models\\',
],
```

--------------------------------

### Module Routes directory layout

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/routes.md

Shows the expected directory structure for module route files. Files named web.php, api.php, admin.php, channels.php, and console.php are automatically loaded with appropriate middleware groups.

```text
Modules/Blog/
└── Routes/
    ├── web.php         // web middleware group
    ├── api.php         // api prefix + middleware group
    ├── admin.php       // custom group (see below)
    ├── channels.php    // broadcast channel definitions
    └── console.php     // Artisan console commands and scheduling
```

--------------------------------

### Module directory layout for seeders

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/seeders.md

Shows the expected directory structure for a module's seeders. Only the main seeder (e.g., BlogDatabaseSeeder) is discovered; other seeders are ignored.

```text
Modules/Blog/
└── Database/
    └── Seeders/
        ├── BlogDatabaseSeeder.php     // discovered
        ├── PostSeeder.php             // NOT discovered
        └── CommentSeeder.php          // NOT discovered
```

--------------------------------

### Build discovery cache with php artisan modules:cache

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/caching.md

Scans all active modules and writes discovery results to individual cache files in bootstrap/cache/, such as modules-views.php and modules-routes.php. Run this during deployment to avoid scanning on every request.

```bash
php artisan modules:cache
```

--------------------------------

### Cache individual components including modules:cache

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/caching.md

Run these commands together to cache config, events, routes, views, and modules individually. Don't skip event:cache because module listeners are discovered by reflecting on every listener class, and without it that scan repeats on every request.

```bash
php artisan config:cache
php artisan event:cache
php artisan route:cache
php artisan view:cache
php artisan modules:cache
```

--------------------------------

### Dispatching events with event() helper, Event facade, and static dispatch

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/events-listeners.md

Standard Laravel ways to dispatch the PostPublished event, showing three equivalent approaches.

```php
use Modules\Blog\Events\PostPublished;

// Using the event() helper
event(new PostPublished($post));

// Using the Event facade
Event::dispatch(new PostPublished($post));

// Using the static dispatch method
PostPublished::dispatch($post);
```

--------------------------------

### Configure per-feature active and patterns

Source: https://github.com/mozex/laravel-modules/blob/main/docs/introduction.md

Per-feature settings in config/modules.php. active false disables the feature for all modules; patterns use glob syntax relative to the modules directory.

```php
'views' => [
    'active' => true,
    'patterns' => [
        '*/Resources/views',
    ],
],
```

--------------------------------

### Custom namespace configuration for models and factories

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/models-factories.md

Shows how to update the 'namespace' settings when modules use different directory structures, such as Entities instead of Models, or Tests/Factories instead of Database/Factories.

```php
// If models live in Modules/Blog/Entities/ instead of Modules/Blog/Models/
'models' => [
    'active' => true,
    'namespace' => 'Entities\\',
],

// If factories live in Modules/Blog/Tests/Factories/
'factories' => [
    'active' => true,
    'namespace' => 'Tests\\Factories\\',
],
```

--------------------------------

### Accessing PHP array translations

Source: https://github.com/mozex/laravel-modules/blob/main/docs/features/translations.md

Shows how to access PHP array translations using the namespace::file.key syntax and the trans_choice helper.

```php
__('blog::messages.welcome')
// "Welcome to the blog"

__('blog::messages.post_created', ['title' => 'My First Post'])
// "Your post "My First Post" has been published."

trans_choice('blog::messages.comments', 5, ['count' => 5])
// "5 comments"
```
Tokens:
Raw