Base Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require zetacomponents/base
   

   Add to composer.json under autoload:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Zeta\\Components\\Base\\": "vendor/zetacomponents/base/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case: Basic Component Initialization

   use Zeta\Components\Base\Base;
   
   $component = new Base();
   $component->setName('MyComponent');
   echo $component->getName(); // Outputs: MyComponent
   

3. Key Classes to Explore

   • Base (Core base class for components)
   • Component (Extended base with common traits)
   • ComponentCollection (For managing multiple components)

4. Where to Look First

   • Source Code (if available)
   • Zeta/Components/Base/Component.php (Core functionality)
   • Zeta/Components/Base/ComponentCollection.php (Group management)

Implementation Patterns

1. Component Lifecycle Management

use Zeta\Components\Base\Component;

class MyComponent extends Component {
    protected function initialize() {
        // Runs on component creation
        $this->setDefault('config.key', 'default_value');
    }

    protected function finalize() {
        // Runs on component destruction
        $this->log('Component finalized');
    }
}

2. Configuration Handling

$component = new MyComponent();
$component->setConfig(['key' => 'value']);
$value = $component->getConfig('key'); // Returns 'value'
$default = $component->getConfig('missing', 'fallback'); // Returns 'fallback'

3. Event-Driven Workflows

$component->on('event.name', function($sender, $eventArgs) {
    // Handle event
});
$component->trigger('event.name', ['arg1' => 'value']);

4. Dependency Injection

$component->setDependency('logger', new Logger());
$logger = $component->getDependency('logger');

5. Collection Management

use Zeta\Components\Base\ComponentCollection;

$collection = new ComponentCollection();
$collection->addComponent(new MyComponent());
$collection->addComponent(new AnotherComponent());

foreach ($collection as $component) {
    $component->doWork();
}

6. Integration with Laravel Services

// Register in a service provider
$this->app->singleton('my.component', function ($app) {
    $component = new MyComponent();
    $component->setDependency('app', $app);
    return $component;
});

// Usage in controllers
$component = app('my.component');

Gotchas and Tips

Pitfalls

1. Circular Dependencies

   • Avoid creating circular dependencies between components. Use lazy loading or interfaces to decouple tightly coupled components.

2. Configuration Overrides

   • Config values set via setConfig() will override defaults, even if set later. Test edge cases where configs are modified dynamically.

3. Event Memory Leaks

   • Unbind event listeners explicitly when no longer needed to prevent memory leaks:

     $component->off('event.name');
     

4. Namespace Collisions

   • If extending Component, ensure your class namespace doesn’t conflict with existing Zeta components (e.g., avoid Zeta\Components\Base\MyComponent).

5. Finalize() Not Always Called

   • finalize() may not run if the component is garbage collected abruptly (e.g., during a script exit). Use try-catch blocks in finalize() for critical cleanup.

Debugging Tips

1. Enable Component Logging

   $component->setLogLevel(Zeta\Components\Base\Logger::LEVEL_DEBUG);
   $component->log('Debug message');
   

2. Inspect Dependencies

   $dependencies = $component->getDependencies();
   // Dump dependencies for debugging
   dd($dependencies);
   

3. Check Event Flow

   • Use trigger() with a debug callback to trace event propagation:

     $component->on('event.name', function($sender, $args) {
         dd('Event triggered!', $args);
     });
     

Extension Points

1. Custom Traits Extend functionality by adding traits to your component:

   trait MyTrait {
       public function myMethod() {
           return 'Extended functionality';
       }
   }
   
   class MyComponent extends Component {
       use MyTrait;
   }
   

2. Override Core Methods

   class MyComponent extends Component {
       protected function initialize() {
           parent::initialize();
           // Custom initialization logic
       }
   }
   

3. Create Custom Collections Extend ComponentCollection for domain-specific behavior:

   class MyComponentCollection extends ComponentCollection {
       public function filterByType($type) {
           return $this->filter(function($component) use ($type) {
               return $component instanceof $type;
           });
       }
   }
   

4. Integrate with Laravel’s Container Use the setDependency() method to inject Laravel services:

   $component->setDependency('request', app('request'));
   $component->setDependency('cache', app('cache.store'));
   

Performance Considerations

• Avoid Heavy Initialization: Move expensive operations to lazy-loaded methods (e.g., initialize() should be lightweight).
• Use ComponentCollection Efficiently: For large collections, consider implementing ArrayAccess or IteratorAggregate for optimized iteration.
• Event Bubbling: Limit event propagation depth to avoid performance bottlenecks in complex component hierarchies.