jszdavid/laravel-world

A Laravel package which provides a list of the countries, states and cities based on nnjeim/world

v1.0.4 2026-04-13 13:24 UTC

Requires

• php: >=8.0
• illuminate/database: ^8.0|^9.0|^10.0|^11.0|^12.0|13.0
• illuminate/http: ^8.0|^9.0|^10.0|^11.0|^12.0|13.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0|13.0
• illuminate/validation: ^8.0|^9.0|^10.0|^11.0|^12.0|13.0

Requires (Dev)

• orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.0|^10.0|^11.0

MIT

• J. Sz. David

• laravel
• states
• countries
• cities

README

A Laravel package which provides a list of the countries, states and cities based on nnjeim/world.

Installation

1. Install the package

composer require jszd2022/laravel-world

1. Publish assets

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

1. Migrate

php artisan migrate

1. Seed the database

php -d memory_limit=512M artisan db:seed --class=WorldSeeder

Configuration

The package comes with a default configuration file. You can customize the table names, API route prefix, and filter which countries to seed.

// config/laravel-world.php

return [
    'countries' => [
        'only' => null,   // Array of ISO2 codes to include (e.g., ['US', 'GB'])
        'except' => null, // Array of ISO2 codes to exclude
    ],

    'routes' => [
        'enabled' => true,
        'prefix' => 'api',
    ],

    'migrations' => [
        'countries' => [
            'table_name' => 'laravel-world-countries',
        ],
        'states' => [
            'table_name' => 'laravel-world-states',
        ],
        'cities' => [
            'table_name' => 'laravel-world-cities',
        ],
    ],
    
    'cache_ttl' => 604800, // 1 week
];

Usage

PHP API

You can use the World facade to retrieve countries, states, and cities.

Retrieve Countries

use JSzD\World\Facades\World;

// Get all countries (default fields: id, name, iso2)
$countries = World::countries([])->data;

// Get countries with specific fields and search
$countries = World::countries([
    'fields' => 'id,name,iso2,phone_code',
    'search' => 'United',
])->data;

// Filter countries
$countries = World::countries([
    'filters' => [
        'iso2' => 'US'
    ]
])->data;

Retrieve States

// Get states for a country
$states = World::states([
    'filters' => [
        'country_code' => 'US'
    ]
])->data;

Retrieve Cities

// Get cities for a state
$cities = World::cities([
    'filters' => [
        'state_id' => 123
    ]
])->data;

// Get cities for a country
$cities = World::cities([
    'filters' => [
        'country_code' => 'US'
    ]
])->data;

Caching

You can chain the withCaching() method to cache the result of the query.

$countries = World::withCaching()->countries([])->data;

API Endpoints

If enabled in the configuration, the following API endpoints are available:

Method	Endpoint	Description
GET	/api/countries	List all countries
GET	/api/countries/{country_code}/states	List states for a country
GET	/api/countries/{country_code}/cities	List cities for a country

Query Parameters

All endpoints support the following query parameters:

• fields: Comma-separated string of fields to return (e.g., id,name).
• filters[field]: Filter by a specific field.
• search: Search by name (using LIKE %search%).

Example: GET /api/countries?fields=name,phone_code&search=Hung

Models

The package provides the following Eloquent models:

• JSzD\World\Models\Country
• JSzD\World\Models\State
• JSzD\World\Models\City

You can use these models to define relationships in your own models:

public function country()
{
    return $this->belongsTo(\JSzD\World\Models\Country::class);
}

License

The MIT License (MIT). Please see License File for more information.