Composer Module Installer Laravel Package

Getting Started

Minimal Steps for Laravel Developers Using SimpleSAMLphp

1. Install the Composer Plugin Globally (or project-specific):

   composer global require simplesamlphp/composer-module-installer
   

   OR add to your project’s composer.json:

   "extra": {
       "installer-paths": {
           "vendor/simplesamlphp/composer-module-installer": ["type:simplesamlphp-module"]
       }
   }
   

2. Ensure SimpleSAMLphp is Installed:

   composer require simplesaml/simplesamlphp
   

3. Install a Module:

   composer require vendor/simplesamlphp-module-mymodule
   

   Example: For the auth module:

   composer require simplesamlphp/simplesamlphp-module-auth
   

4. Verify Installation:

   • Check if the module appears in vendor/simplesamlphp/modules/mymodule/.
   • Ensure SimpleSAMLphp’s config.php includes the module in module.enable.

First Use Case: Adding a Third-Party Module

Scenario: You need to integrate a custom or third-party SimpleSAMLphp module (e.g., simplesamlphp-module-google-auth) into your Laravel app.

1. Add the Module via Composer:

   composer require simplesamlphp/simplesamlphp-module-google-auth
   

2. Enable the Module in SimpleSAMLphp: Edit config/config.php:

   'module.enable' => [
       'googleauth' => true,
       // ... other modules
   ],
   

3. Configure the Module: Update metadata/saml20-idp-hosted.php or module-specific configs in modules/googleauth/config.php.

4. Trigger Module Logic from Laravel: Use Laravel’s HTTP client or SimpleSAMLphp’s API:

   $response = Http::get('https://simplesamlphp.example.com/module.php/googleauth/auth.php');
   

Implementation Patterns

Workflow: Module Lifecycle in Laravel

1. Development:

   • Use dev-master for local testing:

     composer require vendor/simplesamlphp-module-mymodule:dev-master
     

   • Symlink modules for hot-reloading (optional):

     ln -s vendor/simplesamlphp/modules/mymodule modules/
     

2. Production:

   • Pin exact versions in composer.json:

     "require": {
         "simplesamlphp/simplesamlphp-module-auth": "1.0.0"
     }
     

   • Use composer install --optimize-autoloader for performance.

3. CI/CD:

   • Automate module installation in pipelines:

     # GitHub Actions example
     - run: composer require simplesamlphp/simplesamlphp-module-mymodule
     - run: php artisan simplesaml:modules:link  # Custom task to symlink modules
     

Integration Tips

1. Laravel-SimpleSAMLphp Bridge

Create a Laravel Service Provider to expose SimpleSAMLphp modules:

// app/Providers/SimpleSAMLServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use SimpleSAML\Module;

class SimpleSAMLServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('simplesaml.module', function () {
            return Module::load('mymodule');
        });
    }
}

2. Asset Modules

For modules with frontend assets (e.g., CSS/JS):

• Install via Composer:

  composer require simplesamlphp/simplesamlphp-assets-mymodule
  

• Copy assets to Laravel’s public/:

  cp -r vendor/simplesamlphp/assets/mymodule/* public/assets/mymodule/
  

• Add to Laravel’s config/app.php:

  'assets' => [
      'simplesaml' => 'assets/mymodule',
  ],
  

3. Custom Module Development

To create a Composer-installable module:

1. Structure your module:

   mymodule/
   ├── composer.json
   ├── Module.php
   └── config.php
   

2. Define composer.json:

   {
       "name": "vendor/simplesamlphp-module-mymodule",
       "type": "simplesamlphp-module",
       "require": {
           "simplesamlphp/composer-module-installer": "^1.4"
       },
       "extra": {
           "ssp-mixedcase-module-name": "MyModule"
       }
   }
   

3. Publish to Packagist or a private repo.

4. Private Modules

For internal modules, add a repositories entry in Laravel’s composer.json:

"repositories": [
    {
        "type": "path",
        "url": "../path/to/mymodule"
    }
],

Then install:

composer require vendor/simplesamlphp-module-mymodule:dev-master

Gotchas and Tips

Pitfalls

1. Module Naming Conflicts:

   • Composer enforces lowercase package names, but SimpleSAMLphp modules may use mixed case (e.g., MyModule).
   • Fix: Use the ssp-mixedcase-module-name extra in composer.json for backward compatibility.

2. Autoloading Issues:

   • SimpleSAMLphp modules use SimpleSAML\Module\* namespaces, which may conflict with Laravel’s SimpleSAML facade.
   • Fix: Explicitly namespace SimpleSAMLphp classes:

     use SimpleSAML\Module\MyModule\Module as MyModule;
     

3. Plugin Not Auto-Installed:

   • The plugin must be installed globally or explicitly required in the project’s composer.json:

     "require": {
         "simplesamlphp/composer-module-installer": "^1.4"
     }
     

4. Asset Module Paths:

   • Asset modules install to vendor/simplesamlphp/assets/, but Laravel expects public/.
   • Fix: Use a post-install script to copy assets:

     "scripts": {
         "post-install-cmd": [
             "php artisan simplesaml:assets:link"
         ]
     }
     

5. Composer 2.x Plugin System:

   • The plugin requires Composer ≥2.0. Older versions will fail.
   • Fix: Update Composer:

     composer self-update
     

Debugging

1. Module Not Installing:

   • Check Composer’s debug output:

     composer require vendor/module --verbose
     

   • Ensure the module’s composer.json has "type": "simplesamlphp-module".

2. Module Not Loading:

   • Verify the module directory exists:

     vendor/simplesamlphp/modules/mymodule/
     

   • Check SimpleSAMLphp’s config.php for module.enable.

3. Namespace Collisions:

   • Run composer dump-autoload to regenerate the autoloader.
   • Use composer why-not vendor/simplesamlphp/module to diagnose conflicts.

Tips

1. Laravel Artisan Commands: Create custom commands to manage modules:

   // app/Console/Commands/LinkSimpleSAMLModules.php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Symfony\Component\Process\Process;
   
   class LinkSimpleSAMLModules extends Command
   {
       protected $signature = 'simplesaml:modules:link';
       protected $description = 'Symlink SimpleSAMLphp modules';
   
       public function handle()
       {
           $process = new Process(['ln', '-sfn', 'vendor/simplesamlphp/modules/*', 'modules/']);
           $process->run();
           $this->info($process->getOutput());
       }
   }
   

2. Environment-Specific Modules: Use Composer’s environment variables to install different modules per environment:

   composer require --dev vendor/simplesamlphp-module-debug
   

3. Update Strategy:

   • Pin modules to specific versions in composer.json:

     "require": {
         "simplesamlphp/simplesamlphp-module-auth": "1.0.0"
     }
     

   • Use composer update vendor/module cautiously (test in staging first).

4. Fallback to Manual Installation: If Composer fails, manually install modules:

   git clone https://github.com/simplesamlphp/mymodule.git modules/mymodule
   

5. Monitor for Updates:

   • The package is no longer actively maintained (last release: 2023).
   • Mitigation: Fork the repository or monitor for community updates. Consider alternatives like [L