Component Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require thrace/component-bundle
   

   Register the bundle in config/app.php under providers:

   Thrace\ComponentBundle\ThraceComponentBundle::class,
   

2. First Use Case Check the src/Resources/views/ directory for available Blade components. For example, if the bundle includes a Card component, use it in a Blade template:

   @component('thrace::card', ['title' => 'Sample Card'])
       <p>This is a sample card component.</p>
   @endcomponent
   

3. Configuration Review config/thrace.php (if provided) or check the bundle’s service provider for default settings. Override defaults in config/app.php or a custom config file.

Implementation Patterns

Common Workflows

1. Component Integration

   • Blade Components: Use @component('thrace::component-name') syntax for reusable UI elements.
   • Dynamic Data: Pass data via attributes:

     @component('thrace::alert', ['type' => 'success', 'message' => 'Operation completed'])
     @endcomponent
     

   • Slots: If components support slots (e.g., for content), use:

     @component('thrace::container')
         <div>Slot content here</div>
     @endcomponent
     

2. Service Integration

   • If the bundle provides services (e.g., Thrace\ComponentBundle\Services\ExampleService), bind them in the service container:

     $this->app->bind('thrace.example', function ($app) {
         return new \Thrace\ComponentBundle\Services\ExampleService();
     });
     

   • Use dependency injection in controllers:

     public function __construct(private ExampleService $exampleService) {}
     

3. Asset Management

   • Check for published assets (CSS/JS) via:

     php artisan vendor:publish --provider="Thrace\ComponentBundle\ThraceComponentBundle" --tag=public
     

   • Include assets in your layout:

     @vite(['resources/css/thrace.css', 'resources/js/thrace.js'])
     

4. Configuration Overrides

   • Publish the config file:

     php artisan vendor:publish --provider="Thrace\ComponentBundle\ThraceComponentBundle" --tag=config
     

   • Customize in config/thrace.php:

     'default_theme' => 'dark',
     

Best Practices

• Namespace Clarity: Prefix component names with thrace:: to avoid conflicts (e.g., @component('thrace::button')).
• Fallbacks: Use @includeIf for optional components:

  @includeIf(config('thrace.show_footer'), 'thrace::footer')
  

• Testing: Mock bundle services in unit tests:

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

Gotchas and Tips

Pitfalls

1. Under Development

   • The bundle is not production-ready. Expect breaking changes; avoid in critical projects.
   • Check the GitHub issues for unresolved bugs.

2. Component Discovery

   • Components may not auto-discover. Manually include them in Blade files or use a view composer:

     View::composer('*', function ($view) {
         if (str_contains($view->getName(), 'thrace::')) {
             // Pre-process component data
         }
     });
     

3. Asset Conflicts

   • Published assets (CSS/JS) might clash with existing assets. Audit public/vendor/thrace/ after publishing.

4. Configuration Quirks

   • No default config file exists (as of readme maturity). Assume hardcoded defaults or check the provider.

5. Dependency Hell

   • The bundle has no dependents, meaning it may rely on unpublished Thrace-specific packages. Test thoroughly.

Debugging Tips

• Component Not Found? Verify the component exists in vendor/thrace/component-bundle/src/Resources/views/. Use:

  find vendor/thrace/component-bundle -name "*.blade.php"
  

• Service Unavailable? Check if the bundle’s service provider is registered. Run:

  php artisan package:discover
  

• Blade Errors Enable debug mode (APP_DEBUG=true) and check Laravel logs (storage/logs/laravel.log) for missing views or syntax issues.

Extension Points

1. Custom Components Extend existing components by copying them to resources/views/vendor/thrace/ and modifying:

   @component('thrace::card')
       @slot('header')
           Custom Header
       @endslot
   @endcomponent
   

2. Service Decorators Decorate bundle services for custom logic:

   $this->app->bind(
       ExampleService::class,
       function ($app) {
           return new CustomExampleService($app->make(ExampleService::class));
       }
   );
   

3. Event Listeners Listen for bundle events (if documented) to hook into workflows:

   Event::listen(
       \Thrace\ComponentBundle\Events\ComponentRendered::class,
       function ($event) {
           // Log or modify component output
       }
   );
   

4. Testing Use Thrace\ComponentBundle\Tests\* as a reference for writing tests. Isolate bundle dependencies with:

   $this->partialMock(ExampleService::class, function ($mock) {
       $mock->shouldReceive('doSomething')->andReturn('mocked');
   });