README

Laravel integration for oc/world-countries — service provider, facade, validation rules, collection helpers, and Artisan commands.

Maintained by OctaCrafts.

This package is a thin Laravel wrapper. It does not contain country or region data. All datasets and business logic come from the core oc/world-countries package.

About OctaCrafts

OctaCrafts is a global IT systems and software engineering company that builds scalable digital ecosystems for businesses worldwide.

Beyond client projects, OctaCrafts maintains open-source PHP libraries under the oc/* package family on GitHub @octacrafts. Each ecosystem follows a core-plus-wrapper pattern: framework-agnostic cores for plain PHP and any PSR-compliant app, with dedicated integrations for popular frameworks.

For architecture and data flow, see docs/FLOW.md.

Requirements

• PHP 8.2+
• Laravel 11 or 12

Installation

composer require oc/world-countries-laravel

The package is auto-discovered. No manual service provider or alias registration is required.

Quick Start

use WorldCountries;

$country = WorldCountries::country('PK');
$regions = WorldCountries::regions('PK');
$names   = WorldCountries::countriesCollection()->pluck('name');

Configuration

Configuration is optional. Defaults are merged automatically — you do not need to publish anything to get started.

Publish only when you want to customize settings in your app's config/ directory:

php artisan vendor:publish --tag=world-countries-config

Published config/world-countries.php:

return [
    'cache' => false,
    'cache_ttl' => 86400,
];

Caching notes:

• cache is off by default. The core WorldCountries singleton already holds data in memory for the lifetime of each request.
• Set cache to true only when you want cross-request caching and your Laravel cache store is configured (file, Redis, etc.).
• If using the database cache driver, run php artisan cache:table and migrate before enabling cache.

Facade

The WorldCountries facade is registered automatically:

use WorldCountries;

$country = WorldCountries::country('PK');
$regions = WorldCountries::regions('PK');

if (WorldCountries::hasCountry('PK')) {
    // ...
}

// Search, options, and all core methods are available
$results = WorldCountries::searchCountries('pak');
$options = WorldCountries::countryOptions();

Dependency Injection

Inject the core class directly — the service provider registers it as a singleton:

use Oc\WorldCountries\WorldCountries;

class UserController
{
    public function __construct(
        private readonly WorldCountries $worldCountries,
    ) {}

    public function index(): array
    {
        return $this->worldCountries->countries();
    }
}

Use the facade (via WorldCountriesBridge) for Laravel collection helpers. Use DI with Oc\WorldCountries\WorldCountries for the full core API in controllers, services, and jobs.

Validation

Country code

use Oc\LaravelWorldCountries\Validation\CountryCodeRule;

$request->validate([
    'country' => ['required', new CountryCodeRule()],
]);

Validates against WorldCountries::hasCountry(). Accepts ISO 3166-1 alpha-2 or alpha-3 codes.

Failure message: The selected country code is invalid.

Region code

use Oc\LaravelWorldCountries\Validation\RegionCodeRule;

$request->validate([
    'country' => ['required', new CountryCodeRule()],
    'region'  => ['required', new RegionCodeRule($request->country)],
]);

Validates against WorldCountries::hasRegion().

Failure messages:

• A country code is required to validate the region code.
• The selected region code is invalid for the given country.

Collections

Laravel Collection helpers are available via the facade or global functions:

use WorldCountries;

// Via facade
$names   = WorldCountries::countriesCollection()->pluck('name');
$regions = WorldCountries::regionsCollection('PK')->pluck('name');

// Via global helpers
$countries = collectCountries();
$regions   = collectRegions('PK');

Collections contain typed Country and Region DTOs from the core package — not raw arrays.

Artisan Commands

# Package statistics (country count, region count, core version)
php artisan world-countries:info

# Country details (name, alpha-2, alpha-3, numeric)
php artisan world-countries:country PK

# All regions for a country (table: code, name, type)
php artisan world-countries:regions PK

Manual Testing (package development)

Inside this repository, use Orchestra Testbench:

# Artisan commands
vendor/bin/testbench world-countries:info
vendor/bin/testbench world-countries:country PK
vendor/bin/testbench world-countries:regions PK

# Interactive REPL
vendor/bin/testbench tinker

In Tinker:

WorldCountries::country('PK');
WorldCountries::countriesCollection()->pluck('name')->take(5);
collectRegions('PK')->pluck('name');

Package Structure

src/
├── LaravelWorldCountriesServiceProvider.php
├── Facades/WorldCountries.php
├── Validation/
│   ├── CountryCodeRule.php
│   └── RegionCodeRule.php
├── Commands/
│   ├── WorldCountriesInfoCommand.php
│   ├── WorldCountriesCountryCommand.php
│   └── WorldCountriesRegionsCommand.php
└── Support/
    ├── WorldCountriesBridge.php
    └── helpers.php
config/
└── world-countries.php

Design Principles

• Never duplicate data — all countries and regions come from oc/world-countries
• Never duplicate logic — validation and commands delegate to the core API
• Thin wrapper — Laravel-native DX only (provider, facade, rules, collections, commands)
• Auto-discovery — install and use, no manual registration

Testing

composer test

Uses Orchestra Testbench with PHPUnit.

Related Packages

• oc/world-countries — framework-agnostic core (Packagist: oc/world-countries)

License

MIT License. See LICENSE for details.

OctaCrafts — Scalable IT Systems & AI-Driven Digital Ecosystems

octacrafts.com · info@octacrafts.com · +1 (855) 424 4706