PHPackages                             jszdavid/laravel-world - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. jszdavid/laravel-world

ActiveLaravel-package[Localization & i18n](/categories/localization)

jszdavid/laravel-world
======================

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

v1.0.4(1mo ago)011MITPHPPHP >=8.0

Since Apr 12Pushed 1mo agoCompare

[ Source](https://github.com/jszd2022/laravel-world)[ Packagist](https://packagist.org/packages/jszdavid/laravel-world)[ Docs](https://github.com/jszd2022/laravel-world.git)[ RSS](/packages/jszdavid-laravel-world/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (6)Versions (4)Used By (0)

laravel-world
=============

[](#laravel-world)

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

Installation
------------

[](#installation)

1. Install the package

```
composer require jszd2022/laravel-world
```

2. Publish assets

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

3. Migrate

```
php artisan migrate

```

4. Seed the database

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

```

Configuration
-------------

[](#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
-----

[](#usage)

### PHP API

[](#php-api)

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

#### Retrieve Countries

[](#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

[](#retrieve-states)

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

#### Retrieve Cities

[](#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

[](#caching)

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

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

### API Endpoints

[](#api-endpoints)

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

MethodEndpointDescription`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

[](#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
------

[](#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
-------

[](#license)

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

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance89

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

57d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/511270fe7f3676ed6763cf8b0bff12d99d13732ab8e664853e6dec798643b177?d=identicon)[jszd2022](/maintainers/jszd2022)

---

Top Contributors

[![jszd2022](https://avatars.githubusercontent.com/u/99481700?v=4)](https://github.com/jszd2022 "jszd2022 (12 commits)")

---

Tags

laravelcountriesstatescities

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jszdavid-laravel-world/health.svg)

```
[![Health](https://phpackages.com/badges/jszdavid-laravel-world/health.svg)](https://phpackages.com/packages/jszdavid-laravel-world)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.4k51.0M7.4k](/packages/larastan-larastan)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

76318.2M110](/packages/laravel-mcp)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8733.1M23](/packages/yajra-laravel-oci8)[api-platform/laravel

API Platform support for Laravel

59156.3k10](/packages/api-platform-laravel)[calebdw/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

15104.9k4](/packages/calebdw-larastan)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)