Custom Assets Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require adrenalinkin/custom-assets-bundle in your Laravel project root. (Note: The package is Symfony-based, but Laravel can integrate it via composer require and manual kernel registration.)

2. Register the Bundle Add the bundle to config/app.php under the providers array:

   Linkin\Bundle\CustomAssetsBundle\LinkinCustomAssetsBundle::class,
   

   (Laravel 5.5+ uses autoloading, so no AppKernel.php is needed.)

3. Publish Configuration Run php artisan vendor:publish --provider="Linkin\Bundle\CustomAssetsBundle\LinkinCustomAssetsBundle" --tag="config" to publish the default YAML config to config/custom_assets.yaml.

4. Configure Sources Edit config/custom_assets.yaml to define your custom asset sources:

   paths:
       - { from: 'resources/custom-assets', to: 'custom_assets' }
   

   (Maps a local folder to public/custom_assets.)

5. Install Assets Run php artisan custom:assets:install to copy assets to the public directory.

First Use Case

Scenario: You need to bundle third-party assets (e.g., vendor JS/CSS, custom fonts, or legacy files) into your Laravel project without manual copying.

Workflow:

1. Place assets in resources/custom-assets (or your configured from path).
2. Run php artisan custom:assets:install.
3. Access assets via /custom_assets/... in your app.

Implementation Patterns

Workflows

1. Development Workflow

   • Use php artisan custom:assets:install --watch (if supported) to auto-sync changes during development.
   • (Note: The package lacks a --watch flag; consider symlinking for live updates: ln -s resources/custom-assets public/custom_assets.)

2. CI/CD Integration

   • Add php artisan custom:assets:install to your deployment script (e.g., deploy.php or GitHub Actions).
   • Example (Laravel Forge/Envoyer):

     php artisan config:clear && php artisan custom:assets:install --no-interaction
     

3. Dynamic Asset Loading

   • Use Laravel’s mix() or asset() helpers to reference copied files:

     <link href="{{ asset('custom_assets/css/vendor.css') }}" rel="stylesheet">
     

Integration Tips

• Symfony-Laravel Bridge:

  • Override the Symfony command in app/Console/Kernel.php to add Laravel-specific logic:

    protected function commands()
    {
        $this->load(__DIR__.'/../../vendor/adrenalinkin/custom-assets-bundle/src/Command');
        $this->commands([
            \App\Console\Commands\CustomAssetsCommand::class, // Custom wrapper
        ]);
    }
    

• Asset Versioning:

  • Append a cache-busting query string to copied assets:

    # config/custom_assets.yaml
    version: '{{ env("ASSET_VERSION", "1.0") }}'
    paths:
        - { from: 'resources/custom-assets', to: 'custom_assets/v{{ version }}' }
    

• Excluding Files:

  • Use .gitignore-style patterns in the config to skip files:

    paths:
        - { from: 'resources/custom-assets', to: 'custom_assets', exclude: ['*.log', 'temp/'] }
    

Gotchas and Tips

Pitfalls

1. Laravel-Symfony Mismatch

   • The bundle assumes Symfony’s Kernel and Container. If you encounter errors:
     • Mock the Symfony Filesystem or Finder in a service provider:

       use Symfony\Component\Filesystem\Filesystem;
       $this->app->singleton(Filesystem::class, function () {
           return new Filesystem();
       });
       

2. Permission Issues

   • Ensure public/custom_assets is writable:

     chmod -R 755 public/custom_assets
     

   • (Laravel’s storage:link may conflict; run php artisan storage:link first.)

3. YAML Configuration Quirks

   • Indentation must be spaces (not tabs) in custom_assets.yaml.
   • Boolean values require true/false (not yes/no).

4. Overwriting Existing Files

   • The bundle overwrites files by default. To merge changes:
     • Use a custom command extending \Linkin\Bundle\CustomAssetsBundle\Command\InstallCommand and implement incremental sync logic.

Debugging

• Dry Run Mode:

  • Add --dry-run to the command to preview changes without copying:

    php artisan custom:assets:install --dry-run
    

• Verbose Output:

  • Use -v for detailed logs:

    php artisan custom:assets:install -v
    

Extension Points

1. Custom Command Logic

   • Extend the install command to add pre/post hooks:

     namespace App\Console\Commands;
     use Linkin\Bundle\CustomAssetsBundle\Command\InstallCommand as BaseInstallCommand;
     
     class CustomAssetsInstallCommand extends BaseInstallCommand
     {
         protected function execute(InputInterface $input, OutputInterface $output)
         {
             // Add logic before/after asset copy
             parent::execute($input, $output);
         }
     }
     

2. Dynamic Path Resolution

   • Override path resolution in a service provider:

     $this->app->extend('custom_assets.path_resolver', function () {
         return new \App\Services\CustomPathResolver();
     });
     

3. Asset Processing

   • Hook into the copy process to minify/optimize assets:

     # config/custom_assets.yaml
     processors:
         - { type: 'css', command: 'php artisan vendor:publish --tag=laravel-mix' }