Spine Trigonometric Dql Bundle Laravel Package

Technical Evaluation

Verdict up front: Low strategic value as a dependency. The bundle is a thin Symfony wrapper around a handful of Doctrine custom DQL function classes. The reusable surface area is small enough that vendoring or reimplementing the function classes is likely cheaper and safer than adopting the package — especially given the zero-star, zero-dependent footprint and Bitbucket-only hosting.

Architecture fit

• The package is a Symfony bundle, not a Laravel package. Its value-add over raw Doctrine is the DI container wiring (CompilerPass/Bundle registration of doctrine.orm.custom_*_functions). That wiring is inert in Laravel, where Doctrine integration (via laravel-doctrine/orm or manual EntityManager bootstrap) has its own configuration path.
• The actually portable artifact is the set of FunctionNode subclasses implementing SIN, COS, TAN, COT, ACOS, ASIN, ATAN, and friends. Each is typically 30–60 lines: parse(), getSql(), and platform-specific SQL emission.
• Fit is therefore conceptual, not structural: it solves a real but narrow problem (trig expressions in DQL) that most Laravel teams never hit, because the common path is raw SQL via DB::raw() or computing in PHP.

Integration feasibility

• Not installable as a first-class Laravel dependency without friction. Expect to (a) pull via a vcs Composer repository, (b) suppress Symfony auto-discovery, and (c) manually register each function in the Doctrine config array.
• Realistic path: fork the function classes into app/Doctrine/Functions/ or a small internal package and register them explicitly. This is a few hours of work and removes the dependency entirely.
• Open technical questions to resolve before committing:
  • Which Doctrine ORM/DBAL major versions are supported (2.x vs 3.x)? Doctrine 3 changed several AST/FunctionNode contracts.
  • Is there a Packagist entry, or is Composer VCS the only source? Bitbucket private/public status affects CI auth.
  • What license is declared? Absent a clear license, legal review is required before redistribution or vendoring.
  • DB platform coverage: MySQL, PostgreSQL, SQLite, and SQL Server all expose these functions with subtly different names/casing and return-type behavior. Does the package handle getSql() per platform or assume one?
  • Unit semantics: radians vs degrees, NULL propagation, and float precision/rounding — these must be verified, not assumed.
  • Any test suite or CI config in the repo? Zero stars and zero dependents imply no external validation of correctness.

Technical risk

• High bus-factor and abandonment risk. Single author, Bitbucket, no stars, no dependents, score 0. Treat as unmaintained from day one.
• Correctness risk. Trigonometric DQL functions are easy to get subtly wrong (degrees/radians, decimal truncation, platform divergence) and hard to notice without tests.
• Upgrade risk. Any Doctrine major bump could break FunctionNode subclasses; with no upstream activity, you own the fix.
• Supply-chain risk. Pulling an unvetted VCS dependency into a production Laravel app is disproportionate to the ~200 lines of logic involved.

Integration Approach

Stack fit

• Laravel does not ship Doctrine. If the application already uses laravel-doctrine/orm (or a custom EntityManager binding), the function classes drop in cleanly. If the app is Eloquent-based, stop here — the package is irrelevant and the trig logic belongs in SQL expressions or PHP.
• The Symfony bundle layer should be treated as documentation, not runtime code.

Migration / adoption path

1. Spike (½ day): clone the repo, extract the FunctionNode classes, register one (SIN) against the target database in a Laravel test app, and assert output against a native SQL query.
2. Vendor (1–2 days): copy the classes into an internal namespace (App\Doctrine\DQL\*), preserving license headers, and register them explicitly:
   • doctrine.custom_numeric_functions for scalar-returning functions (SIN, COS, TAN, ACOS, …).
   • custom_string_functions only where the DQL return type is genuinely string-typed (unlikely here).
3. Test (1 day): integration tests on every platform you deploy to (typically MySQL/PostgreSQL), covering NULL inputs, degrees-vs-radians, and precision.
4. Document (½ day): a short ADR recording that the bundle was reviewed and vendored rather than depended upon, with rationale.

Compatibility

• Pin to the DBAL/ORM versions actually in use; verify FunctionNode signatures against your Doctrine major before porting.
• Confirm PHP version constraints (Symfony-era bundles are often PHP 7.x-only and will fail composer install under PHP 8.2+).

Sequencing

• Do the spike before any architectural commitment. If the DB already supports native trig and the query can be expressed as DB::raw(), the package is unnecessary and the effort ends there. Only proceed to vendoring if DQL-level composition (e.g., embedding trig inside larger DQL expressions or QueryBuilder reuse) is genuinely required.

Operational Impact

Maintenance

• You are the maintainer. No releases, no issue triage, no security response. Budget a small recurring cost for Doctrine upgrade cycles (re-verify FunctionNode contracts at each major bump) and platform additions.
• Forking into an internal namespace reduces the blast radius to your own repository and removes Composer/VCS auth and availability concerns.

Support

• Effectively none. No README depth, no changelog, no community. Slack/StackOverflow coverage for "trig in DQL" is thin; resolution will be first-principles.

Scaling

• The real scaling concern is query performance, not the package: applying SIN()/COS() to a column in a WHERE clause defeats standard B-tree indexes and forces full scans or expression indexes. On large tables this is the dominant cost.
• Mitigations: precompute and store results (generated columns), use functional/expression indexes where the database supports them, or move the calculation to the application layer after a narrow indexed filter.
• The DQL layer adds negligible overhead itself — it compiles to native SQL.

Failure modes

• Silent numerical error — degrees/radians confusion or unintended DECIMAL rounding passing tests but skewing results at scale. Highest-severity failure because it is invisible.
• Platform divergence — works on MySQL, breaks or changes precision on PostgreSQL.
• Upgrade breakage — Doctrine major version invalidates FunctionNode subclasses at query-parse time.
• Dependency unavailability — Bitbucket repo removed or made private; build reproducibility lost without a local vendor copy.
• NULL/edge-case mishandling — domain errors (e.g., ACOS outside [-1, 1]) surfacing as DB exceptions rather than application-level validation.

Ramp-up

• For engineers already fluent in Doctrine DQL: hours. The concepts (FunctionNode, custom function registration) are standard.
• For an Eloquent-only Laravel team: days, because the friction is Doctrine itself (entity mapping, EntityManager bootstrapping, DQL syntax), not the trigonometric functions. Weigh that ramp-up against the trivial effort of a DB::raw() call or a PHP-side calculation.
• Documentation burden is on us regardless of path; the upstream README will not substitute for an internal ADR.

Recommendation: Do not adopt the bundle as a dependency. Evaluate the function classes as reference source, vendor or reimplement the two or three functions actually needed, and gate the decision on a one-day spike proving that DQL-level trig composition is required at all.