Resource Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/resource-bundle
   

   (Note: As of writing, the README lacks installation instructions—verify composer.json for exact requirements.)

2. Basic Usage Register the service provider in config/app.php under providers:

   Ekyna\ResourceBundle\ResourceBundleServiceProvider::class,
   

3. First Use Case Load a resource bundle via a facade (if provided) or service container:

   $bundle = app('resource-bundle')->load('path/to/bundle');
   

   (Check for a ResourceBundle facade or helper methods in the package.)

4. Locate Documentation

   • Inspect the src/ directory for core classes (e.g., ResourceBundleManager, BundleLoader).
   • Check for tests in tests/ for usage examples.
   • Monitor GitHub issues for community patterns.

Implementation Patterns

Core Workflows

1. Bundle Registration Define bundles in config/resource-bundle.php (if auto-generated):

   'bundles' => [
       'admin' => [
           'path' => resource_path('bundles/admin'),
           'namespace' => 'Admin\\',
       ],
   ],
   

2. Dynamic Loading Load bundles programmatically:

   $bundle = app('resource-bundle')->get('admin');
   $translations = $bundle->get('messages.welcome');
   

3. Integration with Laravel Features

   • Views: Pass bundles to Blade:

     @inject('bundle', 'Ekyna\ResourceBundle\ResourceBundle')
     {{ $bundle->get('admin')->get('title') }}
     

   • API Responses: Attach bundle data to JSON:

     return response()->json(['title' => $bundle->get('admin')->get('title')]);
     

4. Custom Bundle Types Extend Ekyna\ResourceBundle\Contracts\BundleInterface for non-standard formats (e.g., JSON, YAML):

   class CustomBundle implements BundleInterface {
       public function get($key) { ... }
   }
   

Common Use Cases

• Localization: Replace Laravel’s built-in trans() with bundle-aware calls.
• Configuration: Store app settings in bundles (e.g., config/bundles/settings.php).
• Theming: Load theme-specific assets (CSS/JS) via bundles.

Gotchas and Tips

Pitfalls

1. Missing Installation Docs

   • The TODO in README.md suggests incomplete setup. Verify:
     • Service provider registration.
     • Required config files (e.g., config/resource-bundle.php).
     • Publisher scripts (if any) for migrations/views.

2. Namespace Collisions

   • Bundles with overlapping namespaces may cause autoloading issues. Use unique prefixes:

     'bundles' => [
         'vendor.prefix.admin' => [...],
     ],
     

3. Caching Quirks

   • If bundles are cached, clear config after changes:

     php artisan config:clear
     

Debugging

• Bundle Not Found? Check if the bundle path exists and is registered in config. Enable debug mode:

  app('resource-bundle')->setDebug(true);
  

• Key Not Resolving? Verify the bundle’s structure matches the key path (e.g., messages.welcome → messages/welcome.php).

Extension Points

1. Custom Loaders Implement Ekyna\ResourceBundle\Contracts\LoaderInterface for non-file sources (e.g., database):

   class DatabaseLoader implements LoaderInterface {
       public function load($bundleName) { ... }
   }
   

2. Event Hooks Listen for bundle events (if the package supports them):

   event(new BundleLoaded('admin'));
   

3. Testing Mock bundles in tests:

   $this->app->instance('resource-bundle', MockBundle::class);
   

Pro Tips

• Bundle Auto-Discovery Scan a directory for bundles dynamically:

  $bundles = app('resource-bundle')->discover(resource_path('bundles/*'));
  

• Fallback Chains Configure fallback bundles for missing keys:

  'fallbacks' => ['admin' => ['default']],