World Laravel Package

Getting Started

First Steps

1. Installation:

   composer require nnjeim/world
   php artisan vendor:publish --provider="Nnjeim\World\WorldServiceProvider" --tag="world-migrations"
   php artisan migrate
   

   Verify the world table exists in your database.

2. First Use Case: Fetch all countries via the World Facade in a controller or blade view:

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

   Or via API route: GET /api/countries.

3. Where to Look First:

   • Usage Examples in the README for quick reference.
   • config/world.php for configuration options (e.g., default locale).
   • app/Providers/WorldServiceProvider.php for service binding details.

Implementation Patterns

Core Workflows

1. Data Retrieval:

   • Facade Usage: Prefer the World facade for simplicity in controllers/blades:

     $country = World::country(1); // By ID
     $states = World::states(1);   // States for country ID 1
     $cities = World::cities(1, 2); // Cities for state ID 2 in country ID 1
     

   • Eloquent Models: Access raw models for custom queries:

     use Nnjeim\World\Models\Country;
     $country = Country::with('states.cities')->find(1);
     

2. API Integration:

   • Use predefined routes (e.g., /api/countries/{id}/states) for frontend consumption.
   • Extend API with custom endpoints:

     Route::get('/api/countries/{id}/timezones', function ($id) {
         return World::country($id)->timezones;
     });
     

3. Localization:

   • Override default names (e.g., country names) via config/world.php:

     'localization' => [
         'countries' => [
             'US' => ['name' => 'United States of America (Custom)'],
         ],
     ],
     

   • Publish and translate language files:

     php artisan vendor:publish --tag="world-lang"
     

4. Caching:

   • Enable caching in config/world.php:

     'cache' => true,
     

   • Manually clear cache when data changes:

     php artisan cache:clear
     

5. Validation:

   • Use built-in validation rules in forms:

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

Gotchas and Tips

Pitfalls

1. Database Schema Mismatch:

   • If you modify the world table, reset migrations:

     php artisan migrate:fresh --seed
     

   • Avoid altering the id column (used in relationships).

2. Locale Conflicts:

   • Ensure app.php locale matches config/world.php locale to avoid missing translations.
   • Fallback to en if translations are missing:

     config(['world.locale' => 'en']);
     

3. API Route Conflicts:

   • Prefix routes if using Laravel’s default API routes:

     Route::prefix('v1')->group(function () {
         Route::apiResource('countries', CountryController::class);
     });
     

4. Performance:

   • Eager-load relationships to avoid N+1 queries:

     $country = Country::with(['states.cities', 'timezones'])->find(1);
     

   • Disable caching for development:

     config(['world.cache' => env('APP_ENV') !== 'local']);
     

Debugging

1. Data Integrity:

   • Validate data with:

     php artisan world:validate
     

   • Fix issues via:

     php artisan world:fix
     

2. Missing Data:

   • Check if the package’s seeders ran:

     php artisan db:seed --class=WorldSeeder
     

   • Manually seed if needed.

3. Facade Not Found:

   • Ensure the service provider is registered in config/app.php:

     'providers' => [
         Nnjeim\World\WorldServiceProvider::class,
     ],
     

Extension Points

1. Custom Data Sources:

   • Override the WorldServiceProvider to bind custom repositories:

     $this->app->bind(
         \Nnjeim\World\Contracts\CountryRepository::class,
         \App\Repositories\CustomCountryRepository::class
     );
     

2. Add New Fields:

   • Extend the world table via migrations, then update models:

     class Country extends Model {
         protected $appends = ['custom_field'];
         public function getCustomFieldAttribute() {
             return $this->attributes['custom_field'] ?? null;
         }
     }
     

3. Webhooks/Events:

   • Listen for data updates via package events (if supported in future versions):

     event(new \Nnjeim\World\Events\CountryUpdated($country));
     

4. Testing:

   • Use the World facade in tests:

     $this->assertCount(195, World::countries());
     

   • Mock the facade for isolated tests:

     $this->mock(World::class)->shouldReceive('country')->andReturn($mockCountry);