---
url: /custom-modules.md
---
# Custom Modules

Custom modules are a way to extend the functionality of your Evolve application. They can be used to encapsulate specific features, like a blog, a shop or a forum.

## Setup

You can create a new Evolve module with the help of the `evolve:module` artisan command. Just provide a module name as `vendor/package`:

```bash
php artisan evolve:module acme/blog
```

This command creates some module boilerplate inside `modules/acme/blog` and automatically registers it under the `Acme\Blog` namespace.

## Registration

The command adds the `Acme\Blog` namespace to the PSR-4 autoload of your `composer.json`, so run `composer dump-autoload` afterwards. Then register the service provider in `bootstrap/providers.php` (Laravel 12 projects; `config/app.php` on older ones):

```php{3}[bootstrap/providers.php]
return [
    App\Providers\AppServiceProvider::class,
    Acme\Blog\BlogServiceProvider::class,
];
```

Evolve's own providers are auto-discovered from the package and boot before the application's providers, so your module registers after the core is ready. Use the `Evolve` facade inside the `boot` function of the service provider:

```php{5-9}[BlogServiceProvider.php]
public function boot(): void
{
    parent::boot();

    Evolve::registerModule('blog', [
        'name' => 'Blog',
        'path' => $this->modulePath,
        // more configuration ...
    ]);
}
```

The provider extends `Racerfish\Evolve\ModuleServiceProvider`, which gives the module the same switch as the package modules: `evolve.modules.blog` or `EVOLVE_MODULE_BLOG` turns it off, and a disabled module loads nothing. Without a switch the module's `$defaultEnabled` applies (`true` in the base class). A new first-party module sets `protected bool $defaultEnabled = false;` and installs switch it on. What the registration array can carry (sidebar label, Cmd-K `commands`, `settings` keys for the Settings screen, `searchable` models, frontend translations) is described from the user's side on [Modules](/modules/).

## Adding CRUD resources

Evolve provides a `evolve:resource` helper command for creating [CRUD resources](/custom-modules/resources) inside your modules. You need to provide the package and resource name as arguments:

```bash
php artisan evolve:resource acme/blog post
```

This command creates boilerplate code for a `Acme\Blog\Post` model with migrations, controllers, managers and backend views.

::: tip
Add the `-t` or `--translatable` flag to also create **I18n** models and migrations of your resource.
:::

Then, after setting up the migrations, run `artisan:migrate` to update your database schema.