Getting Started

Minimal Steps

Install Dependencies:
```
composer require --dev php-ds/php-ds phpunit/phpunit ^11
```
Ensure your phpunit.xml targets PHP 8.2+.
First Use Case: Run the SeqTest (Sequence tests) to verify basic php-ds functionality:
```
./vendor/bin/phpunit vendor/php-ds/tests/SeqTest.php
```
Focus on SeqTest or MapTest if evaluating php-ds\Seq or php-ds\Map for Laravel.
Where to Look First:
- Test Structure: Browse tests/Seq/ or tests/Map/ for trait-per-method organization (e.g., testPushPop.php).
- Key Changes: Review v2.0.0.md for API shifts (e.g., KeyObject replaces HashableObject).
- Edge Cases: Check MapTest for 0.0/-0.0 key handling (relevant for financial/caching use cases).

Implementation Patterns

Usage Patterns

Trait-Based Testing: Use traits like SeqTest::testPushPop() to validate php-ds\Seq operations in custom Laravel services:

use php\ds\Seq;
use php\ds\tests\SeqTest;

class LaravelSeqServiceTest extends TestCase
{
    use SeqTest;

    public function testLaravelSeqOperations()
    {
        $seq = new Seq();
        $this->testPushPop($seq); // Reuse trait logic
        // Add Laravel-specific assertions
    }
}

Benchmark-Driven Adoption:
- Replace Laravel’s Collection with php-ds\Map for O(1) lookups:
```
use php\ds\Map;

$cache = new Map();
$cache->put('user:1', $userModel);
$this->assertEquals($userModel, $cache->get('user:1')); // Faster than Collection::where()
```
- Pattern: Wrap php-ds in a Laravel-friendly facade (e.g., PhpDsCollection) to maintain API consistency.

Event-Driven Workflows: Use php-ds\Deque (via SeqTest traits) for job queues:

use php\ds\Deque;

class JobQueueService
{
    public function __construct(private Deque $queue) {}

    public function pushJob($job)
    {
        $this->queue->push($job);
    }
}

Workflows

Refactor Legacy Code:
- Before: Custom SplQueue implementations.
- After: Replace with php-ds\Deque and reuse SeqTest traits for validation.
```
composer remove ext-spl
composer require php-ds/php-ds
```
Testing Strategy:
- Step 1: Run php-ds tests in isolation:
```
./vendor/bin/phpunit --testsuite PhpDs
```
- Step 2: Adapt traits for Laravel (e.g., mock HTTP requests in SeqTest).

Integration with Laravel:

Caching Layer: Replace array/Collection caches with php-ds\Map:

$cache = new Map();
Cache::extend('phpds', function () use ($cache) {
    return new class($cache) implements CacheStore {
        // ...
    };
});

Integration Tips

PHPUnit Configuration: Add a separate test suite in phpunit.xml:

<testsuites>
    <testsuite name="PhpDs">
        <directory>./vendor/php-ds/tests</directory>
        <exclude>*/VectorTest.php</exclude> <!-- Skip irrelevant tests -->
    </testsuite>
</testsuites>

Type Safety: Leverage php-ds’s generics (e.g., Seq<int>) in Laravel services:

use php\ds\Seq;

class OrderProcessor
{
    public function __construct(private Seq<int> $orderIds) {}
}

Debugging: Use php-ds’s dump() method for inspection:

$map = new Map();
$map->put('key', 'value');
\php\ds\dump($map); // Visualize structure

Gotchas and Tips

Pitfalls

PHPUnit Version Lock:
- Issue: Requires PHPUnit 11 (Laravel 9 uses PHPUnit 9).
- Fix: Use a separate PHPUnit config or Docker container:
```
docker run --rm -v $(pwd):/app composer:latest require phpunit/phpunit:^11 --dev
```
API Breaking Changes:
- Issue: v2.0.0 removed VectorTest/DequeTest; traits are now inlined.
- Fix: Update test references if using php-ds v2:
```
// Old (v1.x)
use php\ds\tests\VectorTest;

// New (v2.x)
use php\ds\tests\SeqTest;
```

Laravel Test Helpers:

Issue: Traits like DatabaseTestCase won’t work with php-ds tests.

Fix: Extend TestCase directly or mock dependencies:

use Tests\TestCase as BaseTestCase;

class PhpDsTest extends BaseTestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        $this->withoutExceptionHandling(); // For strict php-ds errors
    }
}

Key Interface:
- Issue: KeyObject (implements Ds\Key) is stricter than HashableObject.
- Fix: Ensure custom objects implement Ds\Key:
```
class UserKey implements Ds\Key
{
    public function __hash(): int { return hash('sha256', $this->id); }
}
```

Debugging

Test Failures:
- Common Cause: PHP 8.2+ strict typing or Key interface violations.
- Debug: Run with -d error_reporting=E_ALL:
```
./vendor/bin/phpunit -d error_reporting=E_ALL vendor/php-ds/tests/MapTest.php
```

Performance Mismatches:

Issue: php-ds operations slower than expected in Laravel.

Debug: Compare with Collection benchmarks:

Benchmark::group('Map vs Collection', function () {
    Benchmark::run('Map::get', fn () => $map->get('key'));
    Benchmark::run('Collection::where', fn () => $collection->where('key', 'value')->first());
});

Memory Leaks:
- Issue: php-ds structures retain references unexpectedly.
- Fix: Use clear() or drop() explicitly:
```
$seq->clear(); // Free memory
```

Config Quirks

Autoloading:
- Issue: php-ds classes may not autoload in Laravel.
- Fix: Ensure composer.json includes:
```
"autoload": {
    "psr-4": {
        "php\\ds\\": "vendor/php-ds/src"
    }
}
```
IDE Support:
- Issue: PHPStorm/VsCode may not recognize php-ds types.
- Fix: Add to phpstan.neon:
```
includes:
    - vendor/php-ds/extension.neon
```

Extension Points

Custom Traits:

Extend existing traits for Laravel-specific assertions:

trait LaravelSeqTest
{
    use \php\ds\tests\SeqTest;

    public function testLaravelSpecific()
    {
        $this->assertInstanceOf(\Illuminate\Support\Collection::class, $this->convertToCollection($this->seq));
    }

    protected function convertToCollection(Seq $seq): Collection
    {
        return collect(iterator_to_array($seq));
    }
}

Benchmarking:

Use php-ds tests as a baseline for Laravel optimizations:

use php\ds\tests\MapTest;

class LaravelMapBenchmark extends MapTest
{
    public function testVsLaravelCollection()
    {
        $this->assertLessThan(100, $this->benchmarkMapVsCollection());
    }
}

Polyfill Integration:
- Combine with php-ds/polyfill for backward compatibility:
```
use php\ds\polyfill\Map;

$map = new
```

Tests Laravel Package