Utilitybundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require circle/utilitybundle
   

   Add to AppKernel.php:

   new Circle\UtilityBundle\CircleUtilityBundle(),
   

2. First Use Case: Immutable Container (e.g., storing configuration):

   use Circle\UtilityBundle\Container\ImmutableContainer;
   
   $container = new ImmutableContainer(['key' => 'value']);
   echo $container->get('key'); // 'value'
   

   Queue (e.g., processing tasks):

   use Circle\UtilityBundle\Queue\Queue;
   
   $queue = new Queue();
   $queue->push('task1');
   $queue->push('task2');
   echo $queue->pop(); // 'task1'
   

   Tree (e.g., hierarchical data):

   use Circle\UtilityBundle\Tree\Tree;
   
   $tree = new Tree('root');
   $child = $tree->addChild('child1');
   $child->addChild('grandchild1');
   $tree->render(); // Outputs tree structure
   

Implementation Patterns

Common Workflows

1. Immutable Container:

   • Use for read-only configurations or cached data.
   • Chain immutability with dependency injection:

     $config = new ImmutableContainer($this->getConfig());
     $service = new Service($config);
     

2. Tree Structures:

   • Build nested relationships (e.g., categories, org charts):

     $category = new Tree('Electronics');
     $laptop = $category->addChild('Laptops');
     $laptop->addChild('MacBook Pro');
     

   • Traverse with getChildren() or render().

3. Queue Management:

   • Process tasks sequentially:

     $queue = new Queue();
     while (!$queue->isEmpty()) {
         $task = $queue->pop();
         $this->process($task);
     }
     

   - Use `ImmutableQueue` for thread-safe operations.
   
   

4. Multi-Child Tree:

   • For many-to-many hierarchies (e.g., tags or flexible taxonomies):

     $multiTree = new MultiChildTree('root');
     $multiTree->addChild('tag1', 'parent1');
     $multiTree->addChild('tag2', 'parent1');
     $multiTree->getChildren('parent1'); // Returns ['tag1', 'tag2']
     

Integration Tips

• Symfony Services: Register utilities as services in services.yml:

  services:
      app.tree:
          class: Circle\UtilityBundle\Tree\Tree
          arguments: ['root']
  

• Event-Driven Queues: Pair with Symfony’s EventDispatcher to trigger actions on queue events (e.g., onPush, onPop).

Gotchas and Tips

Pitfalls

1. Deprecation Risk:

   • Last release in 2015; test thoroughly or fork if critical.
   • No Symfony 5+ compatibility (assumes older versions).

2. Immutable Container:

   • No dynamic keys: Keys must be set during initialization.

     // ❌ Fails silently
     $container->set('new_key', 'value'); // No setter method!
     

   • Deep immutability: Nested arrays/objects are not recursively immutable.

3. Tree/Queue Methods:

   • No built-in serialization: Manually handle serialize()/unserialize() for persistence.
   • MultiChildTree quirks: Child keys must be unique per parent; no built-in validation.

4. Performance:

   • Tree rendering: render() outputs HTML; avoid in performance-critical loops.

Debugging

• Immutable Container: Use getKeys() to inspect available keys:

  print_r($container->getKeys()); // ['key1', 'key2']
  

• Queue: Check size with count() or isEmpty() before popping to avoid UnderflowException.

Extension Points

1. Custom Tree Nodes: Extend TreeNode to add metadata:

   class CustomNode extends TreeNode {
       public function __construct($name, $metadata = []) {
           parent::__construct($name);
           $this->metadata = $metadata;
       }
   }
   

2. Queue Prioritization: Override Queue to support priority:

   class PriorityQueue extends Queue {
       public function push($item, $priority = 0) { ... }
       protected function sortItems() { ... }
   }
   

3. Immutable Container: Create a decorator for dynamic keys:

   class DynamicImmutableContainer extends ImmutableContainer {
       public function set($key, $value) {
           $this->container[$key] = $value; // ⚠️ Breaks immutability!
       }
   }