World Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require njjeim/world
   

   Publish the config (optional):

   php artisan vendor:publish --provider="World\WorldServiceProvider"
   

2. First Use Case: Fetch all countries via the facade:

   use World\Facades\World;
   
   $countries = World::countries();
   

   Or via API route (/api/countries).

Where to Look First

• Facade API: World\Facades\World for direct method calls (e.g., countries(), states(), cities()).
• API Routes: /api/{endpoint} (e.g., /api/countries, /api/states/{country_id}).
• Config: config/world.php (if publishing config is needed).

Implementation Patterns

Core Workflows

1. Data Retrieval

• Facade Usage:

  // Get all countries
  $countries = World::countries();
  
  // Get states for a country (by ISO code)
  $states = World::states('US');
  
  // Get cities for a state (by country ISO + state code)
  $cities = World::cities('US', 'CA');
  

• API Usage:

  GET /api/countries
  GET /api/states/US
  GET /api/cities/US/CA
  

2. Nested Data Fetching

Combine facade calls for hierarchical data (e.g., country → states → cities):

$country = World::countries()->where('iso', 'US')->first();
$states = World::states('US');
$cities = World::cities('US', $states[0]->code);

3. Integration with Forms/Validation

Use the data for dropdowns or validation:

// Example: Country dropdown in a form
$countries = World::countries()->pluck('name', 'iso');

// Validation rule (custom rule or manual check)
$request->validate(['country' => 'required|in:' . implode(',', World::countries()->pluck('iso'))]);

4. Timezones/Currencies/Languages

Fetch related data for user profiles or settings:

$timezones = World::timezones(); // For user timezone selection
$currencies = World::currencies(); // For payment systems
$languages = World::languages(); // For localization

5. Caching

Cache responses for performance (e.g., in a service provider):

World::countries()->remember(60 * 24); // Cache for 24 hours

Integration Tips

Laravel Ecosystem

• Eloquent Models: Attach relationships to models (e.g., User has a country_id):

  public function country()
  {
      return $this->belongsTo(Country::class, 'country_id')->where('iso', function($query) {
          $query->whereIn('iso', World::countries()->pluck('iso'));
      });
  }
  

• Scout/Algolia: Index country/city data for search:

  Scout::searchable(Country::class);
  

• Nova/Livewire: Use the facade in admin panels or dynamic components:

  // Livewire component
  public $countries;
  public function mount()
  {
      $this->countries = World::countries();
  }
  

API Layer

• API Resources: Transform facade data into API responses:

  namespace App\Http\Resources;
  use World\Facades\World;
  
  class CountryResource extends JsonResource
  {
      public function toArray($request)
      {
          return [
              'id' => $this->iso,
              'name' => $this->name,
              'states' => World::states($this->iso),
          ];
      }
  }
  

• GraphQL: Expose data via GraphQL (e.g., using Laravel GraphQL):

  type Country {
      iso: String!
      name: String!
      states: [State]
  }
  

Localization

• Language Support: Use World::languages() to populate language selectors:

  $languages = World::languages()->pluck('name', 'code');
  

• Translations: Combine with Laravel’s translation system for dynamic labels:

  __('world.countries.'.$country->iso); // If using custom translation files
  

Gotchas and Tips

Pitfalls

1. Data Freshness:

   • The package provides static data. If you need real-time updates (e.g., new countries/cities), consider:
     • Forking the package and updating the data source.
     • Using an external API (e.g., RESTCountries) as a fallback.
   • Tip: Check the changelog for updates.

2. State/City Hierarchy:

   • Not all countries have states/cities (e.g., some use provinces or regions). The package may return empty arrays for these.
   • Tip: Add a check before rendering:

     if (World::states('US')->isNotEmpty()) {
         // Render state dropdown
     }
     

3. API Route Conflicts:

   • The package registers API routes under /api/. If you’re using Laravel’s default API routes (/api), ensure no conflicts:

     // In routes/api.php
     Route::prefix('v1')->group(function () {
         // Your routes
     });
     

   • Tip: Override routes in routes/web.php or routes/api.php if needed.

4. Case Sensitivity:

   • ISO codes (e.g., US, us) are case-sensitive in some methods. Stick to uppercase:

     // Correct:
     World::states('US');
     // Avoid:
     World::states('us');
     

5. Memory Usage:

   • Loading all data at once (e.g., World::countries()) can be memory-intensive for large datasets.
   • Tip: Use pagination or lazy loading where possible:

     $countries = World::countries()->take(100); // Limit results
     

Debugging

1. Missing Data:

   • If a country/state/city is missing, verify the data source in the package’s config/world.php or vendor/nnjeim/world/src/.
   • Tip: Dump the raw data to debug:

     dd(World::countries()->toArray());
     

2. Facade Not Found:

   • Ensure the service provider is registered. Run:

     composer dump-autoload
     php artisan config:clear
     

3. API Routes Not Working:

   • Check if the middleware (e.g., api or auth:api) is blocking access. Test with:

     php artisan route:list | grep world
     

Extension Points

1. Custom Data Sources:

   • Override the data source by publishing the config and extending it:

     // config/world.php
     'data_source' => env('WORLD_DATA_SOURCE', 'default'),
     

   • Tip: Create a trait or service to merge custom data:

     class CustomWorld extends \World\Facades\World
     {
         public static function countries()
         {
             return parent::countries()->merge([/* custom countries */]);
         }
     }
     

2. Adding New Endpoints:

   • Extend the WorldServiceProvider to add custom routes or facade methods:

     // app/Providers/WorldServiceProvider.php
     public function boot()
     {
         World::extend(function ($app) {
             $app->singleton('world.custom', function () {
                 return new CustomWorld();
             });
         });
     }
     

3. Localization Keys:

   • Add custom translation keys for country/state names:

     // resources/lang/en/world.php
     {
         "countries": {
             "US": "United States of America",
             "GB": "United Kingdom"
         }
     }
     

   • Tip: Use a helper to fetch localized names:

     function localizedCountryName($iso)
     {
         return __("world.countries.{$iso}", ['default' => World::countries()->where('iso', $iso)->first()->name]);
     }
     

4. Testing:

   • Mock the facade in tests to avoid hitting the real data:

     World::shouldReceive('countries')->andReturn(collect([/* mock data */]));
     

   • Tip: Use World::fake() if the package supports it (check for testing utilities).

Performance Tips

1. Selective Loading:
   • Only fetch what you need (e.g., `World::countries()->where('continent',