PHPackages                             thecoder/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. thecoder/world

ActiveLibrary

thecoder/world
==============

World location data

v2.0.1(8mo ago)21642[1 issues](https://github.com/mbpcoder/world/issues)MITPHPPHP >=8.2

Since Feb 14Pushed 8mo ago1 watchersCompare

[ Source](https://github.com/mbpcoder/world)[ Packagist](https://packagist.org/packages/thecoder/world)[ RSS](/packages/thecoder-world/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (4)Versions (4)Used By (0)

🌍 World - PHP & Laravel Package for Geographical Data
=========================================================

[](#-world---php--laravel-package-for-geographical-data)

**World** is a powerful PHP and Laravel package for retrieving structured geographical data, including **continents, countries, provinces, and cities**. This package is lightweight, optimized for performance, and seamlessly integrates with Laravel applications.

---

🚀 Features
----------

[](#-features)

✔ Get all **continents, countries, provinces, and cities**
✔ Filter countries by continent
✔ Retrieve provinces and cities for any country
✔ Optimized for **high performance** with caching
✔ Compatible with **Laravel and PHP**
✔ Includes **migrations and seeding** for easy setup
✔ includes a Laravel Facade for simpler usage!

---

📦 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require thecoder/world
```

If auto-discovery is not working, manually add the service provider in `config/app.php`:

```
TheCoder\World\WorldServiceProvider::class,
```

### 🔧 Publish Configuration & Migrations for Greater Flexibility

[](#-publish-configuration--migrations-for-greater-flexibility)

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

This will publish:
✅ `config/world.php` (configuration file)
✅ Database migration files

### 🛠 Migrate the Database

[](#-migrate-the-database)

```
php artisan migrate
```

### 🌍 Seed Geographical Data

[](#-seed-geographical-data)

```
php artisan world:seed
```

This will populate the database with continents, countries, provinces, and cities.

---

🔍 Usage
-------

[](#-usage)

### 1️⃣ Using the Built-in World Facade (Recommended)

[](#1️⃣-using-the-built-in-world-facade-recommended)

The package now includes a **World** Facade, making it easier to access data:

```
use World;

$continents = World::continents()->get();  // Get all continents
$countries = World::countries()->get();  // Get all countries
```

### 2️⃣ Manually Instantiate the Class

[](#2️⃣-manually-instantiate-the-class)

```
use TheCoder\World;

$world = new World();

$continents = $world->continents()->get();
$countries = $world->countries()->get();
```

### Get Locations

[](#get-locations)

```
$location = World::byId(1)->first();

$location = World::byEnglishName('Asia')->first();

$locations = World::byIds([1,2])->get();

$locations = World::byEnglishNames(['Iraq', 'Iran'])->get();

$location = World::count();
```

### Get Countries by Continent

[](#get-countries-by-continent)

```
$asia = World::continents('Asia')->first();

$asia = World::continents()->byEnglishName('Asia')->first();

$asiaCountries = World::continents()->byEnglishName('Asia')->countries()->get();
```

### Get Provinces & Cities

[](#get-provinces--cities)

```
$iranProvinces = World::countries('Iran')->provinces()->get();

$iranProvinces = World::countries()->byEnglishName('Iran')->provinces()->get();

$gilanCities = World::provinces('Gilan')->cities()->get();

$gilanCities = World::provinces()->byEnglishName('Gilan')->cities()->get();
```

---

⚡Caching for Maximum Performance
--------------------------------

[](#caching-for-maximum-performance)

Since the World database is static and never changes, this package supports permanent caching to eliminate redundant database queries and significantly improve performance.

### Enable Caching

[](#enable-caching)

You can enable caching in the `config/world.php` file:

```
  'cache' => [
      'enabled' => true,
      'prefix' => 'thecoder-world-',
      'tag' => 'thecoder-world',
      'ttl' => null, // Store cache forever
  ],
```

Setting ttl to null ensures that data is cached forever.

### Use Cached Data in Queries

[](#use-cached-data-in-queries)

If caching is enabled, queries will automatically store results in the cache forever.

### Manually Clear Cache (If Needed)

[](#manually-clear-cache-if-needed)

To clear the cache manually, run:

```
  php artisan cache:clear
```

Or in code:

```
World::clearCache();
```

---

🏗 Package-Integrated Laravel Facade
-----------------------------------

[](#-package-integrated-laravel-facade)

The package now provides a **World** Facade out-of-the-box, meaning Laravel users **don't need to set it up manually**.

✔ **No need to register aliases**
✔ **Works automatically in Laravel**

Just install the package and start using it:

```
use World;

$continents = World::continents()->get();
```

---

🧪Testing
--------

[](#testing)

Ensure you have the necessary dependencies installed:

```
composer install --dev
```

### ⚠️ Database Configuration for Testing

[](#️-database-configuration-for-testing)

Due to special columns in the database, SQLite is not supported for testing.

Instead, configure MySQL in phpunit.xml:

```

```

### ▶️ Running tests

[](#️-running-tests)

```
vendor/bin/phpunit
```

🗄 Database Schema
-----------------

[](#-database-schema)

This package provides a **locations table** designed to store structured geographic data with hierarchical relationships.

ColumnTypeDescription`id`Integer (PK)Unique identifier`continent_id`Integer (FK)Parent continent (nullable)`country_id`Integer (FK)Parent country (nullable)`province_id`Integer (FK)Parent province (nullable)`iso_code`String (3)ISO country code (e.g., "US")`type`Enum`continent`, `country`, `province`, `city``english_name`StringLocation name in English`native_name`StringLocal name (optional)`timezone`StringTime zone (e.g., "Asia/Tehran")`is_capital`BooleanMarks capital cities (default: false)`priority`IntegerSort priority (default: 0)`center`POINTGeographic coordinates`area`MULTIPOLYGONSpatial data for regions✅ **Indexed for fast queries**
✅ **Supports geographic coordinates & boundaries**

---

❓ FAQ
-----

[](#-faq)

### 🔹 What is this package used for?

[](#-what-is-this-package-used-for)

It helps developers retrieve geographical data (continents, countries, provinces, and cities) for Laravel & PHP applications.

### 🔹 Is this package compatible with Laravel?

[](#-is-this-package-compatible-with-laravel)

Yes! It fully supports Laravel and can also be used in vanilla PHP projects.

### 🔹 How can I filter countries by continent?

[](#-how-can-i-filter-countries-by-continent)

```
World::continents('Europe')->countries()->get();
```

### 🔹 Can I get cities of a specific province?

[](#-can-i-get-cities-of-a-specific-province)

```
World::provinces('California')->cities()->get();
```

---

⭐ Contribute & Support
--------------------------

[](#-contribute--support)

🔹 **GitHub Repository:** [thecoder/world](https://github.com/thecoder/world)
🔹 **Issues & Features:** [Submit Here](https://github.com/thecoder/world/issues)
🔹 **Contribute:** Fork, star ⭐, and submit PRs

💡 **Need more features?** Open an issue or contribute to the project!

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance57

Moderate activity, may be stable

Popularity18

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity52

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 ~95 days

Total

3

Last Release

268d ago

Major Versions

v1.0.0 → v2.0.02025-02-21

PHP version history (2 changes)v1.0.0PHP >=8.1

v2.0.1PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/47ca7d89ddf7e0cd20c6c17b516919c1de6bf1af2702e37999ec296954ecf51a?d=identicon)[mb-programmer](/maintainers/mb-programmer)

---

Top Contributors

[![mbpcoder](https://avatars.githubusercontent.com/u/3877538?v=4)](https://github.com/mbpcoder "mbpcoder (67 commits)")

---

Tags

laravelphp

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[fumeapp/modeltyper

Generate TypeScript interfaces from Laravel Models

196277.9k](/packages/fumeapp-modeltyper)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

44643.1k1](/packages/pressbooks-pressbooks)[api-platform/laravel

API Platform support for Laravel

59126.4k6](/packages/api-platform-laravel)[dragon-code/migrate-db

Easy data transfer from one database to another

15717.4k](/packages/dragon-code-migrate-db)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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