README

Introduction

Laravel Sepomex is a package that provides Mexican postal code (SEPOMEX) lookup functionality for Laravel applications. It imports postal code data from the official "Correos de México" catalog and provides an API to query settlements by postal code or list all states.

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12

Installation

Install the package via Composer:

composer require wafto/laravel-sepomex

Setup

1. Publish Configuration

Publish the sepomex.php configuration file:

php artisan vendor:publish --provider="Wafto\Sepomex\SepomexServiceProvider"

This will create a configuration file at config/sepomex.php where you can customize the table_name and source_file options.

2. Download Source File

Download the official SEPOMEX catalog from Correos de México and save it to your storage directory as cpdescarga.txt.

The file path should match the source_file setting in your configuration.

3. Run Migrations

Run the database migrations to create the required table:

php artisan migrate

4. Import Data

Import the postal code data using the artisan command:

php artisan sepomex:import --chunk=50

The --chunk option controls the batch size for database inserts. This process may take several minutes depending on your system.

Usage

Using Dependency Injection (Recommended)

Inject the SepomexContract interface into your controllers or services:

use Wafto\Sepomex\Contracts\SepomexContract;

class SepomexController extends Controller
{
    public function postal(SepomexContract $sepomex, string $postal)
    {
        return $sepomex->getByPostal($postal);
    }

    public function states(SepomexContract $sepomex)
    {
        return $sepomex->getStates();
    }
}

Using the Facade

Alternatively, register the Sepomex facade in config/app.php:

'aliases' => [
    // ...
    'Sepomex' => Wafto\Sepomex\Facades\Sepomex::class,
]

Then use it anywhere in your application:

use Sepomex;

class SepomexController extends Controller
{
    public function postal(string $postal)
    {
        return Sepomex::getByPostal($postal);
    }

    public function states()
    {
        return Sepomex::getStates();
    }
}

Using the Container

You can also resolve the contract from the container:

$sepomex = app(\Wafto\Sepomex\Contracts\SepomexContract::class);
$settlements = $sepomex->getByPostal('06600');

API Methods

Important Notes

The database is distributed by Correos de México with the following clause:

El Catálogo Nacional de Códigos Postales, es elaborado por Correos de México y se proporciona en forma gratuita para uso particular, no estando permitida su comercialización, total o parcial, ni su distribución a terceros bajo ningún concepto.

The database has also been released under the LIBRE USO MX license.

Source

"Catálogo Nacional de Códigos Postales" publicado por Correos de México. Disponible en https://www.correosdemexico.gob.mx/SSLServicios/ConsultaCP/CodigoPostal_Exportar.aspx

License

Laravel Sepomex is open-sourced software licensed under the MIT license.