Fractor Extension Installer Laravel Package

Getting Started

Minimal Steps

1. Install the Package Add the package to your Laravel project via Composer:

   composer require --dev a9f/fractor-extension-installer
   

   Note: Avoid using --no-scripts as the installer relies on Composer script events.

2. Verify Composer Scripts Ensure your composer.json includes the post-autoload-dump script (default for Fractor extensions):

   {
       "scripts": {
           "post-autoload-dump": [
               "Fractor\\ExtensionInstaller\\Composer\\ScriptHandler::installExtensions"
           ]
       }
   }
   

3. First Use Case: Installing a Fractor Extension Require a Fractor extension (e.g., vendor/fractor-extension):

   composer require --dev vendor/fractor-extension
   

   The installer will automatically detect and install the extension during composer install or composer update.

Implementation Patterns

Workflow Integration

1. Extension Development

   • Set the Composer package type to fractor-extension in the extension’s composer.json:

     {
         "type": "fractor-extension",
         "extra": {
             "fractor": {
                 "includes": ["config/*.php", "src/**/*.php"]
             }
         }
     }
     

   • Define includes in the extra.fractor section to specify files/directories to publish.

2. Laravel Project Setup

   • Use the extension in your project’s fractor.php config (if applicable) or leverage its functionality via service providers/services.
   • Example: Publish extension config (if included):

     php artisan vendor:publish --provider="Vendor\\FractorExtension\\FractorExtensionServiceProvider"
     

3. Automated Extension Management

   • Extensions are installed during Composer operations (no manual steps required).
   • Update extensions via:

     composer update vendor/fractor-extension
     

Laravel-Specific Tips

• Service Provider Binding If the extension includes a service provider, bind it in your config/app.php:

  'providers' => [
      // ...
      Vendor\FractorExtension\FractorExtensionServiceProvider::class,
  ],
  

• Configuration Publishing Use Laravel’s vendor:publish to publish extension configs:

  php artisan vendor:publish --tag="fractor-extension-config"
  

Gotchas and Tips

Pitfalls

1. Composer Scripts Disabled

   • Issue: Using composer install --no-scripts or composer update --no-scripts will skip extension installation.
   • Fix: Avoid --no-scripts or manually trigger the script:

     composer install && composer run-script post-autoload-dump
     

2. Missing extra.fractor Configuration

   • Issue: Extensions without extra.fractor.includes may not publish files correctly.
   • Fix: Ensure the extension’s composer.json includes the fractor key with includes.

3. Extension Dependencies

   • Issue: Extensions with unresolved dependencies may fail silently.
   • Fix: Run composer validate to check for dependency issues.

Debugging

• Check Script Execution Enable Composer’s debug mode to verify script execution:

  COMPOSER_DEBUG=1 composer install
  

• Log Output The installer logs to stderr; redirect to a file for debugging:

  composer install 2> composer-debug.log
  

Extension Points

1. Custom Script Hooks Extend the installer by adding custom scripts to composer.json:

   {
       "scripts": {
           "post-install-cmd": [
               "Fractor\\ExtensionInstaller\\Composer\\ScriptHandler::installExtensions"
           ]
       }
   }
   

2. Conditional Installation Use Composer’s minimum-stability or conflict constraints to control extension installation contexts.

Laravel-Specific Quirks

• Artisan Command Conflicts If the extension includes Artisan commands, ensure namespace collisions are avoided by prefixing commands (e.g., fractor:extension-command).
• Configuration Caching Clear Laravel’s config cache after installing/updating extensions:

  php artisan config:clear