README

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.

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

# 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

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

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)

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

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

Full Documentation - Deep dive into all features

• Installation - Advanced installation options
• Commands - Complete commands reference
• Basic Usage - Common operations
• API Reference - Complete API documentation
• Countries, States, Cities - Location data
• Currencies, Languages, Timezones - Localization
• Groups - Context-aware relationships
• Meta Data - Custom metadata storage
• Validation Rules - Input validation
• Scopes - Query scopes reference

Testing

composer test

Credits

• Daramola Babatunde Ebenezer
• All Contributors

License

The MIT License (MIT). See License File.