Laravel Modules子目录部署问题：composer配置后模块不显示

Let’s break down what’s going wrong here and fix it step by step—this is a common gotcha when nesting modules under subdirectories with nwidart’s Laravel Modules package.

Your Core Issues #

1. Root Composer Doesn’t Recognize Subdirectory Modules: Your root composer.json only maps the top-level Modules/ directory to the Modules\\ namespace, so it can’t pick up the Role2 module nested inside Administration/.
2. Missing Local Repository Configuration: Nwidart modules rely on their own composer.json files to define autoload rules, but your root composer isn’t set to scan subdirectories for these module-specific configs.
3. Module Scanner Ignores Subdirectories: The default module:list command only scans direct children of Modules/, so it won’t spot modules nested one level down.

Step 1: Fix Your Module’s composer.json #

First, make sure the Role2 module’s composer.json (located at Modules/Administration/Role2/composer.json) has the correct namespace and metadata:

{
    "name": "modules/administration-role2",
    "description": "Role management module under Administration",
    "type": "laravel-module",
    "autoload": {
        "psr-4": {
            "Modules\\Administration\\Role2\\": "src/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Modules\\Administration\\Role2\\Providers\\Role2ServiceProvider"
            ],
            "aliases": {}
        }
    }
}

• The type: laravel-module flag helps nwidart recognize this as a valid module.
• The PSR-4 mapping must match your module’s src/ directory structure.

Step 2: Update Root composer.json #

Add Local Repository for Subdirectory Modules #

Tell composer to scan the Administration/ subdirectory for module-specific composer.json files by adding a repositories section:

"repositories": [
    {
        "type": "path",
        "url": "Modules/Administration/*",
        "options": {
            "symlink": true
        }
    }
]

• symlink: true creates a soft link instead of copying files, which is better for development.

Add the Module to Your Dependencies #

In the require section of your root composer.json, add the module’s name (matching the name field in its composer.json):

"require": {
    // Your existing dependencies...
    "modules/administration-role2": "dev-master"
}

If this is a dev-only module, put it under require-dev instead.

(Alternative) Manual PSR-4 Mapping #

If you don’t want to use the local repository approach, you can directly map the module’s namespace in the root composer.json:

"autoload": {
    "psr-4": {
        // Your existing mappings...
        "Modules\\Administration\\Role2\\": "Modules/Administration/Role2/src"
    }
}

Note: This requires manual updates for every new subdirectory module, so the repository method is more scalable.

Step 3: Configure Nwidart to Scan Subdirectories #

Edit config/modules.php to update the module scan paths so module:list can find your nested module:

'scan' => [
    'enabled' => true,
    'paths' => [
        base_path('Modules/*'),
        base_path('Modules/Administration/*'),
    ],
],

Step 4: Refresh Composer Autoload #

Run this command to apply all changes:

composer update

Or if you only adjusted autoload rules (not dependencies):

composer dump-autoload -o

A Simpler Alternative for Subdirectory Organization #

If you want to avoid the composer config overhead, you can:

• Name modules with a prefix like Administration-Role2 (keeping them in the top-level Modules/ directory)
• Use namespaces like Modules\\AdministrationRole2\\ to logically group them
• Add a custom module generator command to automate creating prefixed modules if you do this often

This keeps the file structure flat but maintains logical separation, which works well for many projects.

内容的提问来源于stack exchange，提问作者Jaroslav Klimčík