Zodiac Laravel Package

Technical Evaluation

Architecture fit Zodiac is a narrow-domain, stateless calculation library (sign resolution from a date, plus Chinese zodiac). It carries no ORM, config, queue, or HTTP coupling, so it slots in cleanly as a domain utility behind an application service. The one architectural decision to make deliberately: never let the vendor Sign type leak into controllers, Blade templates, or API resources — wrap it in our own value object/service so the dependency stays swappable. Confirm whether a Laravel service provider is auto-discovered; if not, bind it manually rather than instantiating inline.

Integration feasibility Low effort. composer require, one primary class surface, no migrations, no env vars, no published config. Measured in hours, not sprints.

Technical risk Low overall, with two flags introduced or sharpened by 7.1.0:

• JsonSerializable on Sign::class is additive at the API level but a silent contract change for existing consumers. Anywhere a Sign object is currently embedded in a model, API resource, cache payload, or queued job, json_encode output changes shape (likely to a scalar identifier). New adopters are unaffected; existing ones must audit. Pin the emitted shape in a contract test before this reaches a public API.
• PHP 8.6 "tested support" is a forward-compatibility CI signal, not a production runtime guarantee. Do not sequence a PHP 8.6 rollout off the back of this note alone.

The other change (externalized coding standard) is development tooling only and has no runtime footprint.

Key questions

• What exactly does json_encode($sign) emit — a scalar name, an ISO-style code, or a structured array? Is it documented and intended as stable?
• Does the package ship a Laravel service provider/facade, or is wiring entirely manual?
• Are Western zodiac cusp/boundary dates configurable, and do the defaults match the markets we serve?
• Is the Chinese zodiac year boundary Lunar New Year–aware, or hardcoded to January 1? This is the most common correctness defect for our use case and is not addressed anywhere in the release notes.
• What is the support/EOL posture for the 7.x line?

Integration Approach

Stack fit Pure PHP 8.x, no extensions, no framework version constraints that bite — works identically on Laravel 10/11/12. Because it is framework-agnostic, the integration work is entirely ours: a thin ZodiacService plus a container binding. That wrapper is the whole integration.

Migration path Greenfield, so no migration. If this replaces in-house sign logic: run both implementations in parallel behind a feature flag for one release, diff outputs across a full 366-day sweep per supported locale/timezone, then cut over. Boundary-date drift is invisible in code review and glaringly obvious to users.

Compatibility 7.0.3 → 7.1.0 is a clean semver-minor: no removals, no deprecations, no signature changes. JsonSerializable only manifests if we call json_encode on the object. Coding-standard externalization is a require-dev concern and never reaches production. Safe to take on a patch cadence.

Sequencing

1. Pin ^7.1.0, run the full test suite and static analysis.
2. Add a contract test asserting the serialized Sign shape (locks the new behavior deliberately rather than inheriting it).
3. Audit for implicit serialization sites — API resources, cache payloads, queue jobs — and wrap or fix each.
4. Add PHP 8.6 to CI only if we are actually tracking that upgrade.
5. Only then ship the wrapper into application code; behind a flag if replacing existing logic.

Operational Impact

Maintenance Near-zero. Small surface, deterministic output, no configuration to drift. Single maintainer (@olivervogel) but a long-lived, actively maintained org. Our real maintenance cost is the boundary layer, not the package.

Support Community/GitHub issues, no commercial SLA. Acceptable for a non-critical, deterministic calculation. Not acceptable if zodiac data ever becomes billing-adjacent or compliance-relevant. Keep the wrapper thin enough that forking or replacing with ~200 lines of internal logic remains a one-day job.

Scaling Effectively free. Pure CPU, stateless, zero I/O, no memory growth, no connection pool, no async concerns. Negligible per-request cost; cache the resolved sign per user if it ever lands on a hot path.

Failure modes

• Cusp/timezone off-by-one — a UTC-versus-local birthdate flips the sign. Most likely real defect; mitigate with explicit timezone handling at the wrapper.
• Serialization contract drift — newly JsonSerializable objects vs. previously cached or queued payloads decode differently, producing inconsistent responses until caches drain.
• Runtime/extension mismatch on a legacy host.
• Upstream major bump (8.x) forcing a wrapper rewrite — fully mitigated by the boundary layer.

Ramp-up Trivial for any PHP developer. The only learning curve is the domain (zodiac boundaries, Lunar New Year), and that is a product/locale question rather than a code question. No new tooling, no new deploy target, no on-call runbook changes.