PHPackages human018/laravel-earth - 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. human018/laravel-earth ActiveLibrary[Localization & i18n](/categories/localization) human018/laravel-earth ====================== A multilingual Laravel package to populate continents, countries, regions and cities for planet Earth v1.4.0(3mo ago)4496MITPHPPHP >=8.2 Since Nov 26Pushed 2mo ago1 watchersCompare [ Source](https://github.com/Human018/laravel-earth)[ Packagist](https://packagist.org/packages/human018/laravel-earth)[ RSS](/packages/human018-laravel-earth/feed)WikiDiscussions master Synced 3w ago READMEChangelog (7)Dependencies (6)Versions (25)Used By (0) [![Contributors](https://camo.githubusercontent.com/fd13a27f28cc3d562009c7603897ec2db56a4827df76e792e50db4f3560a0f6c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6e7472696275746f72732f68756d616e3031382f6c61726176656c2d65617274682e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/Human018/laravel-earth/graphs/contributors)[![Forks](https://camo.githubusercontent.com/f097f1ec0075b01b87dad433863f831c2309e91e0a32125ec63a23d3d9aed771/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f68756d616e3031382f6c61726176656c2d65617274682e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/Human018/laravel-earth/network/members)[![Stargazers](https://camo.githubusercontent.com/9daca5d179d8e79608faf7b42019fdd2c73f7711ca1912a9d169631ad62c9763/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f68756d616e3031382f6c61726176656c2d65617274682e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/Human018/laravel-earth/stargazers)[![Issues](https://camo.githubusercontent.com/7112cb02789a4ab6bccd99a359467e5143152d2682f157439775fa5a4279cbce/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f68756d616e3031382f6c61726176656c2d65617274682e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/Human018/laravel-earth/issues)[![MIT License](https://camo.githubusercontent.com/548eef0fb37e0b30dfa546b172dcc9108451ca1ff95463129f67cf4bc5ab3724/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f68756d616e3031382f6c61726176656c2d65617274682e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/Human018/laravel-earth/blob/main/LICENSE) Table of Contents1. [About The Project](#about-the-project) - [Built With](#built-with) 2. [Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Installation](#installation) 3. [Usage](#usage) 4. [Contributing](#contributing) 5. [License](#license) 6. [Contact](#contact) 7. [Acknowledgements](#acknowledgements) About The Project ----------------- [](#about-the-project) A multilingual Laravel package to populate continents, countries, regions, cities, languages and currencies for planet earth. ### Built With [](#built-with) - PHP ^8.2 - [Laravel ^10](https://laravel.com) Getting Started --------------- [](#getting-started) This project is built using Laravel 8 and is not currently backwards compatible with older versions. ### Prerequisites [](#prerequisites) - PHP 8.2 - Laravel 10, 11 or 12 - Guzzle - ZipArchive - Countrylayer API Because this library uses an NPM package as one of it's data sources, you will need to allow composer to download an NPM package. To do so add the following property (or append to the already existing property) to the `repositories` array/object in your composer.json file. ``` "repositories": [ { "type": "composer", "url": "https://asset-packagist.org" } ] ``` #### API Access [](#api-access) You will require an API key with [countrylayer](https://countrylayer.com/) in order to use its services. A free key is available and all that will be required for the seed. Once you have your API key add it to your .env file. ``` COUNTRY_LAYER_API=XXX ``` ### Installation [](#installation) 1. Using composer install the package to your project. ``` composer require human018/laravel-earth ``` 2. Run database migration. ``` php artisan migrate ``` 3. This package seeds the database with various sources (listed below) so an initialisation script need to be run in order to access these third-party sources and seed your database. ``` php artisan earth:init ``` 4. (*Optional*) If you want to seed all the cities in a certain country pass in the country code. Note that this may take a long time depending on the country you're seeding. ``` php artisan earth:init --country=au ``` 5. (*Optional*) You can also seed all major cities (over 15,000 in pop.). ``` php artisan earth:init --cities=major ``` Usage ----- [](#usage) All models are located in the same namespace and can be imported into your local project. ``` use Human018\LaravelEarth\Models\Continent; use Human018\LaravelEarth\Models\Country; use Human018\LaravelEarth\Models\Region; use Human018\LaravelEarth\Models\City; use Human018\LaravelEarth\Models\Language; use Human018\LaravelEarth\Models\Currency; use Human018\LaravelEarth\Models\Timezone; use Human018\LaravelEarth\Models\TimezoneUTC; ``` A couple of helpful methods for finding the correct resource are included. This means the resource name or code can be used to quickly locate a resource. Additionally, relationships between models are connected in a standard way and can be chained like usual. ``` // eg 1. Retrieve country by code $country = Country::code('au'); echo $country->regions->count(); // Returns '8' // eg 2. You can pass in the Code in lower or upper case $country = Country::code('AU'); // Eg 3. You can also search by name $region = Region::name('New South Wales'); echo $region->country->name; // Returns 'Australia' echo $region->country->capital->name; // Returns 'Canberra' ``` Retrieving timezones are slightly more complicated. Currently timezones are connected to Countries rather than Regions or Cities. Because a country can have multiple UTC zones, and in turn those zones can belong to the same Timezone, retrieving the relationship just requires us to use the unique query modifier. ``` $country = Country::code('ca'); // Canada $country->timezones->pluck('label'); // Returns duplicates because it's unique UTC zones // belong to many of the same Timezones $country->timezones->unique()->pluck('label'); // Returns only unique timezones ``` Contributing ------------ [](#contributing) Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**. 1. Fork the Project 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) 3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the Branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request License ------- [](#license) Distributed under the MIT License. See `LICENSE` for more information. Contact ------- [](#contact) Simon Woodard - [@human018](https://twitter.com/human018) Project Link: Acknowledgements ---------------- [](#acknowledgements) - [countrylayer](https://countrylayer.com/) - [country-region-data](https://github.com/country-regions/country-region-data) - [GeoNames](http://www.geonames.org/) ### Health Score 50 — FairBetter than 95% of packages Maintenance84 Actively maintained with recent releases Popularity17 Limited adoption so far Community7 Small or concentrated contributor base Maturity76 Established project with proven stability 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 ~84 days Recently: every ~116 days Total 24 Last Release 90d ago Major Versions 0.2.0 → 1.0.02023-03-02 v0.2.1 → 1.1.22024-12-18 PHP version history (4 changes)v0.0-alphaPHP >=7.4 0.1.6PHP >=7.3 0.2.0PHP >=8.0 v1.2.0PHP >=8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/2add437b935f0c09ec7b39cbd9c887d43b5d57918336b70223d29a8ca7830c55?d=identicon)[Human018](/maintainers/Human018) --- Top Contributors [![Human018](https://avatars.githubusercontent.com/u/8413094?v=4)](https://github.com/Human018 "Human018 (32 commits)") ### Embed Badge ![Health badge](/badges/human018-laravel-earth/health.svg) ``` [![Health](https://phpackages.com/badges/human018-laravel-earth/health.svg)](https://phpackages.com/packages/human018-laravel-earth) ``` ### Alternatives [typicms/base A modular multilingual CMS built with Laravel, enabling developers to manage structured content like pages, news, events, and more. 1.6k20.4k](/packages/typicms-base)[vemcogroup/laravel-translation Translation package for Laravel to scan for localisations and up/download to poeditor 136319.2k3](/packages/vemcogroup-laravel-translation)[statamic-rad-pack/runway Eloquently manage your database models in Statamic. 135212.4k7](/packages/statamic-rad-pack-runway) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)