Simorgh Laravel Package

Technical Evaluation

Architecture fit aminsamadzadeh/simorgh targets a narrow, well-understood seam in a Laravel application: translating HTTP request parameters into Eloquent query constraints. It sits between the controller/FormRequest layer and the Eloquent builder, which is the same position occupied by spatie/laravel-query-builder and hand-rolled filter traits. That is a legitimate architectural slot for read-heavy JSON APIs (list/index endpoints with filtering, sorting, pagination, and relation inclusion), and it composes cleanly with API Resources, FormRequests, and policies.

The fit is good in principle but shallow in practice. The package appears to solve one concern with a small public surface (likely a trait, scope, or facade), meaning adoption cost is low and blast radius is contained to whichever controllers opt in. It is not a framework-level dependency and does not force a data-access rewrite.

Integration feasibility Composer-installable, Laravel package discovery, no infrastructure requirements, no external services, no schema changes. Integration effort is measured in hours for a spike and days for a hardened rollout. The realistic friction is not installation — it is the Laravel/PHP version constraints frozen at a November 2020 release, which likely caps support at Laravel 6–8 and PHP 7.x. On a modern Laravel 10/11 codebase, this is a fork-and-patch exercise, not a composer require.

Technical risk This is where the package fails as a low-risk adoption:

• Staleness. Last release 2020-11-09. Roughly four-plus years without a tag against a framework that ships breaking changes annually. Assume no Laravel 9+ compatibility without verification.
• Adoption signal. 11 stars and a single maintainer implies effectively zero community scrutiny. For a library that generates SQL from user-controlled input, absence of scrutiny is the dominant risk, not a cosmetic one.
• Security-sensitive domain. Request-driven query building is an injection and data-exposure surface: unwhitelisted column/relation names, operator injection, nested-relation traversal into unauthorized models, and filter-based inference attacks that let a client enumerate records they cannot GET directly. Whether this package whitelists anything is unknown and must be verified in source, not docs.
• Availability risk. Unbounded filter/sort/include combinations are a cheap denial-of-service vector: unindexed LIKE scans, deep relation eager-loads producing cartesian blowups, and arbitrarily large page sizes.
• Maintenance posture. No evidence of a security policy, CI matrix, or test coverage. Bus factor of one, and the maintainer's engagement is unverified.

Key questions

1. Which Laravel and PHP versions do the composer.json constraints permit, and does the test suite pass against our target version?
2. Does it enforce an allowlist of filterable/sortable columns and relations, or does it accept arbitrary field names?
3. How is the filter grammar parsed — raw strings into whereRaw, or bound parameters through the builder?
4. Does it integrate with authorization (policies/Gates) or silently expose every relation it can reach?
5. Is there input validation on operators, page size, and nesting depth?
6. What is the license, and is forking/vendoring permitted?
7. Does it support relation loading (with), and does it guard against N+1 and recursive nesting?
8. Is the maintainer responsive on issues, and are there open security-relevant reports?
9. How does the query-parameter grammar compare to spatie/laravel-query-builder — is there any capability this package offers that a maintained alternative does not?

Integration Approach

Stack fit Fits a conventional Laravel API stack (Laravel + Eloquent + API Resources + FormRequests). It is a read-path convenience, not a persistence or domain-layer component, so it does not constrain domain modeling. It fits poorly in codebases that already standardize on a vetted query-builder package, since running two filter grammars in one API creates inconsistent client contracts.

Migration path Do not adopt directly into production controllers. The correct path is a bounded spike:

1. Vendor spike. Fork the repo, run its tests, and patch version constraints to our target Laravel/PHP. Timebox to two days.
2. Isolation. Wrap the package behind a thin internal interface (e.g., QueryFilterApplicator) so controllers depend on our abstraction, not the vendor API. This is the single highest-value decision here: it converts a stale third-party dependency into a swappable implementation detail and makes the eventual replacement with spatie/laravel-query-builder or an in-house trait a one-file change.
3. Pilot. Apply to one read-only, low-sensitivity index endpoint behind a feature flag. Compare generated SQL against the hand-written baseline.
4. Decide. Either promote to additional endpoints or retire the spike and build the ~200-line internal equivalent.

For most teams the honest recommendation is that the spike exists to evaluate, and the likely outcome is building or adopting in-house — the package is small enough that its value is mostly as a reference implementation of the pattern.

Compatibility Expect to own compatibility. Pin exact versions, add the fork to CI with a Laravel version matrix, and treat every framework upgrade as requiring a review of this package. If the fork cannot be made to pass on our target framework within the timebox, that is a hard stop, not a workaround.

Sequencing Security review of the query construction path before any endpoint exposure; adapter layer before the first production controller; observability (query logging, slow-query alerts) before scaling beyond the pilot; documented allowlists per endpoint before opening to external clients. Do not sequence security review after the pilot — the pilot is exactly where unwhitelisted field access would surface as a real exposure.

Operational Impact

Maintenance Effectively a fork-and-own dependency. Budget ongoing effort for framework-upgrade patches, security review of the query path, and dependency updates. This is low absolute hours but non-zero and perpetual, and it must be assigned to a named owner — an unowned fork is worse than no package.

Support No vendor, no SLA, no security contact. Support is GitHub issues with a single maintainer and an 11-star project; assume no response. Internal documentation of the filter grammar and allowlist conventions is mandatory, because it will not come from upstream.

Scaling The generator itself is cheap; the queries it produces are the scaling risk. Under load, expect unindexed filter columns to degrade first, followed by eager-load amplification from relation includes and oversized page requests. Mitigations: per-endpoint allowlists, enforced max page size, include depth limits, statement timeouts at the database/proxy layer, rate limiting on list endpoints, and slow-query alerting tied to endpoint. Without these, the package converts client creativity directly into database load.

Failure modes

• Framework upgrade breaks the package silently or at boot (service provider/discovery failure).
• Filter/sort on an unwhitelisted or unindexed column → full table scan and latency spike.
• Deep relation includes → N+1 storms or cartesian result explosions.
• Filter-based enumeration or inference allowing access to records the requester cannot fetch directly.
• Unbounded page size or operator abuse → memory exhaustion in the PHP worker.
• Unhandled exceptions leaking SQL fragments or schema details in API error responses.
• Divergence from the documented grammar after a fork patch, breaking client contracts without a version bump.

Ramp-up The API surface is small, so engineer ramp-up is measured in hours — but the grammar is likely undocumented, meaning engineers read the source rather than docs. That concentrates knowledge in whoever did the spike, which is a real continuity risk for a component that touches every list endpoint. Mitigate with an internal README covering the grammar, the allowlist pattern, and the adapter interface, plus at least two engineers through the pilot.

Bottom line for a TPM: low integration cost, low architectural risk, high ownership risk. This package is only defensible behind an internal abstraction and an explicit allowlist layer, with a named owner and a documented exit path. Absent those three, the expected cost of ownership exceeds the cost of building the equivalent in-house.