InterNACHI Modular

https://github.com/internachi/modular
Admin
A module system for Laravel applications that uses Composer path repositories and Laravel package...
Tokens:58,818
Snippets:455
Trust Score:6.6
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### ModuleConfig usage example

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Shows how to use a ModuleConfig instance to get the module name, FQCN, and migration directory.

```php
use InterNACHI\Modular\Support\Facades\Modules;

$module = Modules::module('demo');
if ($module === null) {
    return;
}

$viewNamespace = $module->name;                          // 'demo'
$fqcn = $module->pathToFullyQualifiedClassName(
    $module->path('src/Models/Thing.php')                // 'Modules\Demo\Models\Thing'
);
$migrationDir = $module->path('database/migrations');
```

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

### Usage Example

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Demonstrates how to instantiate the helper and use it to create a module factory.

```APIDOC
## Usage Example

### Description
Shows how to create a DatabaseFactoryHelper and use it to resolve a module factory.

### Code
```php
use Illuminate\Database\Eloquent\Factories\Factory;
use InterNACHI\Modular\Support\DatabaseFactoryHelper;

$helper = new DatabaseFactoryHelper(app('registry'));

// Instantiate a module factory directly:
$factory = Factory::factoryForModel(\Modules\Demo\Models\Thing::class);
$thing = $factory->create();   // resolves via the modular resolver
```
```

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

### Usage example with FinderFactory

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Shows how to use FinderFactory to create finders, apply withModuleInfo, and safely handle directories that may not exist.

```php
use InterNACHI\Modular\Support\FinderFactory;

$finders = new FinderFactory(base_path('app-modules'));

// Finder semantics (files, name, sort) + collection semantics (map, values)
$files = $finders
    ->commandFileFinder()
    ->withModuleInfo()
    ->values()
    ->map(fn(ModuleFileInfo $f) => $f->fullyQualifiedClassName());

// Directory that may not exist — safe:
$routes = $finders->routeFileFinder()->values();
```

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

### Usage example for DatabaseFactoryHelper

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Shows how to instantiate the helper and use it to create a module factory directly.

```php
use Illuminate\Database\Eloquent\Factories\Factory;
use InterNACHI\Modular\Support\DatabaseFactoryHelper;

$helper = new DatabaseFactoryHelper(app('registry'));

// Instantiate a module factory directly:
$factory = Factory::factoryForModel(\Modules\Demo\Models\Thing::class);
$thing = $factory->create();   // resolves via the modular resolver
```

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

### make:module usage examples

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Shows how to run the make:module command with and without the --accept-default-namespace flag.

```shell
php artisan make:module my-module
php artisan make:module my-module --accept-default-namespace
```

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

### Cache usage example

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Example of using the Cache class: read, write, and clear the cache. Handles CannotWriteCacheException.

```php
use InterNACHI\Modular\Support\Cache;
use InterNACHI\Modular\Exceptions\CannotWriteCacheException;

$cache = app(Cache::class);

$data = $cache->read();          // [] when the cache file is missing or broken

try {
    $cache->write(['ModulesPlugin' => [...]]);
} catch (CannotWriteCacheException $e) {
    // file could not be written, or the written PHP could not be re-required
    report($e);
}

$cache->clear();
```

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

### Usage example with FinderFactory

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Shows how to use ModuleFileInfo with FinderFactory to iterate over model files and access their FQCN and module.

```php
use InterNACHI\Modular\Support\FinderFactory;

$finders = new FinderFactory(base_path('app-modules'));

foreach ($finders->modelFileFinder()->withModuleInfo() as $file) {
    $fqcn = $file->fullyQualifiedClassName(); // e.g. 'Modules\Demo\Models\User'
    $module = $file->module();                // ModuleConfig
    echo $module->name;                       // 'demo'
}
```

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

### Custom stub configuration example

Source: https://github.com/internachi/modular/blob/main/_autodocs/configuration.md

Example of configuring custom stubs in the config file. Maps a stub path to a custom stub file location.

```php
// config/app-modules.php
'stubs' => [
    'src/Providers/StubClassNamePrefixServiceProvider.php' => base_path('stubs/app-modules/ServiceProvider.php'),
],
```

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

### Usage Example

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Demonstrates how to use ModuleFileInfo with FinderFactory to iterate over model files and access their FQCN and module information.

```APIDOC
## Usage Example

### Description
Demonstrates how to use ModuleFileInfo with FinderFactory to iterate over model files and access their FQCN and module information.

### Code
```php
use InterNACHI\Modular\Support\FinderFactory;

$finders = new FinderFactory(base_path('app-modules'));

foreach ($finders->modelFileFinder()->withModuleInfo() as $file) {
    $fqcn = $file->fullyQualifiedClassName(); // e.g. 'Modules\Demo\Models\User'
    $module = $file->module();                // ModuleConfig
    echo $module->name;                       // 'demo'
}
```

```

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

### Install Modular package with Composer

Source: https://github.com/internachi/modular/blob/main/README.md

Run this command to install the Modular package. Laravel auto-discovers the package and sets it up automatically.

```shell script
composer require internachi/modular
```

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

### Usage example for PluginRegistry

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Shows how to register a plugin from a service provider and then retrieve and iterate over all registered plugins in application code.

