Laravel Airports Laravel Package

Technical Evaluation

Architecture fit. The package is a single-responsibility reference-data bundle: a service provider, a facade over an in-memory PHP array of IATA records, an optional Eloquent model/migration/seeder, a validation rule, and two Artisan commands. It follows idiomatic Laravel packaging (auto-discovery, publishable tags, readonly value objects) and sits in the "domain primitives" layer rather than the request/response layer. That makes it a good fit for any product with airport pickers, itinerary imports, autocomplete endpoints, or travel-partner integrations — the lookup surface (find, findOrFail, exists, inCountry, search, options) covers most of the workflows a TPM would scope. It is not a geospatial engine, a fare/route service, or an airline database; scoping expectations accordingly matters.

Integration feasibility. Technically low-effort: composer require, auto-discovery, and a working in-memory lookup on a fresh install with no migration. Realistically the effort is concentrated in identification, not integration. The package presents as two identities — the ijeffro/laravel-airports metadata and README (Laravel 5, dev-master, manual provider registration) versus the v1.0.0 release notes and namespace FLAIRUK\Airports (Laravel 12/13, PHP 8.2+). A TPM should treat "confirm the canonical Packagist name, version, and FQCN" as an explicit, time-boxed spike task before any sprint commitment.

Technical risk.

• Hard fork, no upgrade path. v1.0.0 is a rewrite with a new namespace, new PHP/Laravel floors, and array→readonly-object call-site breakage. There is no in-place upgrade from 0.x; teams on Laravel 8–11 are stranded.
• Documentation is the weakest artifact. README and the short description describe the legacy package, not what ships. Maturity is scored "readme," and the readme is partly wrong. Every integration step must be verified against the code.
• Two sources of truth. The in-memory dataset and the published airports table can drift; reseeding is idempotent but may overwrite locally curated rows.
• Dataset provenance and freshness are undocumented. Airport codes are added, retired, and renamed. Without a stated source and refresh cadence, stale data becomes a product defect the consuming team owns.
• Adoption signal is thin. Four stars, zero dependents, and a single maintainer mean no production track record to lean on.
• Data volume in memory/opcache. A ~10k-row compiled array is fast but non-trivial per process, which is a sizing question for Octane or high worker counts.

Key questions.

1. What is the authoritative package name and namespace to pin in composer.json?
2. What is the dataset's provenance, license, and update cadence, and is there a documented refresh path?
3. Which Laravel/PHP version range is actually supported, and what is the maintainer's support commitment and bus factor?
4. Is the CI suite green and does it cover the validation rule and Eloquent path, not just lookups?
5. What is the measured per-process memory footprint of the dataset?
6. Which source of truth will we declare authoritative — in-memory reference data or the SQL table?
7. What does our own dataset-drift incident look like, and who owns it?

Integration Approach

Stack fit. Only viable for Laravel 12/13 on PHP 8.2+. For anything older, the correct decision is usually not to adopt this package — either stay pinned to the unmaintained 0.x line or vendor a trimmed airport list directly. Confirm no transitive constraint conflicts, then treat adoption as greenfield.

Migration path. There is no migration path, only a replacement path. Plan it as a call-site audit: grep for legacy idioms (getByIata, getByName, whereCountry, pluck, ->merge(, array offsets like $airport['iata']), remove the old provider and Airports alias from config/app.php, then composer dump-autoload and clear config/cache so a cached bootstrap/cache/config.php doesn't produce phantom "class not found" errors. Budget this as real work; it is the largest line item in the plan.

Compatibility. Three compatibility surfaces to verify rather than assume: Laravel/PHP version ceilings against the rest of the dependency graph; Octane and queue workers (the array loads per process — measure before scaling worker counts); and the optional database path, where the published migration's column list must be validated against any belongsTo foreign keys we define. Sparse records (null city/region/coordinates) require null-safe rendering in every Blade and API resource.

Sequencing.

1. Week 0 spike (branch). Resolve package name and FQCN; install; verify find, exists, AirportCode, and the commands in a throwaway app. Timebox and require a written artifact.
2. Pilot one surface. Swap a single form's exists:airports,iata for AirportCode and one autocomplete endpoint for search(). No database, no migration.
3. Adopt normalization at the boundary. A shared strtoupper(trim()) helper or form request, applied consistently — cheap now, painful later.
4. Decide source of truth. Document whether the facade or the Eloquent model is authoritative; publish the migration only when SQL joins, aggregates, or index-backed radius queries justify the second copy.
5. Remediate call sites if replacing 0.x, in the same PR cadence as step 2–3 so behavior changes are attributable.
6. Pin, vendor, and document. Exact version constraint, an internal one-pager on the fork/namespace reality, and a fallback plan (fork or generated array) if upstream stalls.

Operational Impact

Maintenance. This is a low-churn dependency with a high-ownership burden. The code is unlikely to break often; the data and the fork identity are the maintenance surface. Pin an exact version, and assume we — not upstream — will handle dataset refreshes, namespace questions, and doc corrections. Budget a small recurring review, not a large one.

Support. Effectively self-support: one maintainer, four stars, no dependents, and a README that describes a different package than the one shipping. Do not plan on upstream responsiveness for blockers. Internal documentation capturing the verified package name, FQCN, supported versions, and the source-of-truth decision is not optional — it is the support plan.

Scaling. Adequate for typical php-fpm workloads. Two scaling notes for the roadmap: avoid json_encode-ing the full options() payload into every page (filter server-side by country or term, cap search() results, cache only serialized large API responses), and measure memory per process before scaling Octane workers or queue concurrency. Geospatial proximity is fine in PHP for small candidate sets; push to SQL only with the published table and indexes.

Failure modes.

• Stale config cache or leftover provider entries → "class not found" surviving composer update; mitigated by cache-clear in the release checklist.
• Namespace/facade mismatch → binding-resolution errors; mitigated by constructor injection of the underlying service.
• Validation on a valid code → usually lowercase/whitespace input or a wrong-namespace rule class; diagnose with Airports::exists() in tinker.
• Table drift → airports:seed succeeding while local curations are overwritten, or exists:airports,iata failing on a fresh install where the table was never published.
• Silent nulls → find() returning null and sparse records rendering blanks; enforce findOrFail in imports and null-safe accessors in views.
• Stale dataset → a real code rejected at the boundary; detect via a periodic reconciliation job and a monitoring signal on validation rejection rate.

Ramp-up. Low for any Laravel developer — an afternoon to a working pilot, with the README's inconsistencies as the only real speed bump. The hidden ramp is organizational: the call-site audit for 0.x consumers, the source-of-truth decision, and the dataset-governance stance. Those are TPM-owned decisions, not engineering trivia, and should be resolved before the package is promoted beyond a pilot.