Resource Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bkstg/resource-bundle
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Bkstg\ResourceBundle\ResourceBundleServiceProvider::class,
   ],
   

2. First Use Case: Bundling Resources Define a bundle in a dedicated class (e.g., app/Bundles/MyBundle.php):

   namespace App\Bundles;
   
   use Bkstg\ResourceBundle\Bundle;
   
   class MyBundle extends Bundle
   {
       public function getResources()
       {
           return [
               'views' => resource_path('views/my-bundle'),
               'public' => public_path('bundles/my-bundle'),
           ];
       }
   }
   

3. Register the Bundle In a service provider (e.g., AppServiceProvider):

   public function boot()
   {
       $this->app->make(\Bkstg\ResourceBundle\ResourceBundleManager::class)
           ->registerBundle(new \App\Bundles\MyBundle());
   }
   

4. Publish Resources Run the bundle publisher:

   php artisan bundle:publish MyBundle
   

Implementation Patterns

Workflow: Modular Resource Management

1. Bundle Structure Organize resources per bundle (e.g., resources/bundles/my-bundle/views, resources/bundles/my-bundle/public). Use getResources() to map paths to publish locations.

2. Dynamic Registration Register bundles dynamically in boot():

   $manager = $this->app->make(ResourceBundleManager::class);
   $manager->registerBundle(new MyBundle());
   $manager->registerBundle(new AdminBundle());
   

3. Conditional Publishing Use tags or environments to control publishing:

   if (app()->environment('local')) {
       $manager->publishBundle('MyBundle', ['--tag' => 'dev']);
   }
   

4. Integration with Laravel Mix Extend webpack.mix.js to handle bundle-specific assets:

   mix.js('resources/bundles/my-bundle/js/app.js', 'public/bundles/my-bundle/js')
       .sass('resources/bundles/my-bundle/scss/app.scss', 'public/bundles/my-bundle/css');
   

5. View Overrides Override bundle views by publishing to resources/views/vendor/bundles/my-bundle:

   $manager->publishBundle('MyBundle', ['--views' => true]);
   

Gotchas and Tips

Pitfalls

1. Path Conflicts Avoid overlapping publish paths (e.g., two bundles publishing to public/js). Use unique subdirectories:

   return ['public' => public_path('bundles/my-bundle/assets')];
   

2. Caching Issues Clear config and compiled views after publishing:

   php artisan config:clear
   php artisan view:clear
   

3. Missing Readme The package lacks documentation. Refer to the source code for undocumented methods (e.g., ResourceBundleManager::getPublishedBundles()).

4. Artisan Command Quirks The bundle:publish command may not handle symlinks. Use absolute paths in getResources():

   return ['views' => realpath(resource_path('views/my-bundle'))];
   

Tips

1. Extension Points Override Bkstg\ResourceBundle\Bundle to add custom logic (e.g., pre-publish hooks):

   public function beforePublish()
   {
       // Minify CSS/JS before publishing
   }
   

2. Debugging Enable verbose output for the publish command:

   php artisan bundle:publish MyBundle --verbose
   

3. Configuration No built-in config file exists. Use environment variables or a custom config file:

   config(['bundles.default_namespace' => 'App\Bundles']);
   

4. Testing Mock the ResourceBundleManager in tests:

   $manager = Mockery::mock(ResourceBundleManager::class);
   $manager->shouldReceive('registerBundle')->once();
   $this->app->instance(ResourceBundleManager::class, $manager);
   

5. Performance For large bundles, use --force to skip existence checks:

   php artisan bundle:publish MyBundle --force