Getting Started

Minimal Setup

Installation

composer require soyuka/pmu

Add the service provider to config/app.php:

'providers' => [
    // ...
    Soyuka\Pmu\PmuServiceProvider::class,
],

Basic Configuration Publish the config file:
```
php artisan vendor:publish --provider="Soyuka\Pmu\PmuServiceProvider" --tag="pmu-config"
```
Update config/pmu.php with your monorepo structure (e.g., package paths, shared directories).

First Use Case: Package Autoloading Define a package in config/pmu.php:

'packages' => [
    'auth' => [
        'path' => base_path('packages/auth'),
        'autoload' => true,
    ],
],

Run:

php artisan pmu:autoload

Enable Plugins for Sub-Projects To leverage the new plugin system for sub-projects:
```
php artisan pmu:plugins:enable auth
```
This allows extending functionality of individual packages via plugins (e.g., custom middleware, providers, or commands).

Implementation Patterns

Workflow: Package Development

Isolated Development Use pmu:serve to spin up a local server for a specific package:
```
php artisan pmu:serve auth
```
- Maps http://localhost:8000/auth to packages/auth/public.

Shared Dependencies Define shared directories in config/pmu.php:

'shared' => [
    'config' => base_path('shared/config'),
    'resources' => base_path('shared/resources'),
],

Access shared files via pmu:share:link:
```
php artisan pmu:share:link
```

Task Automation Create custom tasks in app/Console/Commands/Pmu*:

namespace App\Console\Commands;
use Soyuka\Pmu\Console\PmuCommand;

class BuildAuth extends PmuCommand {
    protected $signature = 'pmu:build:auth';
    protected $description = 'Build Auth package assets';

    public function handle() {
        $this->call('vendor:publish', ['--provider' => 'AuthServiceProvider']);
        $this->call('mix');
    }
}

Plugin Integration Develop plugins for a specific package (e.g., auth):
- Place plugin files in packages/auth/plugins/ (e.g., packages/auth/plugins/Logging/).
- Register plugins in config/pmu.php:
```
'plugins' => [
    'auth' => [
        'Logging' => base_path('packages/auth/plugins/Logging'),
    ],
],
```
- Enable plugins for a package:
```
php artisan pmu:plugins:enable auth Logging
```

Integration Tips

Laravel Mix/Vite: Extend webpack.mix.js to support package-specific builds:

const mix = require('laravel-mix');
const pmu = require('soyuka/pmu/mix');

pmu.packages(['auth', 'dashboard']).forEach(pkg => {
    mix.setPublicPath(`packages/${pkg}/public`);
    mix.js(`packages/${pkg}/resources/js/app.js`, `packages/${pkg}/public/js`);
});

Route Isolation: Use middleware to scope routes:

Route::prefix('auth')->middleware(['web', 'pmu.auth'])->group(function () {
    // Auth package routes
});

Plugin Middleware: Register plugin-specific middleware in app/Http/Kernel.php:

protected $routeMiddleware = [
    // ...
    'pmu.plugin.logging' => \Soyuka\Pmu\Plugins\LoggingMiddleware::class,
];

Gotchas and Tips

Pitfalls

Caching Quirks
- Clear cached configs after changing config/pmu.php:
```
php artisan config:clear
```
- Autoload caches may persist; run composer dump-autoload after structural changes.
- Plugin Caching: After enabling/disabling plugins, clear the plugin cache:
```
php artisan pmu:plugins:clear
```
Path Resolution
- Use pmu_path('auth') instead of hardcoding paths (e.g., base_path('packages/auth')).
- Shared directories take precedence over package-specific ones; verify with:
```
php artisan pmu:debug
```
- Plugin Paths: Ensure plugin directories are correctly defined in config/pmu.php to avoid "Plugin not found" errors.
Middleware Conflicts
- Ensure package-specific middleware (e.g., pmu.auth) doesn’t override global middleware. Test with:
```
php artisan route:list | grep auth
```
- Plugin Middleware: Avoid naming conflicts with existing middleware by prefixing plugin middleware with pmu.plugin.<plugin-name>.

Plugin Loading Order

Plugins are loaded in alphabetical order by default. Use the priority key in config/pmu.php to control loading order:

'plugins' => [
    'auth' => [
        'Logging' => [
            'path' => base_path('packages/auth/plugins/Logging'),
            'priority' => 10, // Lower numbers load first
        ],
    ],
],

Debugging

Log Package Events: Enable debug mode in config/pmu.php:
```
'debug' => env('PMU_DEBUG', false),
```
Check logs at storage/logs/pmu.log.
Validate Structure: Run php artisan pmu:validate to ensure package directories conform to expectations.
- Plugin Validation: Use php artisan pmu:plugins:validate auth to check plugin configurations.
Plugin Debugging: Enable plugin-specific debugging:
```
php artisan pmu:plugins:debug auth
```

Extension Points

Custom Commands Extend Soyuka\Pmu\Console\PmuCommand for package-specific tasks (e.g., pmu:deploy:auth).
- Plugin Commands: Create plugin-specific commands by extending Soyuka\Pmu\Console\PluginCommand.

Dynamic Configuration Override package configs at runtime:

pmu()->extend('auth', function ($config) {
    $config['namespace'] = 'Auth\\Package';
    return $config;
});

Plugin Configs: Extend plugin configurations dynamically:

pmu()->plugin('auth')->extend('Logging', function ($config) {
    $config['log_level'] = 'debug';
    return $config;
});

Package Discovery Dynamically register packages via service providers:

public function register() {
    pmu()->discover(base_path('packages/*/provider.php'));
}

Plugin Discovery: Discover plugins dynamically:

pmu()->plugins()->discover(base_path('packages/*/plugins/*'));

Plugin Development Create reusable plugins for multiple packages:
- Place plugin skeletons in vendor/soyuka/pmu/plugins/ (for shared use).
- Publish plugin templates:
```
php artisan pmu:plugins:publish
```
- Customize plugin templates in resources/views/vendor/pmu/plugins/.

Pmu Laravel Package