Laravel Aircrafts Laravel Package

Technical Evaluation

Architecture Fit

• Lightweight Data Package — now with a persistence option: The package still provides static IATA aircraft codes (ISO 3166-3 and country codes) via a Laravel facade, but v1.0.1's aircrafts:install --migrate command reveals an installable migration path that was not visible in the prior assessment. This materially changes the architecture story: the package can now be treated as seeded reference data in the database rather than purely in-memory/embedded data. For data-driven applications (aviation, logistics, travel), a DB-backed reference table is often preferable — it enables joins, foreign keys, admin correction, and reporting without forking vendor code.
• Typed domain object: AircraftCode is a value object, not a loose string lookup. This aligns better with modern Laravel domain-driven patterns than the previously assumed facade-only Aircrafts::find($code) call. It gives us a natural seam for validation, casting, and custom Eloquent casts on our own models.
• JSON-boundary hardening: Accepting an integer such as 738 in AircraftCode is a direct response to how JSON clients serialize numeric-looking codes. This is a real architecture fit improvement for API-first consumers, closing a class of 422/500 errors at the request boundary.
• sortBy mapping: Indicates configurable ordering semantics. Useful for deterministic dropdown ordering (e.g., by manufacturer vs. code), but it implies configuration surface we must own and document internally.
• Still limited business logic: No CRUD, no live flight data, no real-time updates. Remains reference data only.
• Legacy dependency unchanged: v1.0.1 is a patch release; the Laravel 5 lineage and the abstraction requirement for Laravel 8+/9+ still stand. Do not read this release as a modernization signal.

Integration Feasibility

• Lower effort than previously assessed: php artisan aircrafts:install --migrate replaces manual provider/alias editing plus bespoke seeding. This is the single biggest feasibility improvement — it converts a half-day integration into roughly an hour.
• Database dependency now optional-but-real: The --migrate flag implies a publishable schema. We must decide explicitly between (a) static/embedded mode (zero DB footprint, no joins) and (b) migrated reference table (queryable, joinable, correctable). This is now a design decision rather than a constraint.
• README now documents requirements: The documented-requirements gap in the prior assessment is partially closed, reducing guesswork on PHP/Laravel floors.
• Facade access retained: Still no HTTP endpoints; integration remains a code-level concern inside our service layer.

Technical Risk

• Bug fix confirms real correctness exposure: All-digit codes (738, 320, 777) returning as integers was not cosmetic — it breaks strict comparisons (=== '738'), array-key lookups, cache keys, and JSON contracts where clients expect strings. Any code we shipped against the prior version that compared loosely would have masked this; anything comparing strictly would have failed intermittently. Audit existing call sites for strict comparisons and string casts.
• Behavioral change in a patch release: codes() now returns strings for all codes. Consumers relying on integer returns for all-digit codes will see changed output. This is a semver-hygiene concern (behavior change shipped as v1.0.1) and signals the maintainer may not treat return types as a stable contract. Treat every minor/patch bump as potentially behavior-changing until proven otherwise.
• Laravel version mismatch (unchanged): Still the highest residual risk for Laravel 8+. Mitigation remains a service-layer wrapper or a fork.
• Data accuracy / update mechanism (unchanged): Still no documented upstream refresh process. --migrate makes refreshing easier but not automatic.
• No visible test suite: The integer/string regression is exactly the class of bug a single unit test would have caught. Its existence in a shipped release is evidence that test coverage remains absent or thin.
• Documentation gaps narrowing but present: Requirements and install/sortBy are now documented; error semantics for invalid codes and the migration's upgrade/rollback behavior are not.

Key Questions

