World Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require nnjeim/world
   php artisan vendor:publish --tag=world
   php artisan migrate
   php artisan db:seed --class=WorldSeeder  # (~15 min)
   

   • Verify the world.php config file is published to config/ and adjust table names/fields if needed.

2. First Use Case: Fetch Countries

   use Nnjeim\World\World;
   
   $countries = World::countries()->data;
   

   • Check $action->success to handle failures gracefully.

3. API Endpoint Alternative

   GET /api/countries
   

   • Returns JSON response with success, message, and data keys.

Implementation Patterns

Core Workflows

1. Facade-Based Access

   • Countries: World::countries()
   • States: World::states($countryId)
   • Cities: World::cities($stateId)
   • Timezones: World::timezones()
   • Currencies: World::currencies()
   • Languages: World::languages()

   Example with filtering:

   $states = World::states(182, ['fields' => 'cities'])->data;
   

2. API Integration

   • Use GET /api/{endpoint} with query params:

     GET /api/states?filters[country_id]=182&fields=cities
     

   • Supports fields (e.g., cities) and filters (e.g., country_id).

3. Eager Loading for Performance

   • Fetch nested data in a single query:

     $countryWithStates = World::countries()->with('states')->data;
     

   • Requires defining relationships in the package’s models (check app/Models/ after seeding).

4. Customizing Responses

   • Map responses to DTOs or collections:

     $countries = collect(World::countries()->data)->map(fn($c) => new CountryDto($c));
     

Integration Tips

1. Validation

   • Validate IDs before querying:

     $country = World::countries()->data->firstWhere('id', $request->country_id);
     if (!$country) abort(404);
     

2. Caching

   • Cache static data (e.g., countries) for 24h:

     $countries = Cache::remember('world.countries', 86400, fn() => World::countries()->data);
     

3. Localization

   • Use name_{locale} fields (if published) for multilingual support:

     $country = World::countries()->where('id', 182)->first();
     $name = $country->name_en; // or name_es, etc.
     

4. Testing

   • Mock the facade in tests:

     World::shouldReceive('countries')->andReturn((object) ['success' => true, 'data' => []]);
     

Gotchas and Tips

Pitfalls

1. Seeder Duration

   • The WorldSeeder takes ~15 minutes to run. Avoid running it in CI/CD unless necessary.
   • Workaround: Use a subset of data or mock responses in tests.

2. Table Name Conflicts

   • Default tables (countries, states, etc.) may conflict with existing apps.
   • Fix: Customize table names in config/world.php before seeding.

3. Missing Relationships

   • The package doesn’t auto-load relationships (e.g., states on Country). Define them manually:

     // app/Models/Country.php
     public function states() { return $this->hasMany(State::class); }
     

4. API Rate Limiting

   • The demo API (laravel-world.com) may throttle requests. Prefer local DB access for production.

5. Optional Fields

   • Fields like iso_code, phone_code, or capital are optional. Ensure they’re enabled in config/world.php if needed.

Debugging

1. Check Seeder Status

   • Verify tables exist:

     php artisan db:show
     

   • Re-run seeder if tables are missing.

2. Facade vs. API Inconsistencies

   • Facade and API responses may differ slightly (e.g., field ordering). Standardize on one source.

3. Query Debugging

   • Enable Laravel query logging:

     DB_LOG_QUERIES=true
     

   • Check storage/logs/laravel.log for slow queries.

Extension Points

1. Custom Fields

   • Add columns to existing tables via migrations:

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

   • Update the seeder to populate new fields.

2. Additional Endpoints

   • Extend the API routes in routes/web.php:

     Route::get('/api/custom', function () {
         return World::countries()->with('states')->data;
     });
     

3. Local Overrides

   • Override package models/views by publishing assets:

     php artisan vendor:publish --tag=world-views
     

   • Modify app/Models/ or resources/views/ as needed.

4. Performance Optimization

   • Add indexes to frequently filtered columns (e.g., country_id in states table):

     Schema::table('states', function (Blueprint $table) {
         $table->index('country_id');
     });