Add LookupStrategy to DoctrineWriter (port of #11 for 2.x)

[slashrsm]

Summary

Port of stale #11 (“Add lookup strategy to writer”, ddeboer, 2017) onto current 2.0 master (PHP ^8.2, portphp ^2, doctrine/common ^3 / Doctrine\Persistence).

Related: #3 (custom QueryBuilder lookups), discussion in #9.

What lands

Piece	Role
Port\Doctrine\LookupStrategy	Interface: lookup(array $item): ?object
LookupStrategy\FieldsLookupStrategy	Default field/criteria strategy
DoctrineWriter::withLookupStrategy()	Factory for custom strategies
Optional 5th ctor arg ?LookupStrategy	Same as factory, without deprecations

Default / BC behavior (2.x)

No intentional BC break for existing 2.x call sites:

• new DoctrineWriter($om, $class) — unchanged
• new DoctrineWriter($om, $class, $index, $lookupMethod) — unchanged
• truncate = true (default) still always creates a new instance (no lookup)
• disableTruncate() + no index → ObjectRepository::find(current($item))
• disableTruncate() + index → repository method (default findOneBy) with field criteria
• Lookup miss (null) → create new instance (upsert-friendly)

$index / $lookupMethod are not deprecated in 2.x; LookupStrategy is additive. Deprecating those args can wait for a 3.0 discussion.

Fixes vs original #11

The 2017 branch was incomplete and could not be cleanly rebased (CONFLICTING). Notable bugs fixed in this port:

1. withLookupFields mutated $this instead of the clone
2. Called missing withIndex() on FieldsLookupStrategy
3. Factory passed LookupStrategy as the 4th ctor arg ($lookupMethod string) — type error / broken API
4. Factory argument order was ($objectName, $om, $strategy); now ($om, $objectName, $strategy) to match the constructor
5. findOrCreateItem returned null from strategy without creating a new entity (regression)
6. Default strategy used identifier fields instead of master’s empty-fields → find(current($item)) behavior
7. Namespaces modernized (Doctrine\Persistence), PHP 8.2 types, PHPUnit 9

Usage

// Existing (still supported)
$writer = new DoctrineWriter($em, User::class, 'email');
$writer->disableTruncate();

// Custom strategy (e.g. QueryBuilder — fixes #3)
$writer = DoctrineWriter::withLookupStrategy(
    $em,
    User::class,
    new class($em) implements \Port\Doctrine\LookupStrategy {
        public function __construct(private $em) {}
        public function lookup(array $item): ?object {
            return $this->em->createQueryBuilder()
                ->select('u')->from(User::class, 'u')
                ->where('u.email = :email')->setParameter('email', $item['email'])
                ->getQuery()->getOneOrNullResult();
        }
    }
);
$writer->disableTruncate();

Tests

• Full suite green locally: 16 tests, PHP 8.5.8 / PHPUnit 9.6
• Covers factory, custom strategy lookup/miss, constructor $index path, FieldsLookupStrategy immutability, invalid method

Original #11

Please close #11 as superseded once this merges (do not merge #11).

Checklist

• BC defaults match 2.0 master writer behavior
• PHPUnit green locally
• CI matrix 8.2–8.5 green
• Copilot / human review
• Do not merge until maintainer (@slashrsm) confirms

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[slashrsm]

@copilot please review this PR when quota allows.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.