Framework Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require bungle-suit/framework-bundle
   

   Publish the bundle's configuration (if applicable):

   php artisan vendor:publish --provider="Bungle\Bundle\FrameworkBundle\FrameworkBundleServiceProvider"
   

2. First Use Case Register the service provider in config/app.php under providers:

   Bungle\FrameworkBundle\FrameworkBundleServiceProvider::class,
   

3. Initial Configuration Check config/framework.php (auto-generated if published) for core settings like:

   • Default middleware
   • Route prefixes
   • Service bindings

4. Basic Usage Trigger the framework's core functionality (e.g., bootstrapping) via:

   use Bungle\FrameworkBundle\Facades\Framework;
   
   // Example: Register a custom route group
   Framework::routeGroup(['prefix' => 'api/v1'], function () {
       // Routes here
   });
   

Implementation Patterns

Core Workflows

1. Middleware Integration Extend Laravel's middleware stack by binding Bungle-specific middleware:

   // In a service provider
   $this->app->extend('middleware', function ($middleware) {
       return array_merge($middleware, [
           \Bungle\FrameworkBundle\Http\Middleware\Authenticate::class,
       ]);
   });
   

2. Service Binding Bind custom services to the container:

   $this->app->singleton('bungle.logger', function () {
       return new \Bungle\FrameworkBundle\Services\LoggerService();
   });
   

3. Route Grouping Use Bungle's route grouping for modularity:

   Framework::routeGroup(['namespace' => 'App\Http\Controllers\Admin'], function () {
       Route::get('/dashboard', 'DashboardController@index');
   });
   

4. Event Listeners Subscribe to Bungle events (e.g., FrameworkInitialized):

   event(new \Bungle\FrameworkBundle\Events\FrameworkInitialized());
   

Integration Tips

• Laravel Mix/Inertia: Use Bungle's asset pipeline helpers (if available) alongside Laravel Mix:

  Framework::asset('js/app.js')->version('1.0.0');
  

• API Resources: Extend Bungle's Resource class for API responses:

  class UserResource extends \Bungle\FrameworkBundle\Http\Resources\Resource
  {
      public function toArray($request)
      {
          return ['name' => $this->resource->name];
      }
  }
  

• Testing: Mock Bungle services in PHPUnit:

  $this->app->instance('bungle.logger', Mockery::mock());
  
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Avoid overwriting config/framework.php directly; use environment variables or the config() helper:

     config(['framework.default_locale' => env('APP_LOCALE', 'en')]);
     

   • Debug Tip: Clear config cache after changes:

     php artisan config:clear
     

2. Middleware Conflicts

   • Bungle middleware may clash with Laravel's. Use unless/only guards:

     Route::middleware(['bungle.auth', 'web'])->group(...);
     

3. Service Provider Boot Order

   • Ensure FrameworkBundleServiceProvider loads after Laravel's core providers (e.g., RouteServiceProvider):

     // In app.php
     'providers' => [
         // Laravel providers...
         Bungle\FrameworkBundle\FrameworkBundleServiceProvider::class,
     ],
     

4. Deprecated Methods

   • Check for @deprecated tags in the source. Example:

     // Avoid this (deprecated)
     Framework::oldMethod();
     
     // Use instead:
     Framework::newMethod();
     

Debugging

• Log Dumping: Enable Bungle's debug logs:

  config(['framework.debug' => true]);
  

• Route Debugging: List all registered Bungle routes:

  php artisan route:list --bungle
  

• Service Dumping: Inspect container bindings:

  dd(app()->getBindings());
  

Extension Points

1. Custom Directives Extend Blade directives via Bungle's Directive class:

   Framework::directive('bungleDirective', function ($expression) {
       return "<?php echo Bungle\\Helpers::process({$expression}); ?>";
   });
   

2. Hooks Use Bungle's Framework::hook() to tap into lifecycle events:

   Framework::hook('beforeBoot', function () {
       // Run code before framework boots
   });
   

3. Asset Pipeline Override default asset paths:

   Framework::asset('css/app.css')->setPath(public_path('custom/css/app.css'));
   

4. Testing Helpers Use Bungle's testing traits:

   use Bungle\FrameworkBundle\Testing\TestCase;
   
   class MyTest extends TestCase
   {
       public function testSomething()
       {
           $this->actingAsBungleUser();
           // ...
       }
   }