Laravel Aircrafts Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ijeffro/laravel-aircrafts
   

   (Note: Use dev-master for Laravel 5 compatibility if needed. Check the README "Requirements" section for the officially supported PHP/Laravel matrix.)

2. Register Service Provider & Facade: Add to config/app.php:

   'providers' => [
       IJeffro\Aircrafts\AircraftsServiceProvider::class,
   ],
   'aliases' => [
       'Aircrafts' => IJeffro\Aircrafts\AircraftsFacade::class,
   ]
   

3. Install & Migrate:

   php artisan aircrafts:install --migrate
   

   This is the recommended one-shot installer for the aircraft dataset. If you prefer finer control, publish the config first:

   php artisan vendor:publish --provider="IJeffro\Aircrafts\AircraftsServiceProvider"
   

   (Configures the table name and the new sortBy mapping used for default ordering of results.)

4. First Use Case: Fetch an aircraft by IATA code in a controller:

   use Aircrafts;
   
   $aircraft = Aircrafts::findByIata('A320');
   dd($aircraft->name); // Output: Airbus A320
   

Implementation Patterns

Core Workflows

1. Data Retrieval:

   • By IATA Code:

     $aircraft = Aircrafts::findByIata('B737');
     

   • By Manufacturer:

     $boeingAircrafts = Aircrafts::where('manufacturer', 'Boeing')->get();
     

   • All Aircrafts:

     $allAircrafts = Aircrafts::all();
     

2. Integration with Eloquent Models: Add a relationship to a Flight model:

   public function aircraft()
   {
       return $this->belongsTo(Aircraft::class, 'aircraft_iata');
   }
   

   Then fetch:

   $flight->aircraft->name; // e.g., "Boeing 747"
   

3. Validation: Use the facade to validate IATA codes in Form Requests:

   public function rules()
   {
       return [
           'aircraft_iata' => 'required|exists:aircrafts,iata_code',
       ];
   }
   

4. Caching: Cache frequent queries (e.g., manufacturer lists):

   $manufacturers = Cache::remember('aircraft_manufacturers', now()->addHours(1), function () {
       return Aircrafts::distinct()->pluck('manufacturer');
   });
   

Advanced Patterns

• Accepting Codes from JSON Clients: Since v1.0.1, AircraftCode accepts integers as well as strings, so you can feed request payloads directly:

  use IJeffro\Aircrafts\AircraftCode;
  
  $code = new AircraftCode($request->input('aircraft_code')); // accepts 738 or "738"
  

  This matters for numeric IATA/ICAO codes such as 738 (Boeing 737-800) that arrive from JSON as integers.

• Working with codes() Output: codes() now guarantees every entry is a string (previously all-digit codes like 738 came back as integers). Use === string comparisons safely:

  $codes = Aircrafts::codes();           // ['738', '320', ...]
  in_array('738', $codes, true);         // true — no more integer/string surprises
  

• Dynamic Sorting via sortBy: The config now exposes a sortBy mapping for default ordering. Tune it once in config/aircrafts.php rather than appending orderBy() across the codebase:

  // config/aircrafts.php
  'sortBy' => [
      // map user-friendly sort keys to DB columns
      'name'         => 'name',
      'manufacturer' => 'manufacturer',
      'range'        => 'range_km',
  ],
  

• Dynamic Filtering: Combine with Laravel Scout for search:

  use Aircrafts;
  
  $results = Aircrafts::search('787')->get();
  

• API Responses: Normalize aircraft data for APIs:

  return response()->json([
      'data' => Aircrafts::findByIata($request->aircraft)->toArray(),
  ]);
  

• Seeding:

  php artisan aircrafts:install --migrate
  

  Or, if you need manual control over the migration step:

  php artisan vendor:publish --provider="IJeffro\Aircrafts\AircraftsServiceProvider" --tag=migrations
  php artisan migrate
  

Gotchas and Tips

Pitfalls

1. Laravel 5 Compatibility:

   • The dev-master branch is explicitly for Laravel 5. For Laravel 6+, check for updates or fork the package.
   • Check the README's "Requirements" section (updated in v1.0.1) before pinning a version.

2. Missing Migrations:

   • The package does not auto-migrate the aircraft database on install. Use php artisan aircrafts:install --migrate (recommended) or publish and run migrations manually:

     php artisan vendor:publish --provider="IJeffro\Aircrafts\AircraftsServiceProvider" --tag=migrations
     php artisan migrate
     

3. Case Sensitivity:

   • IATA codes are case-sensitive in queries. Always use uppercase:

     // Correct:
     Aircrafts::findByIata('A380');
     // Incorrect (may return null):
     Aircrafts::findByIata('a380');
     

4. codes() Return Type (fixed in v1.0.1):

   • Before v1.0.1, all-digit codes such as 738 were returned as integers while other codes were strings. If you're on an older version, coerce explicitly:

     $codes = array_map('strval', Aircrafts::codes());
     

   • On v1.0.1+ you can rely on === string checks. Don't downcast with (int) — "738" and 738 are both expected to resolve correctly through AircraftCode, but only the string form is canonical in codes() output.

5. Passing Raw JSON Values to AircraftCode:

   • v1.0.1 explicitly supports integer input (e.g. 738) so JSON payloads work. Prior versions required casts at the boundary. If you're on an older release, cast at the edge of your app:

     $code = new AircraftCode((string) $request->input('aircraft_code'));
     

6. Data Freshness:

   • The package ships with a static dataset. For real-time updates, consider:
     • Writing a cron job to sync with an external API (e.g., OpenAirlines).
     • Forking and extending the package to include an updater.

Debugging Tips

1. Check Published Config: Verify config/aircrafts.php for custom table names, sortBy mapping, and other settings:

   'table'  => 'aircrafts', // Default; adjust if needed
   'sortBy' => [ /* column mapping */ ],
   

2. Query Logs: Enable Laravel query logging to debug slow queries:

   DB::enableQueryLog();
   $aircraft = Aircrafts::findByIata('A320');
   dd(DB::getQueryLog());
   

3. Facade vs. Direct Model: Prefer the facade for consistency, but use the underlying model (\IJeffro\Aircrafts\Models\Aircraft) for advanced queries:

   use IJeffro\Aircrafts\Models\Aircraft;
   
   $customQuery = Aircraft::where('range_km', '>', 10000)->get();
   

4. Verify codes() Types: When debugging type-related bugs, inspect codes() output directly:

   array_map(fn ($c) => gettype($c), Aircrafts::codes()); // all "string" on v1.0.1+
   

Extension Points

1. Add Custom Fields: Extend the aircrafts table migration:

   Schema::table('aircrafts', function (Blueprint $table) {
       $table->string('custom_field')->nullable();
   });
   

2. Create a Decorator: Override the facade to add custom logic:

   class CustomAircraftsFacade extends AircraftsFacade
   {
       public static function getByRange($minRange)
       {
           return parent::where('range_km', '>=', $minRange)->get();
       }
   }
   

   Register it in config/app.php.

3. Localization: Add translated aircraft names by publishing the language files:

   php artisan vendor:publish --provider="IJeffro\Aircrafts\AircraftsServiceProvider" --tag=lang
   

   Then extend resources/lang/en/aircrafts.php.