1. Migration scope: What does the migration create — one table or several, with what indexes and FKs? Is it idempotent and safe to re-run in CI and in production deploy pipelines?
2. Mode selection: Is --migrate optional (static data fallback) or does the package now require the table? What is the supported upgrade path from the pre-1.0.1 static mode to migrated mode?
3. codes() contract: Is string return now guaranteed and documented as stable, or should we cast defensively at the boundary regardless?
4. AircraftCode semantics: On an unknown code, does it throw, return null, or return a null-object? Does integer acceptance extend to other numeric-ish fields?
5. sortBy surface: Which keys are supported, is it config-driven or argument-driven, and is it stable API or incidental?
6. Laravel support matrix: Do the now-documented requirements explicitly exclude Laravel 5, or only list a floor? Any plan to modernize dependencies (a v2 signal we'd wait for)?
7. Maintenance posture: Given a behavioral change shipped as a patch, is there a release policy we can depend on, or must we pin exact versions?

Integration Approach

Stack Fit

• Best For:
  • Laravel 5.x applications (direct use).
  • Laravel 8+/9+ applications wrapped in a service layer (unchanged requirement).
  • Projects needing queryable reference data — now a first-class fit thanks to aircrafts:install --migrate.
  • API-first backends — the integer-tolerant AircraftCode removes a common ingestion failure when JSON clients post 738.
• Poor Fit:
  • Applications needing dynamic aircraft data (live flight tracking, tail-number registries).
  • Teams unwilling to own a DB schema from a third-party package (static mode is the escape hatch, but verify it is still supported).
  • Environments with strict migration governance where vendor-shipped migrations require DBA review.

Migration Path

1. Pin the version explicitly ("vendor/package": "1.0.1"). Given the patch-level behavior change, floating constraints (^1.0, dev-master) are no longer acceptable.
2. Choose a mode and record the decision:
   • Static mode: no migration; keep facade calls behind the service layer.
   • Migrated mode (recommended for new work): run php artisan aircrafts:install --migrate in a controlled environment, inspect the generated schema, and promote it through the standard migration pipeline.
3. Wrap the facade (unchanged, still required for Laravel 8+):

   class AircraftService {
       public function findByCode(string|int $code): ?AircraftCode {
           return Aircrafts::find((string) $code); // normalize at the boundary
       }
   }
   

   Normalize to string inside the wrapper, not at every call site — this is the durable fix for the v1.0.1 bug class and protects us from future reversals.
4. Audit existing call sites for strict comparisons, array keys keyed by code, cache keys, and JSON responses that previously emitted integers. Add casts where needed.
5. Validate at the boundary: form requests / middleware for inbound codes, including the integer case, before reaching business logic.
6. Order deterministically using the documented sortBy mapping rather than ad-hoc usort.

Compatibility

• Laravel 5.x: Compatible.
• Laravel 8+/9+: Still partial — abstraction required; this release does not address the underlying Laravel 5 coupling.
• PHP: Documented requirements now available in the README; validate against our target runtime before pinning.
• Return-type contract: codes() now string across the board — verify downstream producers and API response shapes.
• Dependencies: Still no external services; risk confined to Laravel core compatibility and our own migration ownership.

Sequencing

1. Pin and diff: Pin v1.0.1, read the README requirements, and diff codes() output against current production output for a representative sample.
2. Decide static vs. migrated and document the rationale; if migrated, dry-run the install command in a throwaway environment and capture the schema.
3. Refactor to the service wrapper with string normalization at the boundary.
4. Add regression tests for all-digit codes (738, 320, 777) covering both integer and string inputs, and for unknown-code handling.
5. Validate data integrity against IATA standards; log invalid lookups.
6. Schedule periodic data review (quarterly) and reassess fork viability if the package becomes critical.

Operational Impact

Maintenance

• Moderate and now better-defined: The install command formalizes setup and upgrades, reducing bespoke maintenance. But adopting the migration transfers schema ownership to us — a new ongoing maintenance obligation (migration review, rollback planning, backup coverage) that the static mode avoided.
• Version-pinning discipline required: A behavioral change in a patch release means we should pin exact versions and review diffs before bumping, not accept automatic updates.
• Dependency risk unchanged: Low community activity and Laravel 5 lineage still point to eventual abandonment. Fork readiness is the contingency.
• Update strategy: Quarterly IATA review; on each release, re-run the all-digit-code regression suite before promoting.

Support

• Slightly improved: README now covers requirements, install, and sortBy — the three gaps that previously required reverse-engineering.
• Still limited community: No visible issue tracker activity; expect self-support.
• Remaining documentation gaps: error semantics for invalid codes, migration rollback guidance, and AircraftCode failure behavior.
• Workarounds that still apply: log invalid lookups, cache critical reference data locally, maintain internal docs for data fields and edge cases.

Scaling

• Static mode: no scaling concerns; watch eager-load impact on boot time in large apps.
• Migrated mode: standard relational scaling — index the code column, ensure the reference table is read-only at runtime, and cache aggressively (this data changes rarely, so a long-TTL cache or in-process array is appropriate). No write concurrency concerns since we never write to it.
• Boundary normalization is O(1) and negligible.
• Concurrency: safe; no shared mutable state.

Failure Modes

Ramp-Up

• Developer onboarding: Reduced to ~1 hour for a basic static-mode integration; ~2–3 hours for migrated mode including schema review. The install command and expanded README removed most of the prior guesswork.
• Key learning curve: Choosing and owning static vs. migrated mode; understanding the AircraftCode value object's failure semantics; internalizing that all codes are strings at the boundary.
• Documentation gaps to close internally: data field reference, invalid-code handling policy, migration rollback procedure, and the supported sortBy keys.
• Recommendation: Ship a short internal ADR covering mode selection, string normalization, and the version-pinning policy — this release's behavior change makes those decisions worth writing down once rather than rediscovering per integration.