App Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require carloschininin/app-bundle
   

   Publish the bundle’s assets and configuration (if applicable):

   php artisan vendor:publish --provider="CarlosChininin\AppBundle\AppBundleServiceProvider"
   

2. First Use Case:

   • Check the config/app-bundle.php for core settings (e.g., default routes, middleware, or service bindings).
   • Register the bundle’s service provider in config/app.php under providers:

     CarlosChininin\AppBundle\AppBundleServiceProvider::class,
     

   • Run migrations (if included):

     php artisan migrate
     

3. Where to Look First:

   • Service Provider: vendor/carloschininin/app-bundle/src/AppBundleServiceProvider.php (entry point for bindings, routes, and events).
   • Configuration: config/app-bundle.php (customize defaults like route prefixes, middleware stacks).
   • Routes: Check for a routes/app-bundle.php file (if provided) or look for route registrations in the service provider.
   • Documentation: Review the README.md for setup instructions, features, and examples.

Implementation Patterns

Usage Patterns

1. Service Binding:

   • The bundle likely registers services (e.g., repositories, helpers) via the service container. Access them via dependency injection:

     use CarlosChininin\AppBundle\Services\ExampleService;
     
     class MyController extends Controller {
         public function __construct(private ExampleService $exampleService) {}
     }
     

2. Middleware Integration:

   • If the bundle includes middleware (e.g., for auth, logging), add it to your HTTP kernel:

     // app/Http/Kernel.php
     protected $middleware = [
         // ...
         \CarlosChininin\AppBundle\Http\Middleware\ExampleMiddleware::class,
     ];
     

3. Route Grouping:

   • Use the bundle’s route prefix (if configured) to group routes:

     Route::prefix(config('app-bundle.route_prefix'))->group(function () {
         Route::get('/example', [ExampleController::class, 'index']);
     });
     

4. Events and Listeners:

   • Listen to bundle-specific events (e.g., ExampleEvent) in your EventServiceProvider:

     protected $listen = [
         \CarlosChininin\AppBundle\Events\ExampleEvent::class => [
             \App\Listeners\HandleExampleEvent::class,
         ],
     ];
     

5. Blade Directives/Tags:

   • If the bundle adds Blade helpers, use them in views:

     @exampleDirective('argument')
     

Workflows

1. Extending Functionality:

   • Override bundle behaviors by publishing and modifying config/files:

     php artisan vendor:publish --tag="app-bundle-config"
     

   • Bind your custom implementations to the container (e.g., replace a service interface).

2. Testing:

   • Mock bundle services in tests:

     $this->app->instance(ExampleService::class, MockExampleService::class);
     

   • Use the bundle’s test helpers (if provided) in tests/TestCase.php.

3. Deployment:

   • Ensure the bundle’s assets (if any) are compiled:

     npm run dev  # or prod
     php artisan app-bundle:assets  # if CLI commands exist
     

Integration Tips

• Laravel Mix/Webpack: If the bundle includes assets, configure Mix to handle them in webpack.mix.js.
• Database: Check for migrations/seeds in database/migrations/ and run them post-install.
• API Resources: If the bundle provides API responses, extend them:

  namespace App\Http\Resources extends \CarlosChininin\AppBundle\Http\Resources;
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions:

   • The bundle may use namespaces like CarlosChininin\AppBundle. Avoid naming conflicts in your app (e.g., AppBundle class names).

2. Missing Configuration:

   • Some features may require explicit config. Check config/app-bundle.php for required keys (e.g., enabled: true).

3. Undocumented Dependencies:

   • The bundle might rely on Laravel features (e.g., Eloquent, Blade) or other packages. Verify compatibility with your Laravel version (e.g., 8.x, 9.x).

4. Route Conflicts:

   • If the bundle registers routes in routes/web.php or via the service provider, ensure they don’t clash with your existing routes.

5. Service Provider Loading Order:

   • If the bundle’s provider depends on other services (e.g., auth), load it after those providers in config/app.php.

Debugging

1. Log Output:

   • Enable debug mode (APP_DEBUG=true) and check Laravel logs (storage/logs/laravel.log) for bundle-related errors.

2. Service Binding Issues:

   • Use php artisan container:dump to inspect bindings and resolve missing service errors.

3. Route Debugging:

   • List all registered routes to spot bundle routes:

     php artisan route:list
     

4. Configuration Overrides:

   • Verify your published config isn’t being overridden by default values. Use config('app-bundle.key') to check runtime values.

Tips

1. Customization:

   • Extend bundle classes by creating child classes (e.g., App\Services\CustomExampleService extends \CarlosChininin\AppBundle\Services\ExampleService).

2. CLI Commands:

   • If the bundle includes Artisan commands (e.g., app-bundle:generate), list them with:

     php artisan list
     

3. Testing:

   • Use the --env=testing flag to test bundle features in isolation:

     php artisan test --env=testing
     

4. Performance:

   • If the bundle adds heavy middleware or services, profile with Laravel Debugbar or Xdebug.

5. Community:

   • Despite low stars, check the GitHub Issues tab for unresolved bugs or feature requests. Consider contributing fixes or documentation.