```php
use InterNACHI\Modular\PluginRegistry;

// In a service provider register():
PluginRegistry::register(MyPlugin::class);

// Inside application code:
$registry = app(PluginRegistry::class);
foreach ($registry->all() as $pluginClass) {
    $instance = $registry->get($pluginClass);
}
```

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

### Usage examples for module-specific make commands

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Shows how to use the overridden make commands with the --module= option to generate files within a module. Includes commands for creating a model, controller, test, and running a seeder.

```shell
php artisan make:model Thing --module=demo
php artisan make:controller ThingController --module=demo --model=Thing
php artisan make:test ThingTest --module=demo
php artisan db:seed --module=demo
```

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

### Custom ConfigWriter usage example

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/phpstorm-writers.md

Example of extending ConfigWriter to create a custom writer, including instantiation and handling with error logging.

```php
use InterNACHI\Modular\Support\ModuleRegistry;
use InterNACHI\Modular\Support\PhpStorm\ConfigWriter;

class MyConfigWriter extends ConfigWriter
{
    public function write(): bool
    {
        // ... mutate XML ...
        return false !== file_put_contents($this->config_path, $this->formatXml($xml));
    }
}

$writer = new MyConfigWriter($path, app(ModuleRegistry::class));
if ($writer->handle()) {
    // success
} else {
    logger()->warning($writer->last_error);
}
```

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

### PluginDataRepository get method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Returns discovery data for a single plugin as a Collection, running discover() on first access and memoizing the result.

```php
/** @param class-string<Plugin> $name */
public function get(string $name): Collection
```

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

### Install DatabaseFactoryHelper in ModularServiceProvider

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Creates a DatabaseFactoryHelper instance and registers model and factory name resolvers with Eloquent's Factory class.

```php
$helper = new DatabaseFactoryHelper($this->app->make(ModuleRegistry::class));

EloquentFactory::guessModelNamesUsing($helper->modelNameResolver());
EloquentFactory::guessFactoryNamesUsing($helper->factoryNameResolver());
```

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

### Catch CannotFindModuleForPathException

Source: https://github.com/internachi/modular/blob/main/_autodocs/errors.md

Example of catching the CannotFindModuleForPathException when calling Modules::moduleForPathOrFail().

```APIDOC
## Catch CannotFindModuleForPathException

### Description
Demonstrates how to catch the `CannotFindModuleForPathException` thrown by `Modules::moduleForPathOrFail()` when a path does not correspond to a registered module.

### Method
N/A (PHP exception handling)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```php
use InterNACHI\Modular\Exceptions\CannotFindModuleForPathException;

