PHPackages                             awoods/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. [Utility & Helpers](/categories/utility)
4. /
5. awoods/world

ActiveLibrary[Utility & Helpers](/categories/utility)

awoods/world
============

interact with data from places around the world - the states in the US, the provinces in Canada, validate phone numbers, validate zipcodes/postal codes

0.2.0(7y ago)0858[1 issues](https://github.com/andrewwoods/world/issues)MITPHPPHP >=7.0.0

Since Sep 27Pushed 7mo ago1 watchersCompare

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

READMEChangelogDependencies (2)Versions (5)Used By (0)

World
=====

[](#world)

**Make it simple to work with locations and data about the world**

It should be easy to do things like get a list of US States, Canadian Provinces, and to determine if a postal code or phone number is valid. Some countries don't use postal codes at all, phone numbers have different criteria across countries. This library aims to make things a little easier.

For every country object, you can access the following information:

- Common Name
- Official Name
- ISO 3166-1 alpha 2 code (e.g. US for United States)
- ISO 3166-2 alpha 3 code (e.g. USA for United States)
- ISO 4127 Currency code (e.g. USD for United States Dollars)
- The Continent

The available **interfaces** are:

- PhoneNumberInterface - provide phone number validation method signatures
- PostalCodeInterface - provide postal code validation method signatures
- SubdivisionInterface - provide a subdivision list, e.g. provinces in Canada

The available **traits** are:

- NorthAmericanPhoneNumber
- ZipCode

Version
-------

[](#version)

The current version is 0.2.0. This project uses [semantic versioning](http://semver.org).

License
-------

[](#license)

This is licensed under the [MIT License](https://opensource.org/licenses/MIT).

Example Code
------------

[](#example-code)

### Retrieve Single Country

[](#retrieve-single-country)

```
require 'vendor/autoload.php';

$usa = Awoods\World\CountryFactory::get('US');
echo $usa->getOfficialName(); // Unites States of America

$canada = Awoods\World\CountryFactory::get('CAN');
echo $canada->getCommonName(); // Canada
```

### Loop Over All Countries

[](#loop-over-all-countries)

```
require "vendor/autoload.php";

$countryFactory = new \Awoods\World\CountryFactory();
$countries = $countryFactory->getAllCountries();

foreach ($countries AS $code => $name) {
    echo "\n";
    echo "{$code} is the code for {$name}\n";

    $country = $countryFactory->create($code);

    echo "The official name for {$name} is '{$country->getFullName()}'\n";
    echo "Here is a list of it's localities:\n";

    foreach ($country->getLocalityList() AS $localityCode => $localityName) {
        echo "* {$localityName} ({$localityCode})\n";
    }
}
echo "\n";
```

Currently Supported Countries
-----------------------------

[](#currently-supported-countries)

### North America

[](#north-america)

The countries have additional phone number and postal code validation methods

- United States
- Canada
- Mexico

The countries have basic Country support

- Anguilla
- Antigua and Barbuda
- Aruba
- Bahamas
- Barbados
- Belize
- Bermuda
- British Virgin Islands
- Caribbean Netherlands
- Cayman Islands
- Costa Rica
- Cuba
- Curaçao
- Dominica
- Dominican Republic
- El Salvador
- Greenland
- Grenada
- Guadeloupe
- Guatemala
- Haiti
- Honduras
- Jamaica
- Martinique
- Montserrat
- Nicaragua
- Panama
- **Puerto Rico**
- Sint Maarten
- St. Barthélemy
- St. Kitts and Nevis
- St. Lucia
- St. Martin
- St. Pierre and Miquelon
- St. Vincent and Grenadines
- Trinidad and Tobago
- Turks and Caicos Islands
- **U.S. Virgin Islands**

Upcoming Countries
------------------

[](#upcoming-countries)

- **South America**

    - todo
- **Europe**

    - todo
- **Asia**

    - todo
- **Africa**

    - todo
- **Oceania**

    - todo
- **Antarctica**

    - todo

Ideas for sections/pages
------------------------

[](#ideas-for-sectionspages)

- Traits

    - NorthAmericanPhoneNumber
- Features
- Language Translations

    These 5 languages plus English should cover most developers in the world

    - Spanish
    - French
    - Hindi
    - Chinese (Mandarin)
    - Arabic
- Frequently Asked Questions (FAQ)
- Screenshots
- Submit Issues

Credits and Acknowledgments
---------------------------

[](#credits-and-acknowledgments)

- Project Creator: [Andrew Woods](http://andrewwoods.net)

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance45

Moderate activity, may be stable

Popularity16

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity51

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

Total

3

Last Release

2657d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/78aa0adc8327fc00f762e239f08b7dd6dc0a337c0caa72586a26c4c47aebaba5?d=identicon)[awoods](/maintainers/awoods)

---

Top Contributors

[![andrewwoods](https://avatars.githubusercontent.com/u/1772618?v=4)](https://github.com/andrewwoods "andrewwoods (88 commits)")

---

Tags

countriesgeographylocationsphone-numberspostal-codesZipcodes

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[rinvex/countries

Rinvex Countries is a simple and lightweight package for retrieving country details with flexibility. A whole bunch of data including name, demonym, capital, iso codes, dialling codes, geo data, currencies, flags, emoji, and other attributes for all 250 countries worldwide at your fingertips.

1.7k7.4M48](/packages/rinvex-countries)[league/iso3166

ISO 3166-1 PHP Library

70036.3M116](/packages/league-iso3166)[pragmarx/countries

PHP Countries and Currencies

1.9k3.3M18](/packages/pragmarx-countries)[webpatser/laravel-countries

Modern Laravel Countries package providing ISO 3166-2, ISO 3166-3, currency, capital and more for all countries. Compatible with Laravel 11.x and 12.x.

8272.8M8](/packages/webpatser-laravel-countries)[geokit/geokit

Geo-Toolkit for PHP

251924.7k6](/packages/geokit-geokit)[brick/geo

GIS geometry library

245862.1k15](/packages/brick-geo)

PHPackages © 2026

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