PHPackages usamamuneerchaudhary/country-city-state - 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. usamamuneerchaudhary/country-city-state ActiveLibrary[Utility & Helpers](/categories/utility) usamamuneerchaudhary/country-city-state ======================================= Country City State Data Provider for Laravel 12+ v3.0(10mo ago)242.7k1MITPHPPHP ^8.3|^8.4 Since Dec 27Pushed 10mo ago1 watchersCompare [ Source](https://github.com/usamamuneerchaudhary/country-city-state)[ Packagist](https://packagist.org/packages/usamamuneerchaudhary/country-city-state)[ Docs](https://github.com/usamamuneerchaudhary/country-city-state.git)[ RSS](/packages/usamamuneerchaudhary-country-city-state/feed)WikiDiscussions main Synced 3w ago READMEChangelog (10)Dependencies (3)Versions (19)Used By (0) Country, City, State Data ========================= [](#country-city-state-data) World's Country City State Data for Laravel `^12.0` with PHP `^8.3|^8.4` and phone codes support as per ISO standards. [![Latest Version on Packagist](https://camo.githubusercontent.com/a02f3a651c2633bc8215752c7158c5d59d12fec4f003c0ceb1863fa120e81cde/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7573616d616d756e6565726368617564686172792f636f756e7472792d636974792d73746174652e737667)](https://packagist.org/packages/usamamuneerchaudhary/country-city-state)[![Total Downloads](https://camo.githubusercontent.com/5fe9d3360c6e57d5b47dc9f90b681c89f0477db795102543a3d56e0faf54ed51/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7573616d616d756e6565726368617564686172792f636f756e7472792d636974792d73746174652e737667)](https://packagist.org/packages/usamamuneerchaudhary/country-city-state)[![Monthly Downloads](https://camo.githubusercontent.com/44a9eaa2b1f2db38f1c3d35eb493114826e26dcbc36ab571e506016419e3507a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f7573616d616d756e6565726368617564686172792f636f756e7472792d636974792d73746174652e737667)](https://packagist.org/packages/usamamuneerchaudhary/country-city-state)[![License](https://camo.githubusercontent.com/4ae177cc0f708b5e2e0ddcdc915d2ae8aba49622e8a066e9f65eae32e0cffbd1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7573616d616d756e6565726368617564686172792f636f756e7472792d636974792d73746174652e737667)](https://github.com/usamamuneerchaudhary/country-city-state/blob/main/LICENSE.md)[![PHP Version](https://camo.githubusercontent.com/7434b34f40c438385e3b9452844912f70bcec56e19ce4b2157d0cee1124127f4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7573616d616d756e6565726368617564686172792f636f756e7472792d636974792d73746174652e737667)](https://packagist.org/packages/usamamuneerchaudhary/country-city-state)[![Laravel Version](https://camo.githubusercontent.com/349ee4686b992bea6b3660029a1df00bce654d00cd69357d75b84197c7b2d612/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7573616d616d756e6565726368617564686172792f636f756e7472792d636974792d73746174652f696c6c756d696e6174652f737570706f72742e737667)](https://packagist.org/packages/usamamuneerchaudhary/country-city-state) ๐Ÿš€ Requirements -------------- [](#-requirements) - **PHP**: ^8.3|^8.4 - **Laravel**: ^12.0 ๐Ÿ“ฆ Installation -------------- [](#-installation) You can install the package via composer: ``` composer require usamamuneerchaudhary/country-city-state ``` ๐Ÿ”ง Setup ------- [](#-setup) ### 1. Publish Assets [](#1-publish-assets) ``` # Publish migrations, models, helpers, and seeders php artisan vendor:publish --tag=CountryCityState # Publish configuration file php artisan vendor:publish --tag=config ``` ### 2. Run Migrations [](#2-run-migrations) ``` php artisan migrate ``` ### 3. (Optional) Run Seeder [](#3-optional-run-seeder) ``` php artisan db:seed --class=UsamaMuneerChaudhary\\CountryCityState\\seeds\\CountryCityStateTableSeeder ``` ๐Ÿ’ก Usage ------- [](#-usage) ### Using the Facade [](#using-the-facade) ``` use UsamaMuneerChaudhary\CountryCityState\Facades\CountryCityState; // Get all active countries $countries = CountryCityState::getCountries(); // Get states by country ID $states = CountryCityState::getStatesByCountry(1); // Get cities by state ID $cities = CountryCityState::getCitiesByState(1); // Get phone codes by country ID $phoneCodes = CountryCityState::getPhoneCodesByCountry(1); // Find country by ISO code $country = CountryCityState::findCountryByIso('US'); ``` ### Using the Service Container [](#using-the-service-container) ``` $service = app('country-city-state'); $countries = $service->getCountries(); ``` ### Direct Model Usage [](#direct-model-usage) ``` use UsamaMuneerChaudhary\CountryCityState\Models\Country; use UsamaMuneerChaudhary\CountryCityState\Models\State; use UsamaMuneerChaudhary\CountryCityState\Models\City; // Find country by ISO code $country = Country::where('iso_code2', 'US')->first(); // Get all states for a country $states = $country->states; // Get all cities for a state $cities = $states->first()->cities; // Find state by name $state = State::where('name', 'California')->first(); // Find city by name $city = City::where('name', 'Los Angeles')->first(); ``` ### Working with Relationships [](#working-with-relationships) ``` // Country -> States -> Cities $country = Country::find(1); $states = $country->states; // HasMany relationship $state = $states->first(); $cities = $state->cities; // HasMany relationship // Reverse relationships $city = City::find(1); $state = $city->state; // BelongsTo relationship $country = $state->country; // BelongsTo relationship ``` โš™๏ธ Configuration ---------------- [](#๏ธ-configuration) The package configuration file will be published to `config/country-city-state.php`. You can customize: - **Default Status**: Set default status for new records (`active`/`inactive`) - **Table Names**: Customize database table names if needed - **Cache Settings**: Enable/disable caching and set TTL - **Seeder Behavior**: Control seeder truncation behavior ``` return [ 'default_status' => 'active', 'tables' => [ 'countries' => 'countries', 'states' => 'states', 'cities' => 'cities', 'country_phone_codes' => 'country_phone_codes', ], 'cache' => [ 'enabled' => true, 'ttl' => 3600, // 1 hour ], 'seeder' => [ 'truncate_before_seeding' => false, ], ]; ``` ๐Ÿ—„๏ธ Database Structure --------------------- [](#๏ธ-database-structure) The package creates the following tables: ### Countries Table [](#countries-table) - `id` - Primary key - `name` - Country name - `iso_code2` - 2-letter ISO code (e.g., US, GB) - `iso_code3` - 3-letter ISO code (e.g., USA, GBR) - `num_code` - Numeric ISO code - `status` - Active/Inactive status - `created_at`, `updated_at` - Timestamps - `deleted_at` - Soft delete timestamp ### States Table [](#states-table) - `id` - Primary key - `country_id` - Foreign key to countries table - `name` - State/Province name - `status` - Active/Inactive status - `created_at`, `updated_at` - Timestamps - `deleted_at` - Soft delete timestamp ### Cities Table [](#cities-table) - `id` - Primary key - `state_id` - Foreign key to states table - `name` - City name - `status` - Active/Inactive status - `created_at`, `updated_at` - Timestamps - `deleted_at` - Soft delete timestamp ### Country Phone Codes Table [](#country-phone-codes-table) - `id` - Primary key - `phone_code` - Country calling code - `intl_dialing_prefix` - International dialing prefix - `country_id` - Foreign key to countries table - `created_at`, `updated_at` - Timestamps ๐Ÿงช Testing --------- [](#-testing) ``` composer test ``` ๐Ÿ“ What's New in v3.0 -------------------- [](#-whats-new-in-v30) - โœ… **PHP 8.3+ Support** - Modern PHP features and performance - โœ… **Laravel 12+ Support** - Latest Laravel framework compatibility - โœ… **Modern Migration Syntax** - Anonymous classes and improved foreign keys - โœ… **Enhanced Service Class** - Useful methods for common operations - โœ… **Proper Type Hints** - Better IDE support and code quality - โœ… **Configuration Support** - Customizable package settings - โœ… **Improved Namespaces** - Better package organization - โœ… **PHPUnit 11** - Latest testing framework ๐Ÿ”„ Upgrading from v1.x --------------------- [](#-upgrading-from-v1x) If you're upgrading from version 1.x, please note: 1. **PHP 8.3+ Required** - Update your PHP version 2. **Laravel 12+ Required** - Update your Laravel version 3. **Model Namespaces Changed** - Update any direct model references 4. **Migration Updates** - May need to rollback and re-run migrations See [UPGRADE\_GUIDE.md](UPGRADE_GUIDE.md) for detailed upgrade instructions. ๐Ÿค Contributing -------------- [](#-contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ### Security [](#security) If you discover any security related issues, please email instead of using the issue tracker. ๐Ÿ“„ License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ๐Ÿ‘จโ€๐Ÿ’ป Credits ----------- [](#โ€-credits) - [Usama Muneer](https://github.com/usamamuneerchaudhary) - [All Contributors](../../contributors) --- **Note**: This package is now fully compatible with PHP 8.3+ and Laravel 12+. For older versions, please use v1.x of the package. ### Health Score 47 โ€” FairBetter than 93% of packages Maintenance54 Moderate activity, may be stable Popularity28 Limited adoption so far Community8 Small or concentrated contributor base Maturity80 Battle-tested with a long release history 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 ~100 days Recently: every ~423 days Total 18 Last Release 315d ago Major Versions v1.7 โ†’ v2.02020-12-27 v2.8 โ†’ v3.02025-08-16 PHP version history (2 changes)v1.0PHP >=7.3 v3.0PHP ^8.3|^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/adb088072d2e9f335a0c37e9e5481d8d3c582ccc4b4ca721850b1e32b3a480e8?d=identicon)[usamamuneerchaudhary](/maintainers/usamamuneerchaudhary) --- Top Contributors [![usamamuneerchaudhary](https://avatars.githubusercontent.com/u/24513380?v=4)](https://github.com/usamamuneerchaudhary "usamamuneerchaudhary (39 commits)") --- Tags laravelcountriesstatecountrycitystatescitiesusamamuneerchaudharycountry-state-citycountry-city-state ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/usamamuneerchaudhary-country-city-state/health.svg) ``` [![Health](https://phpackages.com/badges/usamamuneerchaudhary-country-city-state/health.svg)](https://phpackages.com/packages/usamamuneerchaudhary-country-city-state) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.1M337](/packages/psalm-plugin-laravel)[dipeshsukhia/laravel-country-state-city-data Country State City Data Provider 8231.3k1](/packages/dipeshsukhia-laravel-country-state-city-data)[dougsisk/laravel-country-state Country & state helper for Laravel. 1681.8M](/packages/dougsisk-laravel-country-state)[wearepixel/laravel-cart A cart implementation for Laravel 1355.6k](/packages/wearepixel-laravel-cart) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)