try {
    $config = Modules::moduleForPathOrFail($path);
} catch (CannotFindModuleForPathException $e) {
    // $e->getMessage() === "Unable to determine module for '{$path}'"
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

### Error Handling
- **Exception**: `InterNACHI\Modular\Exceptions\CannotFindModuleForPathException`
- **Message**: `Unable to determine module for '{path}'`
- **Code**: `0`
- **Trigger**: When `ModuleRegistry::moduleForPathOrFail()` is called with a path whose first segment does not match any registered module name.
- **Source**: `src/Support/ModuleRegistry.php:44`, `src/Support/ModuleFileInfo.php:26`, `src/Support/Facades/Modules.php`
```

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

### Catch RuntimeException from pathToFullyQualifiedClassName

Source: https://github.com/internachi/modular/blob/main/_autodocs/errors.md

Example of catching a RuntimeException when a path is not mapped to a PSR-4 namespace. Triggered by ModuleConfig::pathToFullyQualifiedClassName() when the path does not start with any registered namespace.

```php
try {
    $fqcn = $module->pathToFullyQualifiedClassName('/unmapped/path.php');
} catch (\RuntimeException $e) {
    // handle
}
```

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

### RoutesPlugin boot, discover, and handle methods

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

Boots eagerly only when routes are not cached. discover returns real paths of route files, and handle requires each file to register routes.

```php
public static function boot(Closure $handler, Application $app): void
{
    if (! $app->routesAreCached()) {
        $handler(static::class);
    }
}

public function discover(FinderFactory $finders): iterable
{
    return $finders
        ->routeFileFinder()
        ->values()
        ->map(fn(SplFileInfo $file) => $file->getRealPath());
}

public function handle(Collection $data): void
{
    $data->each(fn(string $filename) => require $filename);
}
```

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

### ArtisanPlugin boot, discover, and handle methods

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

Defines the ArtisanPlugin class with boot(), discover(), and handle() methods. boot() injects the artisan instance via parameter override, discover() returns FQCNs of concrete command classes, and handle() registers each command with Artisan and configures tinker aliases.

```php
public static function boot(Closure $handler, Application $app): void
{
    Artisan::starting(fn($artisan) => $handler(static::class, ['artisan' => $artisan]));
}

public function __construct(
    protected Artisan $artisan,
    protected ModuleRegistry $registry,
) {}

public function discover(FinderFactory $finders): iterable
{
    return $finders
        ->commandFileFinder()
        ->withModuleInfo()
        ->values()
        ->map(fn(ModuleFileInfo $file) => $file->fullyQualifiedClassName())
        ->filter($this->isInstantiableCommand(...));
}

public function handle(Collection $data): void
{
    $data->each(fn(string $fqcn) => $this->artisan->resolve($fqcn));

    $this->registerNamespacesInTinker();
}
```

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

### Modules facade usage

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Shows how to use the Modules facade to retrieve a module and the facade root.

```php
use InterNACHI\Modular\Support\Facades\Modules;

$module = Modules::module('demo');                // ModuleConfig|null
$registry = Modules::getFacadeRoot();             // ModuleRegistry
```

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

### Abstract Plugin class with boot, discover, and handle methods

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Base class for all plugins. Declares boot timing via a PHP 8 attribute implementing HandlesBoot, and requires subclasses to implement discover() and handle(). The boot() method is called once during $app->booting() by PluginHandler::boot().

```php
abstract class Plugin
{
    public static function boot(Closure $handler, Application $app): void
    {
        static::firstBootableAttribute()?->newInstance()->boot(static::class, $handler, $app);
    }

    /** @return ReflectionAttribute<HandlesBoot>|null */
    protected static function firstBootableAttribute(): ?ReflectionAttribute
    {
        $attributes = (new ReflectionClass(static::class))
            ->getAttributes(HandlesBoot::class, ReflectionAttribute::IS_INSTANCEOF);

        return $attributes[0] ?? null;
    }

    abstract public function discover(FinderFactory $finders): iterable;

    abstract public function handle(Collection $data);
}
```

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

### Catching CannotFindModuleForPathException

Source: https://github.com/internachi/modular/blob/main/_autodocs/errors.md

Example of catching the exception when calling Modules::moduleForPathOrFail(). The caught exception's message will be 'Unable to determine module for '{path}''.

```php
use InterNACHI\Modular\Exceptions\CannotFindModuleForPathException;

try {
    $config = Modules::moduleForPathOrFail($path);
} catch (CannotFindModuleForPathException $e) {
    // $e->getMessage() === "Unable to determine module for '{$path}'"
}
```

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

### get method signature

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Resolves a plugin through the container with optional constructor overrides. Throws InvalidArgumentException if the plugin is not registered. Cached instances are forgotten and re-made when parameters are provided, then stored as a container singleton.

```php
/**
 * @template TPlugin of Plugin
 * @param class-string<TPlugin> $plugin
 * @return TPlugin
 */
public function get(string $plugin, array $parameters = []): Plugin
```

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

### Constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Creates a new DatabaseFactoryHelper instance with the given module registry.

```APIDOC
## Constructor

### Description
Creates a new DatabaseFactoryHelper instance.

### Signature
```php
public function __construct(
    protected ModuleRegistry $registry
)
```

### Parameters
- **$registry** (ModuleRegistry) - Required - The module registry used to resolve module namespaces.
```

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

### Catch InvalidArgumentException for unregistered plugin

Source: https://github.com/internachi/modular/blob/main/_autodocs/errors.md

Example of catching an InvalidArgumentException when trying to resolve an unregistered plugin. Triggered by PluginRegistry::get() when the class name was never registered. The comment shows that registration must happen first.

```php
// Any attempt to resolve an unregistered plugin class:
PluginRegistry::register(MyPlugin::class);   // register first!

try {
    app(PluginRegistry::class)->get(UnregisteredPlugin::class);
} catch (\InvalidArgumentException $e) {
    // "The plugin 'UnregisteredPlugin' has not been registered."
}
```

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

### all method signature

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Returns an array of registered plugin class names in registration order.

```php
/** @return class-string<\InterNACHI\Modular\Plugins\Plugin>[] */
public function all(): array
```

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

### PluginHandler boot method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Boots all registered plugins, calling each plugin's boot method with a handle callback and the application instance. Triggers attribute-based scheduling.

```php
public function boot(Application $app): void
```

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

### Invalid model name in make:controller throws InvalidArgumentException

Source: https://github.com/internachi/modular/blob/main/_autodocs/errors.md

Example of an artisan command that triggers an InvalidArgumentException when the --model value contains invalid characters. Triggered by MakeController::parseModel() when a --module option is selected.

```php
// artisan:
// php artisan make:controller FooController --module=demo --model="Bad Model!"   → throws
```

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

### register() method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/service-providers.md

Registers the command overrides by hooking into the application's booted event and Artisan::starting. This ensures the overrides are applied regardless of provider bootstrap order. Every alias is bound as a singleton and its parent class binding is pointed at the override.

```php
public function register(): void
{
    $this->app->booted(function() {
        Artisan::starting(function(Application $artisan) {
            $this->registerMakeCommandOverrides();
            $this->registerMigrationCommandOverrides();
        });
    });
}
```

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

### ModularServiceProvider boot method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/service-providers.md

Boot method that publishes the config file under the 'modular-config' tag, registers five package commands when running in console, and wires modules:cache and modules:clear into optimize commands on Laravel 11+.

```php
public function boot(): void
{
    $this->publishes([
        "{$this->base_dir}/config/app-modules.php" => $this->app->configPath('app-modules.php'),
    ], 'modular-config');

    if ($this->app->runningInConsole()) {
        if (method_exists($this, 'optimizes')) {
            $this->optimizes('modules:cache', 'modules:clear', 'app-modules');
        }
        $this->commands([
            MakeModule::class,
            ModulesCache::class,
            ModulesClear::class,
            ModulesSync::class,
            ModulesList::class,
        ]);
    }
}
```

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

### withModuleInfo method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Maps each SplFileInfo into a ModuleFileInfo decorator using new ModuleFileInfo($file).

```php
public function withModuleInfo(): static
```

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

### Constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Creates a new ModuleRegistry instance with the modules path and loader closure.

```APIDOC
## Constructor

### Description
Creates a new ModuleRegistry instance.

### Signature
```php
public function __construct(
    protected string $modules_path,
    protected Closure $modules_loader,
)
```

### Parameters
- **$modules_path** (string) - Required - Absolute path to the modules directory (e.g. `.../app-modules`). Returned by `getModulesPath()`.
- **$modules_loader** (Closure) - Required - Callable that returns a `Collection<int, ModuleConfig>`. The service provider binds it to `PluginHandler::handle(ModulesPlugin::class)`.

### Notes
The container binding is created in `ModularServiceProvider::register()` with the modules path derived from `config('app-modules.modules_directory')` and the loader delegating to the plugin system.
```

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

### GatePlugin class implementation

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

Scans src/Models/*.php and probes two policy candidates per model: {Namespace}\Policies\{ModelPath}Policy and {Namespace}\Policies\{ModelBasename}Policy. The first existing class wins; models with no matching policy are filtered out. handle() registers each mapping via $gate->policy($fqcn, $policyClass).

```php
#[AfterResolving(Gate::class, parameter: 'gate')]
class GatePlugin extends Plugin
{
    public function __construct(
        protected Gate $gate
    ) {}

    public function discover(FinderFactory $finders): iterable
    {
        return $finders
            ->modelFileFinder()
            ->withModuleInfo()
            ->values()
            ->map(function(ModuleFileInfo $file) {
                $fqcn = $file->fullyQualifiedClassName();
                $namespace = rtrim($file->module()->namespaces->first(), '\\');

                $candidates = [
                    $namespace.'\\Policies\\'.Str::after($fqcn, 'Models\\').'Policy', // Policies/Foo/BarPolicy
                    $namespace.'\\Policies\\'.Str::afterLast($fqcn, '\\').'Policy',   // Policies/BarPolicy
                ];

                foreach ($candidates as $candidate) {
                    if (class_exists($candidate)) {
                        return [
                            'fqcn' => $fqcn,
                            'policy' => $candidate,
                        ];
                    }
                }

                return null;
            })
            ->filter();
    }

    public function handle(Collection $data): void
    {
        $data->each(fn(array $row) => $this->gate->policy($row['fqcn'], $row['policy']));
    }
}
```

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

### Constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Creates a new ModuleFileInfo instance wrapping a Symfony SplFileInfo object.

```APIDOC
## Constructor

### Description
Creates a new ModuleFileInfo instance wrapping a Symfony SplFileInfo object.

### Signature
```php
public function __construct(
    protected SplFileInfo $file,
)
```

### Parameters
- **$file** (SplFileInfo) - Required - The underlying Symfony file info object.

```

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

### modules:list command signature and description

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Defines the command signature and description for the modules:list command. The handle method prints a table with columns Module, Path, and Namespace (or Namespaces), plus a summary line.

```php
protected $signature = 'modules:list';
protected $description = 'List all modules';
```

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

### ModulesPlugin discover and handle methods

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

The discover method scans app-modules/*/composer.json and returns a collection keyed by module name. The handle method hydrates each array into a ModuleConfig instance.

```php
public function discover(FinderFactory $finders): iterable
{
    return $finders
        ->moduleComposerFileFinder()
        ->values()
        ->mapWithKeys(function(SplFileInfo $file) { /* … */ });
}

/** @return Collection<int, ModuleConfig> */
public function handle(Collection $data): Collection
{
    return $data->map(fn(array $d) => new ModuleConfig($d['name'], $d['base_path'], new Collection($d['namespaces'])));
}
```

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

### Plugin::boot

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Static method that reads the first HandlesBoot attribute on the plugin class and delegates boot scheduling to it. Called once during the application's booting phase.

```APIDOC
## Plugin::boot

### Description
Reads the first `HandlesBoot`-implementing attribute on the class and delegates scheduling to it. Called once during `$app->booting()` by `PluginHandler::boot()`.

### Method
`boot(Closure $handler, Application $app): void`

### Parameters
- **$handler** (Closure) - Required - The handler closure to be scheduled.
- **$app** (Application) - Required - The Laravel application instance.

### Return Value
void
```

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

### ModuleConfig pathToFullyQualifiedClassName method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Converts a file path to an FQCN, throwing RuntimeException if not in a registered namespace.

```php
public function pathToFullyQualifiedClassName(string $path): string
```

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

### make:module constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Constructor for the MakeModule command, injecting Filesystem and ModuleRegistry dependencies.

```php
public function __construct(
    protected Filesystem $filesystem,
    protected ModuleRegistry $module_registry
) {
    parent::__construct();
}
```

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

### ModuleConfig constructor and public properties

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Constructor with public properties for name, base_path, and namespaces.

```php
public function __construct(
    public string $name,
    public string $base_path,
    public Collection $namespaces = new Collection(),
)
```

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

### FinderCollection::forDirectories()

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Static constructor that creates a FinderCollection for directories.

```APIDOC
## FinderCollection::forDirectories()

### Description
Creates a new FinderCollection instance configured to find directories.

### Method
Static constructor

### Signature
```php
public static function forDirectories(): self
```

### Returns
- **self** - A new FinderCollection instance.

### Example
```php
$directories = FinderCollection::forDirectories();
```
```

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

### ModuleConfig qualify method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Prepends the primary namespace to a class name.

```php
public function qualify(string $class_name): string
```

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

### make:module command signature and description

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Defines the make:module command's signature and description. The signature includes a required 'name' argument and an optional '--accept-default-namespace' flag. The description is 'Create a new Laravel module'.

```php
protected $signature = 'make:module
    {name : The name of the module}
    {--accept-default-namespace : Skip default namespace confirmation}';

protected $description = 'Create a new Laravel module';
```

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

### FinderCollection::withModuleInfo()

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Maps each SplFileInfo to a ModuleFileInfo decorator.

```APIDOC
## FinderCollection::withModuleInfo()

### Description
Transforms each file found by the finder into a ModuleFileInfo object, which decorates the SplFileInfo with additional module-related information.

### Method
withModuleInfo

### Signature
```php
public function withModuleInfo(): static
```

### Returns
- **static** - A FinderCollection instance with ModuleFileInfo objects.

### Example
```php
$files = $finder->withModuleInfo();
```
```

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

### Static constructors forFiles and forDirectories

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Static factory methods that create a FinderCollection wrapping Finder::create()->files() or Finder::create()->directories().

```php
public static function forFiles(): self        // Finder::create()->files()
public static function forDirectories(): self  // Finder::create()->directories()
```

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

### module method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Returns the ModuleConfig for the given module name (directory name / composer package short name). Returns null if no module with that name exists or the name is empty.

```php
public function module(?string $name = null): ?ModuleConfig
```

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

### ConfigWriter abstract and handle method signatures

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/phpstorm-writers.md

Abstract write() method and concrete handle() method that checks file permissions before delegating to write().

```php
abstract public function write(): bool;

public function handle(): bool
```

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

### Module directory structure

Source: https://github.com/internachi/modular/blob/main/README.md

Shows the directory structure created for a new module named my-module.

```text
app-modules/
  my-module/
    composer.json
    src/
    tests/
    routes/
    resources/
    database/
```

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

### ViewPlugin class with AfterResolving attribute

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

Registers view namespaces for each module's resources/views directory. The discover method returns module name and path pairs, and handle adds them to the ViewFactory. Use to enable view('demo::index') syntax.

```php
#[AfterResolving(ViewFactory::class, parameter: 'factory')]
class ViewPlugin extends Plugin
{
    public function __construct(
        protected ViewFactory $factory,
    ) {}

    public function discover(FinderFactory $finders): iterable
    {
        return $finders
            ->viewDirectoryFinder()
            ->withModuleInfo()
            ->values()
            ->map(fn(ModuleFileInfo $dir) => [
                'namespace' => $dir->module()->name,
                'path' => $dir->getRealPath(),
            ]);
    }

    public function handle(Collection $data)
    {
        $data->each(fn(array $d) => $this->factory->addNamespace($d['namespace'], $d['path']));
    }
}
```

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

### PluginDataRepository constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Constructor for PluginDataRepository, accepting pre-populated discovery data, a plugin registry, and a finder factory.

```php
public function __construct(
    protected array $data,
    protected PluginRegistry $registry,
    protected FinderFactory $finders,
)
```

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

### Constructor with optional finder and collection

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Constructor accepting an optional Finder and LazyCollection. If neither is provided, an empty lazy collection is created.

```php
public function __construct(
    protected ?Finder $finder = null,
    protected ?LazyCollection $collection = null,
)
```

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

### make:module

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Scaffolds a new module and registers it in the application's composer.json as a path repository and require entry. This command creates the module directory structure, writes stub files, and updates the composer configuration.

```APIDOC
## make:module

### Description
Scaffolds a new module and registers it in the application's composer.json as a path repository + require entry.

### Method
Artisan Command

### Endpoint
`php artisan make:module {name} {--accept-default-namespace}`

### Parameters
#### Arguments
- **name** (string) - Required - The name of the module. Kebab-cased for the directory/composer name, Studly for the class prefix.

#### Options
- **--accept-default-namespace** (flag) - Optional - Skips the interactive "configure your namespace first?" confirmation that appears for the first module when the namespace is still the default `Modules`.

### Request Example
```shell
php artisan make:module my-module
php artisan make:module my-module --accept-default-namespace
```

### Response
#### Success Response (0)
- Exit code 0 on success.
- Prints "Please run `composer update {composer_name}`".

#### Response Example
```
Please run composer update vendor/module-name
```

### Behavior
1. If this is the first module, the namespace is still `Modules`, and `--accept-default-namespace` was not passed, it prompts "Would you like to cancel and configure your module namespace first?" (default yes) — confirming aborts with exit code `0`.
2. Creates the module base directory with mode `0777` (recursive) if missing.
3. Writes each stub to `{base_path}/{destination}`, skipping files that already exist. Placeholders replaced in both filenames and contents: `StubBasePath`, `StubModuleNamespace`, `StubComposerNamespace`, `StubModuleNameSingular`, `StubModuleNamePlural`, `StubModuleName`, `StubClassNamePrefix`, `StubComposerName`, `StubMigrationPrefix` (`date('Y_m_d_His')`), `StubFullyQualifiedTestCaseBase` (`config('app-modules.tests_base', 'Tests\TestCase')`), `StubTestCaseBase` (`class_basename` of the test base).
4. Updates the app's `composer.json` (CWD switched to the Laravel base directory, restored afterwards). Adds a `repositories` entry `{module_name: {type: path, url: {modules_directory}/*, options: {symlink: true}}}` when no repository with the same `url` exists, and a `require` entry `"{composer_namespace}/{module_name}": "*"` when missing. `require` keys are re-sorted with Composer's canonical package ordering.
5. Calls `ModulesClear` (`modules:clear`), prints "Please run `composer update {composer_name}`", reloads the registry, and returns `0`.

### Notes
- Class: `InterNACHI\Modular\Console\Commands\Make\MakeModule`
- Source: `src/Console/Commands/Make/MakeModule.php`
```

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

### ModularServiceProvider constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/service-providers.md

Constructor for the main service provider. Sets base_dir to the package root (two directories above src/Support/) normalized to forward slashes. The $app parameter is the Laravel application.

```php
public function __construct($app)
{
    parent::__construct($app);

    $this->base_dir = str_replace('\\', '/', dirname(__DIR__, 2));
}
```

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

### __call method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Forwards any unknown method to the wrapped SplFileInfo (e.g., getRealPath(), getContents(), getFilename()).

```php
public function __call(string $name, array $arguments)
```

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

### FinderCollection::forFiles()

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Static constructor that creates a FinderCollection for files.

```APIDOC
## FinderCollection::forFiles()

### Description
Creates a new FinderCollection instance configured to find files.

### Method
Static constructor

### Signature
```php
public static function forFiles(): self
```

### Returns
- **self** - A new FinderCollection instance.

### Example
```php
$files = FinderCollection::forFiles();
```
```

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

### moduleForClass method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Returns the ModuleConfig whose namespace is a prefix of the given fully-qualified class name. When multiple namespaces match, the longest (most specific) prefix wins because the namespace index is sorted descending.

```php
public function moduleForClass(string $fqcn): ?ModuleConfig
```

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

### DatabaseFactoryHelper constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Constructor that accepts a ModuleRegistry instance.

```php
public function __construct(
    protected ModuleRegistry $registry
)
```

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

### ConfigWriter::__construct

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/phpstorm-writers.md

Constructor for the ConfigWriter class. Initializes the writer with a config file path and a module registry.

```APIDOC
## ConfigWriter::__construct

### Description
Creates a new ConfigWriter instance with the given config file path and module registry.

### Method
Constructor

### Signature
```php
public function __construct($config_path, ModuleRegistry $module_registry)
```

### Parameters
- **$config_path** (string, untyped) - Required - Absolute path of the PhpStorm XML file to update.
- **$module_registry** (ModuleRegistry) - Required - Source of installed modules.

```

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

### PluginDataRepository all method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Materializes and memoizes discovery data for every registered plugin, returning the full data array. Used by modules:cache to persist via Cache::write().

```php
public function all(): array
```

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

### modules method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Returns an Illuminate\Support\Collection of ModuleConfig, lazy-loaded on first call and memoized.

```php
/** @return Collection<int, ModuleConfig> */
public function modules(): Collection
```

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

### FinderCollection::__construct()

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Constructor for FinderCollection, optionally accepting a Finder and LazyCollection.

```APIDOC
## FinderCollection::__construct()

### Description
Initializes a new FinderCollection instance. If neither argument is provided, an empty lazy collection is created.

### Method
Constructor

### Signature
```php
public function __construct(
    protected ?Finder $finder = null,
    protected ?LazyCollection $collection = null,
)
```

### Parameters
- **finder** (Finder|null) - Optional - The underlying Finder instance.
- **collection** (LazyCollection|null) - Optional - The underlying LazyCollection instance.

### Example
```php
$collection = new FinderCollection();
```
```

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

### Create a new module

Source: https://github.com/internachi/modular/blob/main/README.md

Scaffolds a new module with the given name. Creates the app-modules/my-module directory structure and adds entries to composer.json.

```shell script
php artisan make:module my-module
```

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

### moduleForClass(string $fqcn): ?ModuleConfig

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Resolves a module from a fully-qualified class name. The most specific namespace prefix wins.

```APIDOC
## moduleForClass(string $fqcn): ?ModuleConfig

### Description
Resolves a module from a fully-qualified class name. The most specific namespace prefix wins.

### Method
`moduleForClass`

### Signature
```php
public function moduleForClass(string $fqcn): ?ModuleConfig
```

### Parameters
- **$fqcn** (string) - Required - A fully-qualified class name (e.g. `Modules\Demo\Models\Thing`).

### Returns
- **?ModuleConfig** - The `ModuleConfig` whose namespace is a prefix of the class. When multiple namespaces match, the longest (most specific) prefix wins because the namespace index is sorted descending (`namespaceIndex()` uses `sortKeysDesc()`).

### Source
`src/Support/ModuleRegistry.php:47`
```

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

### Cache constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Constructor for the Cache class. Takes a Filesystem instance and an absolute path to the cache file.

```php
public function __construct(
    protected Filesystem $fs,
    protected string $path,
)
```

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

### modules:sync command signature and description

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Defines the command signature and description for the modules:sync command. The signature includes options --no-phpstorm and --no-phpunit to skip updates. The handle method runs updatePhpUnit() then updatePhpStormConfig() unless suppressed.

```php
protected $signature = 'modules:sync
                        {--no-phpstorm : Do not update PhpStorm config files}
                        {--no-phpunit : Do not update phpunit.xml file}';

protected $description = 'Sync your project\'s configuration with your current modules';
```

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

### namespace method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Reads Factory::$namespace (protected static) via reflection; memoized.

```php
public function namespace(): string
```

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

### OnBoot attribute implementation

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Runs the handler eagerly during the booting() hook with no parameter overrides. This attribute implements HandlesBoot and simply invokes the handler with the plugin class-string.

```php
#[Attribute(Attribute::TARGET_CLASS)]
class OnBoot implements HandlesBoot
{
    public function boot(string $plugin, Closure $handler, Application $app)
    {
        $handler($plugin);
    }
}
```

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

### PluginRegistry::all

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Returns the list of registered plugin class names in registration order.

```APIDOC
## PluginRegistry::all

### Description
Returns the list of registered plugin class names in registration order.

### Method
`public function all(): array`

### Returns
- An array of class-string<Plugin>.

### Source
`src/PluginRegistry.php:61`
```

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

### modules:cache command signature and description

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/console-commands.md

Defines the modules:cache command's signature and description. The signature is 'modules:cache' and the description is 'Create a cache file for faster module loading'.

```php
protected $signature = 'modules:cache';
protected $description = 'Create a cache file for faster module loading';
```

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

### BladePlugin class with AfterResolving attribute

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

Registers Blade class components and component directories per module. discover returns files and directories arrays; handle registers each component and namespace with the module-name prefix, enabling <x-demo::alert /> and <x-demo::nested.one />.

```php
#[AfterResolving(BladeCompiler::class, parameter: 'blade')]
class BladePlugin extends Plugin
{
    public function __construct(
        protected BladeCompiler $blade
    ) {}

    public function discover(FinderFactory $finders): iterable
    {
        return [
            'files' => $finders
                ->bladeComponentFileFinder()
                ->withModuleInfo()
                ->values()
                ->map(fn(ModuleFileInfo $component) => [
                    'prefix' => $component->module()->name,
                    'fqcn' => $component->fullyQualifiedClassName(),
                ])
                ->toArray(),
            'directories' => $finders
                ->bladeComponentDirectoryFinder()
                ->withModuleInfo()
                ->values()
                ->map(fn(ModuleFileInfo $component) => [
                    'prefix' => $component->module()->name,
                    'namespace' => $component->module()->qualify('View\Components'),
                ])
                ->toArray(),
        ];
    }

    public function handle(Collection $data)
    {
        foreach ($data['files'] as $config) {
            $this->blade->component($config['fqcn'], null, $config['prefix']);
        }

        foreach ($data['directories'] as $config) {
            $this->blade->componentNamespace($config['namespace'], $config['prefix']);
        }
    }
}
```

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

### Cache::__construct

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/cache-and-factories.md

Constructor for the Cache class. Initializes the cache with a filesystem instance and the path to the cache file.

```APIDOC
## Cache::__construct

### Description
Initializes a new Cache instance with the given filesystem and cache file path.

### Method
Constructor

### Signature
```php
public function __construct(
    protected Filesystem $fs,
    protected string $path,
)
```

### Parameters
- **$fs** (Illuminate\Filesystem\Filesystem) - Required - Filesystem used for exists/put/delete and directory creation.
- **$path** (string) - Required - Absolute path to the cache file.

```

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

### moduleForPath method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Returns the ModuleConfig for the module whose directory is the first path segment after stripping the modules base path. Returns null if the path is outside the modules tree. Resolves symlinked modules-directory prefixes and normalizes Windows backslashes.

```php
public function moduleForPath(string $path): ?ModuleConfig
```

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

### ModuleFileInfo constructor

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Constructor that accepts a Symfony SplFileInfo object to wrap.

```php
public function __construct(
    protected SplFileInfo $file,
)
```

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

### Publish modular config

Source: https://github.com/internachi/modular/blob/main/_autodocs/configuration.md

Publishes the package's configuration file to `config/app-modules.php` using the `modular-config` tag.

```shell
php artisan vendor:publish --tag=modular-config
```

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

### ConfigWriter::handle

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/phpstorm-writers.md

Runs permission checks and then calls the write method. Returns false if permission checks fail.

```APIDOC
## ConfigWriter::handle

### Description
Runs permission checks and then calls the write method. Returns false if permission checks fail.

### Method
handle

### Signature
```php
public function handle(): bool
```

### Returns
- **bool** - True on success, false on failure.

### Notes
- Runs `checkConfigFilePermissions()`; if it fails, returns `false`. Otherwise returns `write()`.
- Source: `src/Support/PhpStorm/ConfigWriter.php:33`

```

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

### ModuleConfig factory method signature

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Signature of the fromComposerFile factory method.

```php
public static function fromComposerFile(SplFileInfo $composer_file): self
```

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

### __call()

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Forwards any unknown method calls to the wrapped SplFileInfo instance, enabling access to methods like getRealPath(), getContents(), and getFilename().

```APIDOC
## __call()

### Description
Forwards any unknown method calls to the wrapped SplFileInfo instance, enabling access to methods like getRealPath(), getContents(), and getFilename().

### Signature
```php
public function __call(string $name, array $arguments)
```

### Parameters
- **$name** (string) - Required - The method name to forward.
- **$arguments** (array) - Required - The arguments to pass to the forwarded method.

### Returns
- **mixed** - The result of the forwarded method call.

```

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

### TranslatorPlugin class implementation

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

Registers module language directories as translation namespaces and JSON paths. Uses #[AfterResolving(Translator::class, parameter: 'translator')] to inject the translator. The discover method returns module namespace and path pairs from the lang directory finder, and handle adds each namespace and JSON path to the translator.

```php
<?php

#[AfterResolving(Translator::class, parameter: 'translator')]
class TranslatorPlugin extends Plugin
{
    public function __construct(
        protected Translator $translator,
    ) {}

    public function discover(FinderFactory $finders): iterable
    {
        return $finders
            ->langDirectoryFinder()
            ->withModuleInfo()
            ->values()
            ->map(fn(ModuleFileInfo $dir) => [
                'namespace' => $dir->module()->name,
                'path' => $dir->getRealPath(),
            ]);
    }

    public function handle(Collection $data): void
    {
        $data->each(function(array $row) {
            $this->translator->addNamespace($row['namespace'], $row['path']);
            $this->translator->addJsonPath($row['path']);
        });
    }
}
```

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

### ModuleConfig::namespace

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Returns the first namespace in the namespaces collection.

```APIDOC
## ModuleConfig::namespace

### Description
Returns the primary namespace for the module.

### Method
`public function namespace(): string`

### Return Value
- `string` - The first namespace in the namespaces collection.

### Example
```php
$namespace = $module->namespace(); // 'Modules\Demo\'
```
```

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

### Constructor signature

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugin-system.md

Defines the constructor that receives the container instance.

```php
public function __construct(
    protected Container $container,
)
```

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

### moduleForPathOrFail method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Returns the ModuleConfig for a path expected to belong to a module. Throws InterNACHI\Modular\Exceptions\CannotFindModuleForPathException with message 'Unable to determine module for '{path}'' when no module can be determined.

```php
public function moduleForPathOrFail(string $path): ModuleConfig
```

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

### Default configuration file (config/app-modules.php)

Source: https://github.com/internachi/modular/blob/main/_autodocs/configuration.md

The default configuration file for the modular package. It defines the modules namespace, vendor, directory, tests base, stubs, and event discovery settings. This file is typically published to config/app-modules.php.

```php
<?php

return [
	'modules_namespace' => 'Modules',

	'modules_vendor' => null,

	'modules_directory' => 'app-modules',

	'tests_base' => 'Tests\TestCase',

	'stubs' => null,

	'should_discover_events' => null,
];
```

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

### ModuleConfig toArray method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Returns the module as an array.

```php
public function toArray(): array
```

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

### ModuleConfig path method

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/module-registry.md

Resolves a relative path against base_path.

```php
public function path(string $to = ''): string
```

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

### EventsPlugin class implementation

Source: https://github.com/internachi/modular/blob/main/_autodocs/api-reference/plugins.md

Discovers event listeners from module Listeners directories and registers them with the event dispatcher. Uses #[AfterResolving(Dispatcher::class, parameter: 'events')] to inject the dispatcher. Discovery is skipped when shouldDiscoverEvents() returns false, which checks config('app-modules.should_discover_events') or falls back to the application's EventServiceProvider discovery setting. handle() registers each unique listener for its event.

```php
<?php

#[AfterResolving(Dispatcher::class, parameter: 'events')]
class EventsPlugin extends Plugin
{
    public function __construct(
        protected Application $app,
        protected Dispatcher $events,
        protected Repository $config,
    ) {}

    public function discover(FinderFactory $finders): array
    {
        if (! $this->shouldDiscoverEvents()) {
            return [];
        }

        return $finders
            ->listenerDirectoryFinder()
            ->withModuleInfo()
            ->reduce(fn(array $discovered, ModuleFileInfo $file) => array_merge_recursive(
                $discovered,
                DiscoverEvents::within($file->getPathname(), $file->module()->path('src'))
            ), []);
    }

    public function handle(Collection $data): void
    {
        $data->each(function(array $listeners, string $event) {
            foreach (array_unique($listeners, SORT_REGULAR) as $listener) {
                $this->events->listen($event, $listener);
            }
        });
    }

    protected function shouldDiscoverEvents(): bool
    {
        return $this->config->get('app-modules.should_discover_events') ?? $this->appIsConfiguredToDiscoverEvents();
    }
}
```

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

### Update Composer for new module

Source: https://github.com/internachi/modular/blob/main/README.md

Run this after creating a module to update Composer dependencies for the new module.

```shell script
composer update modules/my-module
```
Tokens:
Raw