Getting Started

Minimal Steps

Installation:
```
composer require zenstruck/collection
```
Ensure your project uses PHP 8.5+ and Symfony 6.4+ (or Laravel 10+).

First Use Case: Replace native Collection operations with zenstruck/collection for enhanced type safety and Doctrine integration:

use Zenstruck\Collection\Collection;

$users = Collection::fromArray($arrayOfUsers)
    ->filter(fn ($user) => $user['active'])
    ->map(fn ($user) => $user['name'])
    ->toArray();

Doctrine ORM Integration: For Doctrine entities, use the DoctrineBridgeCollection:

use Zenstruck\Collection\DoctrineBridge\DoctrineBridgeCollection;
use Doctrine\ORM\EntityRepository;

$repository = $entityManager->getRepository(User::class);
$users = DoctrineBridgeCollection::fromEntityRepository($repository)
    ->filter(fn ($user) => $user->isActive())
    ->toArray();

Lazy Loading: Process large datasets efficiently with lazy evaluation:

$lazyUsers = Collection::fromArray($largeArrayOfUsers)
    ->lazy()
    ->filter(fn ($user) => $user['active'])
    ->map(fn ($user) => $user['name']);

Batch Processing: Use the built-in batch processor for chunked operations (e.g., bulk updates):

use Zenstruck\Collection\BatchProcessor;

$processor = new BatchProcessor(100); // Process 100 items at a time
$processor->process($users, fn ($batch) => $this->updateUsers($batch));

Where to Look First

Documentation (limited but clear).
Tests for usage examples.
Release Notes for breaking changes (e.g., PHP 8.5 features, DoctrineBundle 3 support).

Implementation Patterns

Core Workflows

1. Collection Operations

Replace Laravel’s Collection with Zenstruck\Collection\Collection for stricter typing and additional methods:

use Zenstruck\Collection\Collection;

$collection = Collection::fromArray($data)
    ->filter(fn ($item) => $item['status'] === 'active')
    ->sortBy('name')
    ->groupBy('department')
    ->mapWithKeys(fn ($group, $key) => [$key => $group->values()]);

2. Doctrine ORM Integration

Leverage DoctrineBridgeCollection for seamless entity operations:

use Zenstruck\Collection\DoctrineBridge\DoctrineBridgeCollection;

$users = DoctrineBridgeCollection::fromEntityRepository($userRepository)
    ->filter(fn ($user) => $user->getRole() === 'admin')
    ->with('posts') // Eager-load associations
    ->toArray();

3. Lazy Evaluation

Optimize memory usage for large datasets:

$lazy = Collection::fromArray($hugeDataset)
    ->lazy()
    ->filter(fn ($item) => $item['active'])
    ->map(fn ($item) => $item['id']);

foreach ($lazy as $id) {
    // Process one item at a time
}

4. Batch Processing

Process collections in chunks (e.g., for API calls or database updates):

use Zenstruck\Collection\BatchProcessor;

$processor = new BatchProcessor(50); // Batch size
$processor->process($users, fn ($batch) => $this->saveUsers($batch));

5. Pagination with Pagerfanta

Integrate with Pagerfanta for advanced pagination:

use Zenstruck\Collection\Pagerfanta\PagerfantaAdapter;

$adapter = new PagerfantaAdapter($collection);
$pagerfanta = new \Pagerfanta(new \Pagerfanta\Adapter\ArrayAdapter($adapter->getIterator()));

Integration Tips

Laravel-Specific

Service Providers: Register the package in AppServiceProvider if extending functionality:

public function boot()
{
    Collection::macro('customMethod', function () {
        return $this->map(fn ($item) => strtoupper($item));
    });
}

Eloquent Models: Use DoctrineBridgeCollection for query builder operations:

$query = User::query()->where('active', true);
$collection = DoctrineBridgeCollection::fromQueryBuilder($query);

Symfony-Specific

DoctrineBundle 3: Enable output walkers for debugging:

# config/packages/zenstruck_collection.yaml
zenstruck_collection:
    doctrine:
        output_walkers: true

Dependency Injection: Bind DoctrineBridgeCollection as a service:

// src/Service/CollectionService.php
public function __construct(
    private DoctrineBridgeCollectionFactory $factory
) {}

Performance Patterns

Avoid toArray() Early: Use lazy loading or generators to defer materialization.
Batch Sizes: Tune BatchProcessor sizes based on database/index performance.
Doctrine Joins: Use with() sparingly to avoid the N+1 problem; prefer join in QueryBuilder.

Gotchas and Tips

Pitfalls

PHP Version Requirements:
- PHP 8.5+ is mandatory for full feature support (e.g., enums, new array functions).
- Symfony 6.4+ or Laravel 10+ is recommended for compatibility.
Doctrine ORM Quirks:
- Lazy-Loaded Associations: with() may trigger multiple queries if not used with fetchJoinColumn.
- QueryBuilder Conflicts: Ensure DoctrineBridgeCollection is used with Doctrine’s latest QueryBuilder methods (e.g., expr()).

Immutable Collections:

Methods like filter() return new collections; chain operations carefully to avoid memory leaks:

// Bad: Creates many intermediate collections
$result = $collection->filter(...)->map(...)->filter(...);

// Good: Use lazy evaluation
$result = $collection->lazy()->filter(...)->map(...);

Batch Processor Pitfalls:

Error Handling: Uncaught exceptions in batch callbacks will halt processing. Use try-catch:

$processor->process($items, fn ($batch) => {
    try {
        $this->saveBatch($batch);
    } catch (\Throwable $e) {
        $this->logError($e);
        throw $e; // Re-throw to continue with next batch
    }
});

Batch Size: Too small = overhead; too large = memory issues. Test with 100–1000 items.

Type Safety:
- Generics: The package uses array<array-key, T> for type hints. Ensure your IDE (PHPStorm, VSCode) supports PHP 8.5 generics.
- Doctrine Entities: Return types for DoctrineBridgeCollection are strict. Cast to array if needed:
```
$array = $collection->toArray(); // array<array-key, mixed>
```

Debugging Tips

Doctrine Debugging:
- Enable SQL logging in config/packages/dev/doctrine.yaml:
```
doctrine:
    dbal:
        logging: true
        profiler: true
```
- Use DoctrineBridgeCollection::getQueryBuilder() to inspect the underlying query.
Lazy Collection Issues:
- Generator Wrapping: Ensure generators are properly wrapped in LazyCollection:
```
$lazy = Collection::fromGenerator($generator)->lazy();
```
- Memory Leaks: Use memory_get_usage() to profile lazy-loaded operations.

Batch Processor:

Progress Tracking: Add logging to track batch completion:

$processor->process($items, fn ($batch) => {
    $this->logger->info('Processing batch', ['count' => count($batch)]);
    $this->saveBatch($batch);
});

Performance Bottlenecks:
- Profile with Xdebug: Use xdebug_profile_enable() to identify slow collection operations.
- Avoid toArray(): Materializing large collections prematurely can cause OOM errors.

Extension Points

Custom Collections: Extend Zenstruck\Collection\Collection for domain-specific logic:

class UserCollection extends Collection
{
    public function activeAdmins(): array
    {
        return $this->filter(fn ($user) => $user->isActive() && $user->isAdmin())
            ->values()
            ->toArray();
    }
}

**Doctrine

Collection Laravel Package