PHPackages ritechoice23/laravel-worldable - 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. [Database & ORM](/categories/database) 4. / 5. ritechoice23/laravel-worldable ActiveLibrary[Database & ORM](/categories/database) ritechoice23/laravel-worldable ============================== Make your Laravel application location-aware in seconds. Worldable is a package that provides a simple and efficient way to add Country, State, City, Currency, Language, and Timezone relationships to your laravel application. 1.0.0(4mo ago)161[3 PRs](https://github.com/ritechoice23/laravel-worldable/pulls)MITPHPPHP ^8.3CI passing Since Dec 15Pushed 1mo agoCompare [ Source](https://github.com/ritechoice23/laravel-worldable)[ Packagist](https://packagist.org/packages/ritechoice23/laravel-worldable)[ Docs](https://github.com/ritechoice23/laravel-worldable)[ GitHub Sponsors](https://github.com/ritechoice23)[ RSS](/packages/ritechoice23-laravel-worldable/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (1)Dependencies (12)Versions (4)Used By (0) [![Laravel Worldable Thumbnail](assets/laravel_worldable_thumbnail.png)](assets/laravel_worldable_thumbnail.png) Laravel Worldable ================= [](#laravel-worldable) [![Latest Version on Packagist](https://camo.githubusercontent.com/5d536073cc81c85ca62890d13464c79fbb06d1dedd05ef66b51474ec68bfb337/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7269746563686f69636532332f6c61726176656c2d776f726c6461626c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ritechoice23/laravel-worldable)[![GitHub Tests Action Status](https://camo.githubusercontent.com/6623955734abd367bceb08bdda685bd78cd240492f21bcb0a61b356db3ad2359/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7269746563686f69636532332f6c61726176656c2d776f726c6461626c652f72756e2d74657374732e796d6c3f6272616e63683d6d6173746572266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/ritechoice23/laravel-worldable/actions?query=workflow%3Arun-tests+branch%3Amaster)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/341fd927deeb07da6e05db2e47c958832efe63df4305f44238ae1bd5b0adb8c3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7269746563686f69636532332f6c61726176656c2d776f726c6461626c652f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d6173746572266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/ritechoice23/laravel-worldable/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amaster)[![Total Downloads](https://camo.githubusercontent.com/bd1981fa6828a17645e7337111c3bdb422247a8937cc78bd2729d2e656afedbf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7269746563686f69636532332f6c61726176656c2d776f726c6461626c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ritechoice23/laravel-worldable)[![Buy Me A Coffee](https://camo.githubusercontent.com/e78c1a35f8d1b89d3cf0ef6638e09772cdd62d1eadf18fb59ec6914ffc2890d8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4275792532304d6525323041253230436f666665652d737570706f72742d79656c6c6f772e7376673f7374796c653d666c61742d737175617265)](https://buymeacoffee.com/ritechoice23) **Make your Laravel application location-aware in seconds.** Worldable is a package that provides a simple and efficient way to add Country, State, City, Currency, Language, and Timezone relationships to your laravel application. Quick Start ----------- [](#quick-start) ``` composer require ritechoice23/laravel-worldable ``` **That's it!** You now have access to 8 world entities: Continents, Subregions, Countries, States, Cities, Currencies, Languages, and Timezones. Installation Options -------------------- [](#installation-options) ``` # Install everything (all world data + polymorphic support) php artisan world:install --all # Install specific components only php artisan world:install --countries --currencies # Add polymorphic support later php artisan world:install --worldables # Uninstall any component you don't need again php artisan world:uninstall ``` ### Optional: Publish Configuration [](#optional-publish-configuration) If you need to customize table names, publish the config file: ``` php artisan vendor:publish --tag=worldable-config ``` This creates `config/worldable.php` where you can customize table names to match your naming convention. Usage Modes ----------- [](#usage-modes) ### 1. Direct Model Usage (Traditional Approach) [](#1-direct-model-usage-traditional-approach) Use world data models directly with standard Eloquent relationships: ``` use Ritechoice23\Worldable\Models\Country; use Ritechoice23\Worldable\Models\Currency; // Add foreign keys to your model Schema::table('users', function (Blueprint $table) { $table->foreignId('country_id')->nullable()->constrained('world_countries'); $table->foreignId('currency_id')->nullable()->constrained('world_currencies'); }); // Use standard relationships class User extends Model { public function country() { return $this->belongsTo(Country::class); } } $user->country_id = Country::where('name', 'Nigeria')->first()->id; $user->save(); ``` ### 2. Polymorphic Relationships (Zero-Migration Approach) [](#2-polymorphic-relationships-zero-migration-approach) **Too lazy to add foreign keys?** We got you covered! Use the `Worldable` trait for instant location awareness without touching your database schema: ``` use Ritechoice23\Worldable\Traits\Worldable; class User extends Model { use Worldable; // That's it! } // Attach world data on the fly $user->attachCountry('Nigeria'); $user->attachCity('Lagos', 'billing'); $user->attachCurrency('NGN'); $user->formatMoney(5000); // "₦5,000.00" // Query naturally User::whereFrom('Nigeria')->get(); User::wherePricedIn('USD')->get(); ``` **Why use polymorphic relationships?** - **Zero migrations** - No need to modify your existing tables - **Multiple contexts** - Separate billing/shipping, citizenship/residence - **Flexible** - Attach multiple countries, cities, or currencies to one model - **Metadata support** - Store extra data on relationships - **Clean codebase** - No foreign key clutter in your models Key Features ------------ [](#key-features) FeatureDescription**8 World Entities**Continents, Subregions, Countries, States, Cities, Currencies, Languages, Timezones**Modular Install**Install only what you need, add more later**Two Usage Modes**Traditional foreign keys OR polymorphic relationships**Context Groups**Separate billing/shipping, citizenship/residence**Smart Resolution**Accepts IDs, names, ISO codes automatically**Query Scopes**`whereFrom()`, `whereLocatedInCity()`, `wherePricedIn()`, `whereSpeaks()`**Money Formatting**`$product->formatMoney(100)` → "$100.00" with locale support**Bulk Operations**`$user->attachCountries(['NG', 'GH', 'KE'])`**Custom Metadata**Store extra data: `$user->attachCountry('NG', 'billing', ['tax_id' => '...'])`**Health Checks**`php artisan world:health --detailed` monitors data integrityReal-World Example ------------------ [](#real-world-example) ``` class Order extends Model { use Worldable; } // E-commerce checkout with multiple contexts $order ->attachCountry('United States', 'billing') ->attachState('California', 'billing') ->attachCountry('Canada', 'shipping') ->attachCity('Toronto', 'shipping') ->attachCurrency('USD', 'display') ->attachCurrency('CAD', 'settlement'); // Analytics $usOrders = Order::whereFrom('United States')->count(); $canadaShipping = Order::whereHas('countries', fn($q) => $q->where('name', 'Canada')->wherePivot('group', 'shipping') )->count(); // Conditional logic if ($order->hasCountry('United States', 'billing')) { // Apply US tax rules } ``` Documentation ------------- [](#documentation) **[Full Documentation](docs/)** - Deep dive into all features - [Installation](docs/installation.md) - Advanced installation options - [Commands](docs/commands.md) - Complete commands reference - [Basic Usage](docs/basic-usage.md) - Common operations - [API Reference](docs/api-reference.md) - Complete API documentation - [Countries](docs/countries.md), [States](docs/states.md), [Cities](docs/cities.md) - Location data - [Currencies](docs/currencies.md), [Languages](docs/languages.md), [Timezones](docs/timezones.md) - Localization - [Groups](docs/groups.md) - Context-aware relationships - [Meta Data](docs/meta-data.md) - Custom metadata storage - [Validation Rules](docs/validation-rules.md) - Input validation - [Scopes](docs/scopes.md) - Query scopes reference Testing ------- [](#testing) ``` composer test ``` Credits ------- [](#credits) - [Daramola Babatunde Ebenezer](https://github.com/ritechoice23) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). See [License File](LICENSE.md). ### Health Score 40 — FairBetter than 88% of packages Maintenance84 Actively maintained with recent releases Popularity7 Limited adoption so far Community10 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 66.7% 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 Unknown Total 1 Last Release 147d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/cc2c3a32449f76aa8dfca355106fce6c5ade0effe7d22fa265493051e890aa40?d=identicon)[ritechoice23](/maintainers/ritechoice23) --- Top Contributors [![ritechoice23](https://avatars.githubusercontent.com/u/62488893?v=4)](https://github.com/ritechoice23 "ritechoice23 (4 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags laravel-frameworklaravel-packagelaravel-worldableworld-datalaravellocalizationinternationalizationi18nl10nlanguagesmodeleloquentcountriestraitlocationgeographygeostatescurrenciesRelationshipstimezonescitiespolymorphiccontinentsritechoice23world-dataworldable ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/ritechoice23-laravel-worldable/health.svg) ``` [![Health](https://phpackages.com/badges/ritechoice23-laravel-worldable/health.svg)](https://phpackages.com/packages/ritechoice23-laravel-worldable) ``` ### Alternatives [nnjeim/world Laravel countries, states, cities, currencies, languages and IP geolocation 970361.2k3](/packages/nnjeim-world)[dyrynda/laravel-model-uuid This package allows you to easily work with UUIDs in your Laravel models. 4802.8M8](/packages/dyrynda-laravel-model-uuid)[io238/laravel-iso-countries Ready-to-use Laravel models and relations for country (ISO 3166), language (ISO 639-1), and currency (ISO 4217) information with multi-language support. 5462.3k](/packages/io238-laravel-iso-countries)[lacodix/laravel-model-filter A Laravel package to filter, search and sort models with ease while fetching from database. 17649.9k](/packages/lacodix-laravel-model-filter)[altwaireb/laravel-world Laravel World, Countries States Cities DB Migration & Seeder 989.4k](/packages/altwaireb-laravel-world)[richan-fongdasen/laravel-i18n Simple route and eloquent localization / translation in Laravel 1296.6k](/packages/richan-fongdasen-laravel-i18n) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)