Datasource Laravel Package

Technical Evaluation

Architecture fit

• fsi/datasource is a standalone PHP component, not a Laravel package: no service provider, facade, config file, or publishable assets. It provides a driver abstraction plus "specified conditions" for retrieving data from heterogeneous sources (Doctrine-style, array/API, etc.).
• Architecturally it is a query-port/adapter layer: drivers encapsulate how to fetch, conditions encapsulate what to fetch. That maps cleanly onto a hexagonal boundary in a Laravel app — a DataSource port with Eloquent/HTTP/legacy-DB adapters behind it.
• It is a poor fit as a general-purpose ORM replacement or as the primary data-access path in a Laravel app; Laravel's Eloquent/Query Builder already cover the single-database case, so value only appears when you genuinely have multiple, heterogeneous sources behind one interface.

Integration feasibility

• Feasible but not turnkey. Work required: (1) a container binding/service provider, (2) a driver registration strategy, (3) at least one custom driver (e.g. Eloquent/Query Builder) since shipped drivers are likely Doctrine-oriented, (4) a condition-object mapper from your domain filters to its condition model.
• Composer-installable and MIT-licensed, so forking or vendoring under an internal namespace is legally and practically straightforward.
• Effort is concentrated in adapters, not in the core — budget roughly a spike plus one adapter sprint before any production path.

Technical risk

• High. Last release 2021-02-11, 8 stars, 0 dependents, single-organisation provenance (FSi Open, known for Symfony admin bundles). Effectively unmaintained and unexercised by the wider community.
• Dependency drift is the top risk: its PHP/Symfony (or PSR) constraints likely conflict with Laravel 10/11 on PHP 8.2/8.3. Must be verified against composer.json before anything else.
• No visible security-advisory process, no LTS, bus factor of one organisation. Any CVE or PHP minor-version break becomes your problem.
• Silent correctness risk: a mis-mapped condition produces a wrong result set rather than an error — the worst failure mode for data access.

Key questions

1. What drivers ship in the box, and is any of them non-Doctrine?
2. What are the exact PHP and dependency constraints — do they resolve on our target Laravel/PHP matrix?
3. Is the condition model expressive enough for our real filters (nested and/or, ranges, relations, pagination, sorting)?
4. Test coverage and CI status of the current HEAD?
5. Who owns this internally after adoption — and is a fork acceptable to the team?

Integration Approach

Stack fit

• Treat it as a library, not a framework extension. It fits where the product genuinely needs a uniform read interface over 2+ dissimilar sources (e.g. MySQL + legacy ERP DB + partner REST API + search index).
• It fits poorly as a thin wrapper over one Eloquent model — the indirection buys nothing and costs a dependency.
• Keep its types out of controllers/domain code; expose your own DataSource interface and let fsi/datasource be an implementation detail behind it.

Migration path

1. Spike (1–2 days): install in a scratch branch, resolve dependencies against the real composer.lock, run its test suite, write a throwaway array driver and one condition to confirm the extension points are usable.
2. Fork decision gate: if the spike passes but constraints are stale, fork to internal/datasource, bump PHP/deps, add CI and a composer.json replace. This is the expected outcome and should be planned for, not discovered later.
3. Adapter layer: DataSourceServiceProvider registering a driver registry; internal driver(s) implementing the shipped interface over Eloquent/HTTP clients; a mapper translating domain filter DTOs into package conditions.
4. Pilot: one read-only, low-blast-radius endpoint or reporting module. No writes.
5. Expand only after the pilot proves result parity against the existing query path (golden-dataset comparison tests).

Compatibility

• Verify composer.json constraints before committing; check for Symfony 4/5-era pins and abandoned transitive dependencies (composer why-not, composer outdated --direct).
• Laravel 10/11 ships no bridge; you own the container wiring. Expect to pin or patch PHP version support.
• Laravel Octane/queue contexts: confirm the driver/registry holds no mutable global state; drivers should be stateless or scoped.

Sequencing Spike → fork/dependency decision → adapter + condition mapper → pilot with parity tests → production rollout → deprecation path for the legacy query code. Do not start the pilot before the fork gate is resolved; retrofitting a fork mid-integration doubles the work.

Operational Impact

Maintenance

• Assume full ownership. There is no upstream roadmap and no realistic expectation of fixes; the 2021 release date means you are adopting a snapshot, not a maintained product.
• Budget recurring time for dependency bumps and PHP-version compatibility, even if the code never changes. Fork + CI + a "do not upgrade Laravel without re-testing this" note in the runbook are the minimum.
• Add parity/regression tests around condition translation — this is the artifact that keeps the component honest over time.

Support

• No vendor SLA, no active issue triage, negligible community footprint (0 dependents means almost nobody has hit your edge cases before you). Internal expertise must be documented, ideally with more than one engineer ramped.

Scaling

• The abstraction adds a thin indirection layer; query cost is driven by your driver implementations, not the package. Watch for absent pagination/batching semantics and ensure drivers stream or chunk rather than materialising large result sets.
• Caching, read replicas, and connection pooling stay your responsibility — the package is unlikely to help.
• Horizontal scale is unaffected; the concern is per-query efficiency and N+1 patterns introduced by conditions that fan out to relations.

Failure modes

• Dependency deadlock: cannot upgrade Laravel/PHP without patching an unmaintained package — highest-probability, highest-cost failure.
• Silent wrong results: condition mis-mapping returns plausible but incorrect data; only parity tests catch this.
• Driver exception leakage: raw DB/HTTP exceptions surfacing through the abstraction instead of domain errors.
• Bit-rot/availability: package unpublished or Composer resolution breaking on a transitive dependency yanked from Packagist — mitigated by vendoring or a fork in your own VCS.
• Knowledge concentration risk: one engineer understands the condition model; mitigation is documentation and the parity test suite.

Ramp-up

• Conceptual surface is small (drivers + conditions): a mid-level PHP developer reaches productive in roughly 2–4 days, mostly reading the driver interface.
• Practical productivity requires Laravel-specific adapter knowledge plus the target source's query semantics; budget 1–2 weeks to first meaningful contribution.
• Onboarding cost is permanent overhead: every new engineer must learn a bespoke, undocumented abstraction that they cannot look up on the internet. This is the strongest argument for wrapping it tightly behind an internal interface — or for building the much smaller abstraction in-house instead.