Iterator Laravel Package

Technical Evaluation

What it is. hoa/iterator is the Hoa Project’s iterator toolkit: a set of Iterator/IteratorAggregate implementations (buffer, callback filter, CSV, directory, limit, map, regular-expression, split, token, infinite/repeater, etc.) plus glue for composing them. It is framework-agnostic PHP — there is no Laravel service provider, facade, config, or container binding. Any Laravel usage is as a leaf dependency inside application or domain code, not as a framework extension.

Architecture fit. Fits only where the requirement is genuinely lazy, pull-based traversal over a stream or unbounded source (large CSV imports, directory walks, token scanning) and where the team wants pre-built combinators rather than writing generators. In a modern Laravel codebase, LazyCollection, native generators, and SPL (SplFileObject, LimitIterator, CallbackFilterIterator, RegexIterator) cover the same ground with zero dependency cost. Fit is therefore narrow — a handful of legacy or specialized call sites, not an architectural layer.

Integration feasibility. Mechanically easy: Composer install, PSR-4 autoload, no native extensions, no runtime services. The friction is transitive — it drags in sibling Hoa packages (consistency, exception, and the stream stack), each carrying the same abandonment profile. There is no Laravel package discovery, so nothing auto-wires; you instantiate directly. BSD-3-Clause licensing is permissive and low-risk.

Technical risk — high, and mostly non-technical.

• Abandoned upstream: last release January 2017, repository archived. The 332 stars and 0 dependents signal near-zero ecosystem momentum; the package score (~1.44) and opportunity score (32.5) are consistent with a library nobody is betting on.
• PHP version drift: code predates PHP 7.2+ typing conventions and has not been validated against 8.1–8.4. Expect deprecation notices, possible dynamic-property and implicit-nullable issues, and no upstream fix path. This is the single largest unknown and must be proven by test, not assumed.
• Behavioral correctness: the Hoa idiom layer (Xcallable, custom exception hierarchy, stream wrappers) does not map cleanly onto SPL contracts; code that expects \RuntimeException or standard Iterator semantics may get surprises.
• Bus-factor: fixes are ours by definition. That is a permanent, if small, tax.

Key questions to answer before adopting.

1. Which specific iterator behavior do we need that LazyCollection/generators/SPL cannot express in under ~50 lines? If the answer is "none," stop here.
2. Is the consuming code path long-lived (core ingestion, queue workers) or disposable (one-off backfill script)? Risk tolerance differs sharply.
3. Has anyone actually run this suite on our PHP runtime and matrix? What is the deprecation/error volume?
4. Do we accept forking and owning it, or is this a stopgap with a dated removal ticket?
5. What is the exit cost — how many call sites would need rewriting if we drop it in 12 months?

Integration Approach

Stack fit. Treat it as a utility leaf, never as a public contract. Do not leak Hoa\Iterator\* types across module or service boundaries; convert to \Iterator, \Generator, or LazyCollection at the boundary. Laravel’s container, queues, and Eloquent have no opinion about it, which is both the appeal and the reason it adds nothing framework-native.

Migration path (preferred: replace, don’t integrate).

1. Inventory candidate call sites: CSV/tokenization, directory crawling, chunked filtering.
2. Spike each with LazyCollection::make() + Generators + SplFileObject; measure LOC delta. In most cases the native rewrite is smaller than the adapter.
3. Where parity fails, encapsulate behind one internal interface (e.g., App\Support\Iteration\RowStream) with a Hoa-backed implementation hidden inside.
4. Record the decision and a removal trigger in an ADR; add a static-analysis or code-review rule blocking new Hoa\Iterator imports.

If adoption is unavoidable.

• Pin the exact version in composer.json; commit the lockfile; add composer audit to CI.
• Vendor or fork into an internal namespace (App\Vendor\HoaIterator) so the archived upstream cannot be silently swapped and so we can patch.
• Isolate to a single Composer autoload path and a single service provider binding — no ad-hoc new scattered through controllers.

Compatibility. Run the full test suite on the oldest and newest PHP in the support matrix; assert zero deprecations under E_ALL. Verify autoload does not collide with other Hoa packages already present. Confirm exception types thrown by stream-backed iterators are catchable as standard SPL exceptions where callers expect it.

Sequencing. Prove compatibility → spike native alternative → decide replace vs. wrap → if wrap, add adapter + tests + ADR → migrate call sites opportunistically → set a review date (12 months) with an explicit sunset criterion.

Operational Impact

Maintenance. Effectively ours. No upstream releases, no security advisories, no PR merge path — archived means issues and PRs are closed loops. Dependency scanners will flag it as abandoned, and the transitive Hoa packages compound that. Budget a small standing allowance for PHP-upgrade remediation, and expect it to surface during every major runtime bump.

Support. No vendor, no community channel with throughput. Support is internal tribal knowledge held by whoever wrote the adapter. Document the wrapped behaviors in a runbook, including any Hoa-specific semantics (non-rewindable iterators, buffering, Xcallable invocation rules), or the knowledge leaves with the author.

Scaling. This is the one genuine upside: generator-style traversal keeps memory flat where an array-based implementation would blow up on large files or result sets. But not all Hoa iterators are lazy — buffering and serializing variants deliberately materialize state, which can silently invert the memory profile. Benchmark the specific iterators in use under production-shaped inputs (row counts, file sizes, queue concurrency), not the library as a whole. CPU cost of userland iterator chains is modestly higher than an equivalent foreach/generator loop; measure before assuming it matters.

Failure modes to plan for.

• Runtime upgrade breakage: deprecations escalate to errors, or subtle behavioral drift in stream-backed iterators — caught only by integration tests, not unit tests.
• Double-consumption bugs: non-rewindable iterators consumed twice inside a queued job or retried request, producing partial or duplicated output.
• Exception mismatch: Hoa exceptions unwinding past Laravel’s handler without mapping to expected HTTP/queue semantics, causing retries that should not happen.
• Autoload/namespace collision with other Hoa remnants in a legacy vendor tree.
• Silent buffering: memory regression under load with no obvious code smell.

Ramp-up. Low-to-moderate for a mid-level PHP developer: iterator and SPL concepts transfer directly, so the core API reads familiar within a day. The friction is Hoa’s idiosyncratic conventions (Consistency\Xcallable, custom exception hierarchy, stream wrappers), which are poorly documented and unmaintained — expect additional time for anyone touching stream-backed or tokenizing iterators. Net estimate: roughly half a day for basic combinators, one to two days to be safe with the stream-dependent classes.

Bottom line. The library is technically competent but stranded: archived, single-release-since-2017, zero dependents, and superseded in nearly every use case by native PHP and LazyCollection. The rational TPM position is replace, don’t integrate — fund the short native rewrite, and only wrap it if a specific iterator proves genuinely costly to reproduce, in which case fork it, pin it, document it, and put a removal ticket on the board with a date.