World Laravel Package

Getting Started

Start by installing the package via Composer and running php artisan world:install (or manually publish config, run migrations, and seed with WorldSeeder). The package immediately provides country/state/city data and — since v1.1.38 — IP geolocation via World::geolocate(). Your first use case will likely be fetching a list of countries or populating a country/state/city dropdown in a registration form.

Implementation Patterns

Use the World facade for most queries (e.g., World::countries(['filters' => ['iso2' => 'FR']])) for consistency and flexibility. For state/city selection, chain filters and fields: World::states(['filters' => ['country_id' => 77], 'fields' => 'cities']). Leverage the API routes (/api/{prefix}/countries, /api/states, etc.) to power AJAX-driven select boxes. Integrate World::geolocate() into registration or shipping flows: World::geolocate(['ip' => $ip]) returns linked Eloquent models, letting you pre-fill addresses. Use WorldHelper in services where dependency injection is preferred. Keep data fresh by scheduling php artisan world:geoip (once MaxMind license is configured) or periodically re-seeding via the seeder.

Gotchas and Tips

• Mandatory re-publish on upgrade: Always run php artisan vendor:publish --tag=world --force after upgrading — config changes often add required options (e.g., GeoIP fallback toggles).
• GeoIP fallback is silent but matters: The free ip-api.com fallback hits a 45 req/min limit and fails silently if exceeded. Prefer local GeoLite2 in production; set WORLD_GEOLOCATE_FALLBACK_API=false in .env to fail fast and debug.
• IP detection is header-aware but fragile: Ensure reverse proxies (Cloudflare, Nginx) correctly forward CF-Connecting-IP, X-Forwarded-For. In local development, explicitly pass ['ip' => '127.0.0.1'].
• IDs tie to database: Geolocation responses include IDs only if a matching country/state/city exists in the local database — otherwise, raw values are returned. Confirm seeding completed successfully (world_countries, world_states, world_cities tables populated).
• Fields vs relations: Use fields=states,cities to eager-load relations in a single query. Avoid over-fetching: only request needed fields to reduce payload size.
• Localization: The package supports locale-aware responses, but you must configure config/world.php — default behavior returns English names unless overridden.
• Performance: For high-traffic apps, cache results (e.g., World::countries(['search' => 'France'])->cache(3600)) or use the API as a backend-only resource to avoid repeated DB lookups.