Unified Asset Installer Laravel Package

Getting Started

Minimal Steps

1. Install the Package Add the package to your project's composer.json under require-dev (if used for development):

   "require-dev": {
       "phpdocumentor/unified-asset-installer": "*"
   }
   

   Run composer update.

2. Define a Template or Plugin Create a composer.json for your template or plugin with the correct type:

   {
       "name": "your-vendor/template-yourname",
       "type": "phpdocumentor-template",
       "require": {
           "phpdocumentor/unified-asset-installer": "*"
       }
   }
   

3. Trigger Installation Run composer install or composer update. The installer will automatically place template files in /data/template (or equivalent) instead of /vendor.

First Use Case

Installing a Custom phpDocumentor Template

• Clone or download a template repository (e.g., phpdocumentor/template-custom).
• Ensure its composer.json includes "type": "phpdocumentor-template".
• Run composer install in your project root. The template assets will now be installed in /data/template (configurable via config.phpDocumentor.php or environment variables).

Implementation Patterns

Workflow Integration

1. Template Development

   • Develop templates/plugins locally, then distribute via Packagist or private repositories.
   • Use "type": "phpdocumentor-template" (or future "phpdocumentor-plugin") to trigger custom installation.

2. Project Setup

   • In your Laravel project, add the template as a dependency in composer.json:

     "require-dev": {
         "your-vendor/template-yourname": "*"
     }
     

   • Run composer install to install assets to /data/template.

3. Configuration

   • Configure phpDocumentor to use the installed template via:

     // config/phpDocumentor.php
     return [
         'template' => 'yourname',
         'template_dir' => base_path('data/template'),
     ];
     

4. Automation

   • Use composer post-install-cmd or post-update-cmd to ensure assets are installed after dependency updates:

     "scripts": {
         "post-install-cmd": [
             "phpdocumentor install-template"
         ],
         "post-update-cmd": [
             "phpdocumentor install-template"
         ]
     }
     

Laravel-Specific Tips

1. Publish Assets Create a custom Artisan command to symlink or publish template assets to a Laravel-accessible location (e.g., public/docs):

   php artisan vendor:publish --tag=phpdocumentor-assets
   

2. Service Provider Register a service provider to dynamically load phpDocumentor configurations:

   // app/Providers/PHPDocumentorServiceProvider.php
   public function boot()
   {
       $this->app->singleton('phpdocumentor.config', function () {
           return require base_path('config/phpDocumentor.php');
       });
   }
   

3. Testing Use Laravel’s Artisan::call() to test template installation in PHPUnit:

   public function testTemplateInstallation()
   {
       Artisan::call('composer:install', ['--dev' => true]);
       $this->assertFileExists(base_path('data/template/yourname'));
   }
   

Gotchas and Tips

Pitfalls

1. Composer Bug Workaround

   • The installer name must be alphabetically after "template" in composer.json due to Composer issue #655.
   • Example: Use "phpdocumentor/unified-asset-installer-z" if needed (though the current name works).

2. Directory Permissions

   • Ensure /data/template (or custom path) is writable by the web server:

     mkdir -p data/template && chmod -R 755 data/template
     

3. Missing type Field

   • Forgetting "type": "phpdocumentor-template" will cause assets to install in /vendor instead of the custom location.

4. Archived Package

   • The package is archived but still functional. Monitor for updates or forks if critical.

Debugging

1. Verify Installation Check if assets are installed correctly:

   ls data/template
   

   If empty, run composer dump-autoload or clear Composer’s cache:

   composer clear-cache
   

2. Composer Debug Mode Enable verbose output to diagnose issues:

   composer install -v
   

3. Custom Installer Logging Add debug logs to the installer (if extending):

   // In a custom installer class
   file_put_contents(
       storage_path('logs/phpdocumentor-installer.log'),
       'Debug message: ' . print_r($event, true),
       FILE_APPEND
   );
   

Extension Points

1. Custom Paths Override the default /data/template path via:

   • Environment variable: PHP_DOCUMENTOR_TEMPLATE_DIR=/custom/path
   • Config file: Add 'template_dir' => env('CUSTOM_TEMPLATE_DIR') to config/phpDocumentor.php.

2. Plugin Support The TODO in the README suggests future "phpdocumentor-plugin" support. Monitor for updates or implement a similar installer for plugins.

3. Laravel Mix/Webpack If using Laravel Mix, exclude /data/template from processing to avoid conflicts:

   // webpack.mix.js
   mix.exclude('data/template');
   

4. Post-Install Hooks Extend the installer to run additional commands (e.g., symlinking):

   // In a custom installer class
   public function install($composer)
   {
       $this->postInstallScript = 'php artisan phpdocumentor:link-assets';
       parent::install($composer);
   }