Core Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the bundle via Composer in your Laravel project:

   composer require admc/core-bundle
   

   Register the bundle in config/app.php under the extra.bundles key:

   'bundles' => [
       Admc\CoreBundle\AdmcCoreBundle::class => ['all' => true],
   ],
   

2. Publish Assets (if applicable) Run the following command to publish any config or assets:

   php artisan vendor:publish --provider="Admc\CoreBundle\AdmcCoreBundle"
   

3. First Use Case: Basic Configuration Check the published config file (if any) at config/admc_core.php and adjust settings as needed. Example:

   return [
       'debug_mode' => env('APP_DEBUG', false),
       'default_locale' => 'en',
   ];
   

4. Service Provider & Facades Verify the service provider is auto-loaded. If not, manually register it in config/app.php:

   'providers' => [
       Admc\CoreBundle\AdmcCoreServiceProvider::class,
   ],
   

   Use the facade (if provided) in your code:

   use Admc\CoreBundle\Facades\AdmcCore;
   
   $result = AdmcCore::doSomething();
   

Implementation Patterns

Common Workflows

1. Dependency Injection Inject the bundle’s services into controllers, commands, or other classes:

   use Admc\CoreBundle\Services\SomeService;
   
   class MyController extends Controller
   {
       public function __construct(private SomeService $someService) {}
   
       public function index()
       {
           $data = $this->someService->fetchData();
       }
   }
   

2. Event Listeners & Subscribers Listen to custom events fired by the bundle. Example in EventServiceProvider:

   protected $listen = [
       'Admc\CoreBundle\Events\SomeEvent' => [
           'App\Listeners\HandleSomeEvent',
       ],
   ];
   

3. Middleware Integration Use the bundle’s middleware in routes or HTTP kernel:

   Route::middleware(['admc.core.middleware'])->group(function () {
       // Routes requiring the middleware
   });
   

4. Console Commands Extend or use the bundle’s commands:

   php artisan admc:core:command-name
   

   Or create custom commands leveraging its services.

5. Blade Directives (if applicable) Register and use custom Blade directives:

   Blade::directive('admcDirective', function () {
       return "<?php echo AdmcCore::directiveContent(); ?>";
   });
   

   Usage in Blade:

   @admcDirective
   

Integration Tips

• Leverage Service Container Bind custom interfaces to the bundle’s concrete classes in AppServiceProvider:

  $this->app->bind(
      Admc\CoreBundle\Contracts\SomeInterface::class,
      Admc\CoreBundle\Services\SomeService::class
  );
  

• Configuration Overrides Override default config values via environment variables or config/admc_core.php:

  'api_url' => env('ADMC_CORE_API_URL', 'https://default.url'),
  

• Testing Mock the bundle’s services in PHPUnit tests:

  $this->mock(Admc\CoreBundle\Services\SomeService::class)
       ->shouldReceive('fetchData')
       ->andReturn(['test' => 'data']);
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions Ensure the bundle’s namespaces (e.g., Admc\CoreBundle) do not conflict with your project’s namespaces. Use fully qualified names (e.g., \Admc\CoreBundle\...) to avoid ambiguity.

2. Missing Auto-Loading If the bundle isn’t auto-discovered, manually register the service provider and facade aliases in config/app.php.

3. Configuration Caching After modifying config/admc_core.php, clear the config cache:

   php artisan config:clear
   

4. Debugging Enable debug mode in config/admc_core.php to log detailed errors:

   'debug_mode' => true,
   

   Check logs at storage/logs/laravel.log.

5. Database Migrations If the bundle includes migrations, run them after installation:

   php artisan migrate
   

Tips

1. Extend Core Functionality Create custom classes that extend the bundle’s base classes. Example:

   use Admc\CoreBundle\Base\SomeBaseClass;
   
   class CustomClass extends SomeBaseClass
   {
       public function customMethod()
       {
           // Extend logic
       }
   }
   

2. Localization If the bundle supports localization, publish and translate its language files:

   php artisan vendor:publish --tag=admc-core-translations
   

3. Performance Lazy-load heavy services or defer initialization until needed:

   $service = app()->makeWith(Admc\CoreBundle\Services\HeavyService::class, [
       'lazy' => true,
   ]);
   

4. Documentation Since the bundle lacks stars/dependents, refer to its README.md or source code for undocumented features. Example:

   grep -r "TODO" ./vendor/admc/core-bundle
   

5. Community Support Open an issue on the GitHub repository for feature requests or bugs. Example issue template:

   **Bug Report**
   - Version: [e.g., 1.0]
   - Description: [Clear description of the issue]
   - Steps to Reproduce:
     1. [First step]
     2. [Second step]
   - Expected Behavior: [What you expected to happen]
   - Actual Behavior: [What actually happened]