World Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sewidan/world
   php artisan vendor:publish --tag=world
   php artisan migrate
   

   • Publishes config, migrations, and seeders to your project.

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

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

   • Returns a collection of Country models with nested states, cities, and currencies.

3. Quick API Access: The package includes API routes (e.g., /api/countries). Test with:

   php artisan route:list | grep world
   

Implementation Patterns

Core Workflows

1. Data Retrieval:

   • Facade Methods:

     // Get a country by ISO code
     $country = World::country('US');
     
     // Get states for a country
     $states = World::states('US');
     
     // Get cities for a state (e.g., California)
     $cities = World::cities('US', 'CA');
     

   • Eager Loading: Use with() to avoid N+1 queries:

     $country = World::country('US')->load('states.cities');
     

2. Search Functionality (v1.1.12+):

   // Search countries by name
   $results = World::search('United', 'country');
   
   // Search cities in a country
   $results = World::search('New York', 'city', ['country_id' => 'US']);
   

3. API Integration:

   • Use the built-in routes for frontend consumption:

     // Fetch countries via AJAX
     fetch('/api/countries')
       .then(response => response.json())
       .then(data => console.log(data));
     

4. Custom Queries:

   • Access the underlying models directly:

     use Sewidan\World\Models\Country;
     
     $countries = Country::where('name', 'like', '%United%')->get();
     

Integration Tips

1. Form Validation: Integrate with Laravel Validation:

   use Sewidan\World\Rules\ValidCountry;
   
   $request->validate([
       'country_code' => ['required', new ValidCountry],
   ]);
   

2. Localization:

   • Override default names (e.g., for translations) by extending the seeder:

     // app/Database/Seeders/CustomWorldSeeder.php
     public function run()
     {
         $this->call([
             \Sewidan\World\Database\Seeders\CountriesSeeder::class,
             \App\Database\Seeders\CustomCountryNamesSeeder::class, // Your custom logic
         ]);
     }
     

3. Caching: Cache frequent queries (e.g., country lists):

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

4. Partial Seeding:

   • Seed only specific countries/cities to reduce DB size:

     php artisan install:country US  # Only seed USA data
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If upgrading from <1.1.10, run:

     php artisan vendor:publish --tag=world --force
     php artisan migrate:fresh
     

   • The sub_region field was renamed to subregion in v1.1.12. Refresh migrations if needed.

2. Performance with Large Datasets:

   • Avoid loading all cities at once. Use pagination:

     $cities = World::cities('US', 'CA')->paginate(20);
     

3. API Route Conflicts:

   • The package registers routes under /api/world/*. Ensure no naming clashes with your existing routes.

4. Seeder Overwrites:

   • Running php artisan db:seed --class=WorldSeeder drops and recreates all tables. Use --force cautiously in production.

Debugging Tips

1. Check Config:

   • Verify config/world.php for:
     • allowed_countries/disallowed_countries (restricts seeding).
     • Custom table names (e.g., countries_table).

2. Log Seeder Issues:

   • Add debug logs in app/Database/Seeders/WorldSeeder.php if seeding fails:

     \Log::info('Seeding countries...', ['count' => Country::count()]);
     

3. Validate Data:

   • Use Tinker to test queries:

     php artisan tinker
     >>> \Sewidan\World\Models\Country::where('iso', 'US')->first();
     

Extension Points

1. Custom Fields:

   • Extend the Country, State, or City models in app/Models:

     namespace App\Models;
     
     use Sewidan\World\Models\Country as BaseCountry;
     
     class Country extends BaseCountry
     {
         protected $appends = ['custom_field'];
     }
     

2. Add New Regions:

   • Extend the seeder to include custom regions (e.g., districts):

     // app/Database/Seeders/CustomRegionsSeeder.php
     public function run()
     {
         DB::table('regions')->insert([
             ['country_id' => 1, 'name' => 'District A', 'type' => 'district'],
         ]);
     }
     

3. Override API Responses:

   • Publish the API controllers and modify them:

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

   • Edit app/Http/Controllers/World/CountryController.php to customize responses.

4. Timezones:

   • The package includes timezones. Use them in your app:

     $timezones = World::timezones('US'); // Get timezones for a country