Collections Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require cscfa_tool_division/collections
   

   Register the service provider in config/app.php under providers:

   CSCFAToolDivision\Collections\CollectionsServiceProvider::class,
   

2. First Use Case Use the concrete collection class directly. For example, to check if an array contains a value:

   use CSCFAToolDivision\Collections\Concrete\Collection;
   
   $collection = new Collection(['apple', 'banana', 'cherry']);
   $containsBanana = $collection->contain('banana'); // Returns true
   

3. Where to Look First

   • Documentation: Check the README for available methods and traits.
   • Source Code: Explore src/Concrete/Collection.php for the concrete implementation and src/Traits/ for reusable logic.

Implementation Patterns

Usage Patterns

1. Basic Collection Operations Use the concrete Collection class for simple operations like checking for elements, clearing content, or counting items:

   $collection = new Collection([1, 2, 3]);
   $collection->clear(); // Clears the collection
   $count = $collection->count(); // Returns 0
   

2. Custom Collections Extend the AbstractCollection to create domain-specific collections:

   use CSCFAToolDivision\Collections\AbstractCollection;
   
   class UserCollection extends AbstractCollection {
       // Inherits all traits and methods from AbstractCollection
       public function findById($id) {
           return $this->content[$id] ?? null;
       }
   }
   

3. Trait Composition Combine traits to add functionality to your custom collections. Ensure the content property is defined:

   use CSCFAToolDivision\Collections\Traits\ContainerCollectionTrait;
   use CSCFAToolDivision\Collections\Traits\NumberizedCollectionTrait;
   
   class CustomCollection extends AbstractCollection {
       use ContainerCollectionTrait, NumberizedCollectionTrait;
   }
   

Workflows

1. Data Validation Use contain() or containAll() to validate data before processing:

   $requiredFields = ['name', 'email', 'age'];
   $userData = new Collection($inputData);
   if ($userData->containAll($requiredFields)) {
       // Proceed with processing
   }
   

2. Data Transformation Combine with Laravel’s collection methods for advanced transformations:

   $collection = new Collection([1, 2, 3]);
   $transformed = $collection->content; // Get underlying array
   $doubled = collect($transformed)->map(fn($item) => $item * 2);
   

3. Integration with Laravel Use collections alongside Laravel’s built-in Illuminate\Support\Collection for hybrid workflows:

   $laravelCollection = collect([1, 2, 3]);
   $customCollection = new Collection($laravelCollection->toArray());
   

Integration Tips

• Service Container Binding Bind the Collection class to the Laravel service container for easier instantiation:

  $this->app->bind('custom.collection', function() {
      return new \CSCFAToolDivision\Collections\Concrete\Collection();
  });
  

• Dependency Injection Inject custom collections into controllers or services:

  public function __construct(private Collection $collection) {}
  

Gotchas and Tips

Pitfalls

1. Trait Dependency on content Property Traits like ContainerCollectionTrait and NumberizedCollectionTrait require a content property in the class using them. Forgetting this will cause runtime errors:

   // ❌ Will fail
   class BadCollection {
       use ContainerCollectionTrait; // Missing 'content' property
   }
   

2. No Laravel Collection Integration This package does not integrate with Laravel’s Illuminate\Support\Collection. Treat it as a standalone array wrapper.

3. Outdated Codebase Last release was in 2016. Test thoroughly for edge cases (e.g., PHP 8.x compatibility, edge-case array handling).

4. No Built-in Immutability Methods like clear() modify the collection in-place. Create copies if immutability is needed:

   $newCollection = new Collection($originalCollection->content);
   

Debugging

1. Check for Missing content Property If methods like contain() fail silently, verify the content property exists and is an array:

   var_dump(property_exists($collection, 'content'), $collection->content);
   

2. Type Mismatches Methods like contain() use === for comparison. Ensure data types match:

   $collection->contain(1); // Will fail if content has '1' (string)
   

3. Trait Conflicts Avoid using multiple traits that modify the same logic (e.g., two traits defining count()). Override in your class if needed.

Config Quirks

• No Configuration File The package has no config file. All behavior is defined via traits and abstract classes.

Extension Points

1. Custom Traits Create your own traits and extend AbstractCollection:

   trait SortableCollectionTrait {
       public function sort() {
           $this->content = sort($this->content);
           return $this;
       }
   }
   

2. Override Methods Override trait methods in your concrete class to add custom logic:

   class FilterableCollection extends AbstractCollection {
       public function contain($element) {
           // Custom logic
           return str_contains($element, 'test');
       }
   }
   

3. Add Helper Methods Extend the collection with domain-specific helpers:

   class UserCollection extends AbstractCollection {
       public function activeUsers() {
           return new static(array_filter($this->content, fn($user) => $user['active']));
       }
   }