World Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stellarwhale/world
   

   Publish the config (if needed) with:

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

2. First Use Case: Access countries via the World facade in a controller or service:

   use StellarWhale\World\Facades\World;
   
   $countries = World::countries(); // Returns a collection of all countries
   

3. API Routes: The package registers API routes under /api/world. Test immediately:

   php artisan route:list | grep world
   

   Example: GET /api/world/countries returns JSON of all countries.

Implementation Patterns

Core Workflows

1. Data Retrieval:

   • Facade Usage: Prefer World::countries(), World::states($countryId), etc., for type-hinted access in classes.
   • API Layer: Use /api/world/{resource} for frontend or external services (e.g., React/Vue apps).
   • Eager Loading: Fetch nested data (e.g., country + states + cities) in a single call:

     $country = World::countryWithStatesAndCities($countryId);
     

2. Form Integration:

   • Dropdowns: Use World::countries()->pluck('name', 'id') for Laravel Collective or Livewire dropdowns.
   • Validation: Validate country/state/city IDs with custom rules:

     use StellarWhale\World\Rules\ValidCountryId;
     
     $request->validate(['country_id' => ['required', new ValidCountryId]]);
     

3. Localization:

   • Override default names (e.g., "United States" → "USA") via config:

     'overrides' => [
         'US' => ['name' => 'United States of America'],
     ],
     

4. Caching:

   • Cache responses for API routes or facade calls:

     $countries = Cache::remember('world.countries', now()->addDays(7), function () {
         return World::countries();
     });
     

Integration Tips

• Laravel Scout: Use the package’s data for geolocation-based search (e.g., filter cities by country).
• Laravel Nova: Extend the package to create custom Nova resources for admin management.
• Testing: Mock the facade in unit tests:

  $this->mock(World::class)->shouldReceive('countries')->andReturn(collect([...]));
  

Gotchas and Tips

Pitfalls

1. Data Mutability:

   • The package returns immutable collections (Laravel 8+). Use ->toArray() or ->values() to modify data:

     $countriesArray = World::countries()->toArray();
     

2. ID vs. Code:

   • Countries/States/Cities use numeric IDs (e.g., 1 for "United States").
   • Timezones/Currencies/Languages use ISO codes (e.g., "America/New_York").
   • Always check the structure with dd(World::countries()->first()).

3. API Route Conflicts:

   • The package registers routes under /api/world. If you have a WorldController, rename it to avoid conflicts (e.g., CountryController).

4. Performance:

   • Avoid fetching all cities globally (e.g., World::cities()). Instead, scope by country/state:

     $usCities = World::cities()->where('country_id', 1); // USA
     

Debugging

• Missing Data: Verify the database/world.json file exists (auto-generated on first install). Re-publish config if corrupted:

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

• Facade Not Found: Ensure the service provider is registered in config/app.php under providers.

Extension Points

1. Custom Data Sources:

   • Override the default JSON file by binding a custom repository:

     $this->app->bind('world.repository', function () {
         return new CustomWorldRepository();
     });
     

   • Implement StellarWhale\World\Contracts\WorldRepository.

2. Add New Regions:

   • Extend the states or cities arrays in config/world.php:

     'states' => [
         'US' => [
             'Alaska' => ['id' => 99, 'cities' => [...]],
         ],
     ],
     

3. Localization:

   • Translate names using Laravel’s translation system. Override the name key in config or use a language-specific file:

     'lang' => [
         'en' => ['US' => 'United States'],
         'es' => ['US' => 'Estados Unidos'],
     ],
     

Pro Tips

• Laravel Jetstream: Use the package to pre-populate address fields in the create or update forms.
• Laravel Excel: Export country/state/city data to CSV:

  Excel::download(new CountriesExport, 'countries.csv');
  

• Dynamic Filters: Combine with Laravel’s query builder for dynamic filtering:

  $query = World::cities()
      ->where('country_id', $request->country_id)
      ->when($request->state_id, fn($q) => $q->where('state_id', $request->state_id));