PHPackages                             oc/world-countries-laravel - 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. [Validation & Sanitization](/categories/validation)
4. /
5. oc/world-countries-laravel

ActiveLibrary[Validation & Sanitization](/categories/validation)

oc/world-countries-laravel
==========================

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

v1.0.0(1mo ago)03MITPHPPHP ^8.2

Since Jun 12Pushed 1mo agoCompare

[ Source](https://github.com/octacrafts/oc-world-countries-laravel)[ Packagist](https://packagist.org/packages/oc/world-countries-laravel)[ Docs](https://octacrafts.com)[ RSS](/packages/oc-world-countries-laravel/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

oc/world-countries-laravel
==========================

[](#ocworld-countries-laravel)

[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)

Laravel integration for [`oc/world-countries`](https://packagist.org/packages/oc/world-countries) — service provider, facade, validation rules, collection helpers, and Artisan commands.

Maintained by **[OctaCrafts](https://octacrafts.com)**.

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`](https://github.com/octacrafts/oc-world-countries) package.

About OctaCrafts
----------------

[](#about-octacrafts)

[OctaCrafts](https://octacrafts.com) 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](https://github.com/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.

PackageRole[`oc/world-countries`](https://github.com/octacrafts/oc-world-countries)Framework-agnostic core — countries, regions, search, DTOs**`oc/world-countries-laravel`** (this package)Laravel 11+ wrapper — facade, DI, validation, collections, commandsFor architecture and data flow, see [docs/FLOW.md](docs/FLOW.md).

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11 or 12

Installation
------------

[](#installation)

```
composer require oc/world-countries-laravel
```

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

Quick Start
-----------

[](#quick-start)

```
use WorldCountries;

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

Configuration
-------------

[](#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,
];
```

KeyDefaultDescription`cache``false`Cache collection helper results via Laravel's cache store`cache_ttl``86400`TTL in seconds when `cache` is enabled**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
------

[](#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
--------------------

[](#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
----------

[](#validation)

### Country code

[](#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

[](#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
-----------

[](#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
----------------

[](#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)
------------------------------------

[](#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
-----------------

[](#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
-----------------

[](#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
-------

[](#testing)

```
composer test
```

Uses [Orchestra Testbench](https://packages.tools/testbench) with PHPUnit.

Related Packages
----------------

[](#related-packages)

- [`oc/world-countries`](https://github.com/octacrafts/oc-world-countries) — framework-agnostic core (Packagist: `oc/world-countries`)

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

---

**[OctaCrafts](https://octacrafts.com)** — Scalable IT Systems & AI-Driven Digital Ecosystems

[octacrafts.com](https://octacrafts.com) ·  · +1 (855) 424 4706

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance90

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 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

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/278240197?v=4)[octacrafts](/maintainers/octacrafts)[@octacrafts](https://github.com/octacrafts)

---

Top Contributors

[![WasifBoostzone](https://avatars.githubusercontent.com/u/275062263?v=4)](https://github.com/WasifBoostzone "WasifBoostzone (1 commits)")

---

Tags

laravelvalidationcountriesISO 3166regionsworld countries

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/oc-world-countries-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/oc-world-countries-laravel/health.svg)](https://phpackages.com/packages/oc-world-countries-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M348](/packages/psalm-plugin-laravel)[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k95.4M322](/packages/laravel-horizon)[illuminate/database

The Illuminate Database package.

2.8k54.9M12.3k](/packages/illuminate-database)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M250](/packages/laravel-ai)[moonshine/moonshine

Laravel administration panel

1.3k253.1k86](/packages/moonshine-moonshine)[illuminate/validation

The Illuminate Validation package.

18838.2M1.8k](/packages/illuminate-validation)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)