Laravel Cep

https://github.com/jeffersongoncalves/laravel-cep
Admin
Laravel Cep is a Laravel package for querying Brazilian postal codes (CEP) with automatic fallback...
Tokens:22,169
Snippets:242
Trust Score:9.8
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Cep::findByCepInDatabase usage example

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Example showing how to perform a local-only database lookup for a CEP.

```php
use JeffersonGoncalves\Cep\Models\Cep;

// No HTTP requests are issued by this method.
$localOnly = Cep::findByCepInDatabase('01310-100');

if (empty($localOnly['cep'])) {
    // Not cached locally — decide whether to call findByCep().
}
```

--------------------------------

### Manual Testing Examples

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Examples for testing valid and invalid CEP lookups, as well as CEP validation checks.

```php
// Test valid CEP
$result = Cep::findByCep('01310-100');
var_dump($result);

// Test invalid CEP
$result = Cep::findByCep('00000-000');
var_dump($result); // Should return empty array

// Test CEP validation
$isValid = Cep::checkCep('01310-100'); // true
$isInvalid = Cep::checkCep('invalid'); // false
```

--------------------------------

### Cep::checkCep usage examples

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Examples demonstrating how to use checkCep with valid, empty, null, and invalid format inputs.

```php
use JeffersonGoncalves\Cep\Models\Cep;

if (Cep::checkCep('01310-100')) {
    // CEP exists
}

var_dump(Cep::checkCep(''));       // bool(false)
var_dump(Cep::checkCep(null));     // bool(false)
var_dump(Cep::checkCep('123'));    // bool(false)  — invalid format
var_dump(Cep::checkCep('invalid'));// bool(false)  — no HTTP request is made
```

--------------------------------

### Basic CEP lookup example

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Demonstrates a standard lookup and how to handle the returned address array.

```php
use JeffersonGoncalves\\\Cep\\\Models\\\Cep;

$address = Cep::findByCep('01310-100');

if (! empty($address['cep'])) {
    echo $address['state'].' / '.$address['city']; // e.g. "SP / São Paulo"
} else {
    echo 'CEP not found';
}
```

--------------------------------

### Set Configuration at Runtime

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/configuration.md

Example of overriding configuration values dynamically before executing a lookup.

```php
config()->set('cep.timeout', 10);
config()->set('cep.verify_ssl', false);
config()->set('cep.cache_ttl', 86400); // re-fetch after one day

$result = Cep::findByCep('01310-100');
```

--------------------------------

### Install laravel-cep via Composer

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Run this command to install the package in your Laravel project.

```bash
composer require jeffersongoncalves/laravel-cep
```

--------------------------------

### Cep::sanitize usage examples

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Examples demonstrating how Cep::sanitize handles various input formats, including formatted strings, short strings, and invalid inputs.

```php
use JeffersonGoncalves\Cep\Models\Cep;

Cep::sanitize('01.310-100'); // '01310100'
Cep::sanitize('1310100');    // '01310100'
Cep::sanitize('');           // null
Cep::sanitize(null);         // null
Cep::sanitize('abcd');       // null - not numeric
Cep::sanitize('123');        // null - padded to 00000123, fails regex
```

--------------------------------

### Custom HTTP Client Configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Example of overriding the default HTTP timeout for requests.

```php
use Illuminate\Support\Facades\Http;

// Example: Custom timeout
Http::timeout(10)->get('https://brasilapi.com.br/api/cep/v1/01310100');
```

--------------------------------

### Input normalization examples for Cep::findByCep

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Shows various input formats that are automatically normalized by the method, including handling of special characters and padding.

```php
Cep::findByCep('01310-100');
Cep::findByCep('01.310.100');
Cep::findByCep('01310100');
Cep::findByCep('1310100');      // left-padded to 01310100
Cep::findByCep('01310/100');
Cep::findByCep('01310(100)');
Cep::findByCep('01310 100');
```

--------------------------------

### API Route Example

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Define a route in routes/api.php to expose CEP lookup functionality via an API endpoint.

```php
// routes/api.php
Route::get('/cep/{cep}', function ($cep) {
    $result = Cep::findByCep($cep);

    return response()->json($result);
});
```

--------------------------------

### Cep::isStale usage example

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Example showing how to check if a retrieved Cep record is stale based on the configured cache TTL.

```php
use JeffersonGoncalves\Cep\Models\Cep;

$record = Cep::find('01310100');
if ($record !== null && $record->isStale()) {
   // record is older than cep.cache_ttl seconds
}
```

--------------------------------

### Basic CepService Usage

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

Example of calling findByCep with a valid CEP string to retrieve address data.

```php
use JeffersonGoncalves\Cep\Services\CepService;

$result = CepService::findByCep('01310100');

// ['cep' => '01310100', 'state' => 'SP', 'city' => 'São Paulo', ...]
```

--------------------------------

### Input sanitization examples

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

The findByCep method handles various input formats by sanitizing and padding them to 8 digits.

```php
// All these are equivalent:
Cep::findByCep('01001000');
Cep::findByCep('01001-000');
Cep::findByCep('01.001-000');
Cep::findByCep('1001000');  // Padded to 01001000
```

--------------------------------

### Laravel Controller Integration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Example of using the package within a Laravel controller, including request validation and JSON response handling.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use JeffersonGoncalves\Cep\Models\Cep;

class AddressController extends Controller
{
    public function getCep(Request $request)
    {
        $request->validate([
            'cep' => 'required|string|min:8|max:9'
        ]);

        $cepData = Cep::findByCep($request->cep);

        if (empty($cepData['cep'])) {
            return response()->json([
                'error' => 'CEP not found'
            ], 404);
        }

        return response()->json($cepData);
    }
}
```

--------------------------------

### GET https://cep.awesomeapi.com.br/json/{cep}

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/endpoints.md

Retrieves address information from the AwesomeAPI service using a specific CEP.

```APIDOC
## GET /json/{cep}

### Description
Retrieves address details including state, city, neighborhood, and street for a given 8-digit CEP.

### Method
GET

### Endpoint
https://cep.awesomeapi.com.br/json/{cep}

### Parameters
#### Path Parameters
- **cep** (string) - Required - 8 digits (normalized)

### Response
#### Success Response (200)
- **state** (string) - Mapped from 'state'
- **city** (string) - Mapped from 'city'
- **neighborhood** (string) - Mapped from 'district'
- **street** (string) - Mapped from 'address'
```

--------------------------------

### Laravel Validation Rule Integration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepsupport.md

Example of wiring the package into Laravel validation using a custom rule.

```php
use Illuminate\Support\Facades\Validator;
use JeffersonGoncalves\Cep\Models\Cep;

$validator = Validator::make($request->all(), [
    'cep' => [
        'required',
        'string',
        function ($attribute, $value, $fail) {
            if (! Cep::checkCep($value)) {
                $fail('The CEP is invalid or not found.');
            }
        },
    ],
]);
```

--------------------------------

### GET https://brasilapi.com.br/api/cep/v1/{cep}

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/endpoints.md

Fetches address information from the BrasilAPI service. This is the first provider in the lookup chain.

```APIDOC
## GET /api/cep/v1/{cep}

### Description
Retrieves address details for a given 8-digit CEP from the BrasilAPI service.

### Method
GET

### Endpoint
https://brasilapi.com.br/api/cep/v1/{cep}

### Parameters
#### Path Parameters
- **cep** (string) - Required - The 8-digit sanitized CEP code.

### Response
#### Success Response (200)
- **cep** (string) - The sanitized input CEP.
- **state** (string) - The state abbreviation.
- **city** (string) - The city name.
- **neighborhood** (string) - The neighborhood name (optional).
- **street** (string) - The street name (optional).
```

--------------------------------

### Update or create a CEP record

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Example usage of the updateByCep method to seed or update the cache with CEP information.

```php
use JeffersonGoncalves\Cep\Models\Cep;

Cep::updateByCep('01310100', 'SP', 'São Paulo', 'Bela Vista', 'Avenida Paulista');
```

--------------------------------

### GET https://viacep.com.br/ws/{cep}/json/

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/endpoints.md

Retrieves address information from the ViaCEP service using a specific CEP.

```APIDOC
## GET /ws/{cep}/json/

### Description
Retrieves address details including state, city, neighborhood, and street for a given 8-digit CEP.

### Method
GET

### Endpoint
https://viacep.com.br/ws/{cep}/json/

### Parameters
#### Path Parameters
- **cep** (string) - Required - 8 digits (normalized)

### Response
#### Success Response (200)
- **state** (string) - Mapped from 'uf'
- **city** (string) - Mapped from 'localidade'
- **neighborhood** (string) - Mapped from 'bairro'
- **street** (string) - Mapped from 'logradouro'
```

--------------------------------

### HTTP GET Request Implementation

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/endpoints.md

The core logic used by the package to perform outbound requests via Laravel's Http facade, including timeout and HTTP options.

```php
$request = Http::timeout(self::timeout())
    ->withOptions(self::httpOptions())
    ->get(($provider['url'])($cep))
    ->json();
```

--------------------------------

### Retrieve empty result structure

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Use CepSupport to get the standard empty array structure when a CEP is not found.

```php
use JeffersonGoncalves\Cep\Support\CepSupport;

$empty = CepSupport::getResult();
// ['cep' => '', 'state' => '', 'city' => '', 'neighborhood' => '', 'street' => '']
```

--------------------------------

### CEP Data Flow Logic

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/repository-reference.md

Visual representation of the lookup process starting from input sanitization through database checks and external provider fallback.

```text
Cep::findByCep($input)
  └─ Cep::sanitize()                → ?string  (null short-circuits with empty result)
       └─ DB lookup by PK 'cep'     → record?  (isStale() false → return toArray())
            └─ CepService::findByCep() → GET BrasilAPI → GET ViaCEP → GET AwesomeAPI
                 ├─ success → Cep::updateByCep() → return ['cep' => $cep] + $address
                 └─ all fail → CepSupport::getResult()
```

--------------------------------

### Publish and Run Migrations

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Publish the package migration files and execute them to set up the database table for storing queried CEP data.

```bash
php artisan vendor:publish --tag=cep-migrations
php artisan migrate
```

--------------------------------

### Run package migrations

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Execute the migration to create the necessary 'cep' table in your database.

```bash
php artisan migrate
```

--------------------------------

### Publish Configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/configuration.md

Command to publish the package configuration file to your application.

```bash
php artisan vendor:publish --tag=config
```

--------------------------------

### Download cacert.pem via CLI

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Downloads the latest CA certificate bundle from the official cURL website.

```bash
# Download the latest cacert.pem file
curl -o cacert.pem https://curl.se/ca/cacert.pem
```

--------------------------------

### Basic Usage of Cep Model

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Demonstrates how to retrieve address information and check for the existence of a CEP using the Cep model.

```php
use JeffersonGoncalves\Cep\Models\Cep;

// Find CEP information
$cepData = Cep::findByCep('01310-100');
// Returns:
// [
//     'cep' => '01310100',
//     'state' => 'SP',
//     'city' => 'São Paulo',
//     'neighborhood' => 'Bela Vista',
//     'street' => 'Avenida Paulista'
// ]

// Check if CEP exists
$exists = Cep::checkCep('01310-100'); // Returns true/false
```

--------------------------------

### Run Project Commands

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Common CLI commands for running tests, checking coverage, static analysis, and code formatting.

```bash
# Run all tests
vendor/bin/pest

# Run with coverage
vendor/bin/pest --coverage

# Static analysis
vendor/bin/phpstan analyse

# Code formatting
vendor/bin/pint
```

--------------------------------

### Run tests with Composer

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Execute the project's test suite using the Composer package manager.

```bash
composer test
```

--------------------------------

### Indexing Recommendations for Performance

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

SQL commands to create additional indexes on state and city columns for improved reporting performance.

```sql
-- Primary key already provides optimal lookup performance
-- Additional indexes for reporting (optional):
CREATE INDEX idx_cep_state ON cep(state);
CREATE INDEX idx_cep_city ON cep(city);
```

--------------------------------

### Configuration File Structure

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/configuration.md

The default content of the config/cep.php file.

```php
<?php

// config for JeffersonGoncalves/Cep
return [
    /*
    |--------------------------------------------------------------------------
    | HTTP Timeout
    |--------------------------------------------------------------------------
    |
    | The maximum number of seconds to wait for each provider HTTP request
    | before giving up and trying the next provider.
    |
    */
    'timeout' => 5,

    /*
    |--------------------------------------------------------------------------
    | SSL Verification
    |--------------------------------------------------------------------------
    |
    | Whether the TLS certificate of each provider should be verified. This
    | should always remain true in production. Guzzle ships with a CA bundle
    | (composer/ca-bundle), so disabling this is almost never required.
    |
    */
    'verify_ssl' => true,

    /*
    |--------------------------------------------------------------------------
    | Database Cache TTL
    |--------------------------------------------------------------------------
    |
    | The number of seconds a CEP stored in the database is considered fresh.
    | When the stored record is older than this value it will be fetched again
    | from the providers. Use null to cache the records forever.
    |
    */
    'cache_ttl' => null,
];
```

--------------------------------

### Import CepServiceProvider

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepserviceprovider.md

The namespace root import path for the service provider.

```php
use JeffersonGoncalves\Cep\CepServiceProvider;
```

--------------------------------

### CepService::httpOptions() configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

Returns options for Http::withOptions(), including the verify key controlled by cep.verify_ssl. Setting verify to false disables TLS certificate verification, which is discouraged for production.

```php
/**
 * @return array<string, mixed>
 */
protected static function httpOptions(): array
{
    return [
        'verify' => (bool) config('cep.verify_ssl', true),
    ];
}
```

--------------------------------

### Configure PHP for SSL

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Updates the php.ini file to point to the cacert.pem file for SSL verification.

```ini
; Enable SSL certificate verification
openssl.cafile = "C:\php\extras\ssl\cacert.pem"  ; Windows path
; openssl.cafile = "/etc/ssl/certs/cacert.pem"   ; Linux/macOS path

; For cURL specifically
curl.cainfo = "C:\php\extras\ssl\cacert.pem"     ; Windows path
; curl.cainfo = "/etc/ssl/certs/cacert.pem"      ; Linux/macOS path
```

--------------------------------

### Compare Lookup Results with CepSupport

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepsupport.md

Demonstrates using getResult to compare against lookup results for failure detection.

```php
use JeffersonGoncalves\Support\CepSupport;

$empty = CepSupport::getResult();

// Use it to compare against lookup results:
$result = $someLookup();
if ($result === CepSupport::getResult()) {
    // Lookup failed (array comparison — a new array is allocated per call).
}
```

--------------------------------

### Package Directory Structure

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/repository-reference.md

The file layout of the package, including the service provider, Eloquent model, service logic, and configuration files.

```text
src/
├── CepServiceProvider.php     # Spatie package provider — registers config + migration
├── Models/Cep.php             # Eloquent model — primary public entry point
├── Services/CepService.php    # Static provider chain (HTTP lookups, normalization, persistence)
└── Support/CepSupport.php     # Empty-result array factory
config/cep.php                 # timeout, verify_ssl, cache_ttl
database/migrations/create_cep_table.php
tests/                         # Pest suite (Unit + Feature)
```

--------------------------------

### Verify SSL Configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Tests the SSL connection to ensure the configuration is working correctly.

```php
// Test SSL connection
$response = file_get_contents('https://brasilapi.com.br/api/cep/v1/01310100');
if ($response !== false) {
    echo "SSL configuration is working correctly!";
} else {
    echo "SSL configuration needs attention.";
}
```

--------------------------------

### Restart Web Server Services

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Commands to restart common web server services to apply the updated php.ini configuration.

```bash
# Apache
sudo systemctl restart apache2

# Nginx
sudo systemctl restart nginx

# PHP-FPM
sudo systemctl restart php-fpm
```

--------------------------------

### Import CepSupport

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepsupport.md

The import path for the CepSupport helper class.

```php
use JeffersonGoncalves\Support\CepSupport;
```

--------------------------------

### Public Method Signatures

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/repository-reference.md

A collection of public method signatures extracted from the package source files.

```php
// src/Models/Cep.php
public static function checkCep(?string $cep): bool                                       // line 42
public static function findByCep(?string $cep): array                                     // line 49
public static function findByCepInDatabase(?string $cep): array                           // line 70
public static function sanitize(?string $cep): ?string                                    // line 86
public function isStale(): bool                                                           // line 101
public static function updateByCep(string $cep, string $state, string $city, string $neighborhood, string $street): void  // line 116

// src/Services/CepService.php
public static function findByCep(?string $cep): array                                     // line 12

// src/Support/CepSupport.php
public static function getResult(): array                                                 // line 7

// src/CepServiceProvider.php
public function configurePackage(Package $package): void                                  // line 10
```

--------------------------------

### CepService Error Handling

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

Demonstrates how to check if the lookup failed by comparing the result against the default empty result set.

```php
use JeffersonGoncalves\Cep\Services\CepService;

$result = CepService::findByCep('99999999');

if ($result === CepSupport::getResult()) {
    // All three providers failed or returned no address data.
    // A ConnectionException never escapes this method.
}
```

--------------------------------

### AwesomeAPI Service Configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/endpoints.md

Defines the URL structure and response mapping for the AwesomeAPI service as implemented in src/Services/CepService.php.

```php
'url' => fn (string $cep): string => "https://cep.awesomeapi.com.br/json/{$cep}",
'map' => fn (array $response): array => [
    'state' => $response['state'],
    'city' => $response['city'],
    'neighborhood' => $response['district'] ?? '',
    'street' => $response['address'] ?? '',
],
```

--------------------------------

### Import CepService

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

The namespace and class import required to access the CepService functionality.

```php
use JeffersonGoncalves\Cep\Services\CepService;
```

--------------------------------

### Test CEP Lookup

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Demonstrates how to seed the database to test CEP lookups without triggering external API calls.

```php
use JeffersonGoncalves\Cep\Models\Cep;

it('finds a valid CEP', function () {
    // Seed the database to avoid external API calls
    Cep::create([
        'cep' => '01001000',
        'state' => 'SP',
        'city' => 'Sao Paulo',
        'neighborhood' => 'Se',
        'street' => 'Praca da Se',
    ]);

    $result = Cep::findByCep('01001000');

    expect($result)
        ->toBeArray()
        ->and($result['cep'])->toBe('01001000')
        ->and($result['state'])->toBe('SP');
});
```

--------------------------------

### Set SSL Environment Variable

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Sets the SSL_CERT_FILE environment variable as an alternative to modifying php.ini.

```bash
export SSL_CERT_FILE=/path/to/cacert.pem
```

--------------------------------

### Import the Cep Model

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Use this namespace to access the Cep model in your application code.

```php
use JeffersonGoncalves\Cep\Models\Cep;
```

--------------------------------

### Add a new CEP provider in CepService::findByCep

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Implement a new try/catch block to fetch and map data from a new CEP provider. Ensure you map provider-specific fields to standard keys and use the null coalescing operator for optional fields.

```php
try {
    $request = Http::timeout(5)->withOptions($options)
        ->get("https://newprovider.com/api/{$cep}")->json();
    if (! empty($request['cep'])) {
        Cep::updateByCep(
            $cep,
            $request['state_field'],
            $request['city_field'],
            $request['neighborhood_field'] ?? '',
            $request['street_field'] ?? ''
        );
        return [
            'cep' => $cep,
            'state' => $request['state_field'],
            'city' => $request['city_field'],
            'neighborhood' => $request['neighborhood_field'] ?? '',
            'street' => $request['street_field'] ?? '',
        ];
    }
} catch (ConnectionException $ignored) {
}
```

--------------------------------

### Register via composer.json

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepserviceprovider.md

The package is auto-discovered by Laravel using the extra.laravel.providers entry in the project's composer.json file.

```json
"extra": {
    "laravel": {
        "providers": [
            "JeffersonGoncalves\\Cep\\CepServiceProvider"
        ]
    }
}
```

--------------------------------

### Configure Laravel HTTP Client for SSL

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Uses the Laravel HTTP client options to specify the path to the CA certificate bundle.

```php
Http::withOptions([
    'verify' => '/path/to/cacert.pem'
])->get('https://api.example.com');
```

--------------------------------

### Validation Before Processing

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Use Cep::checkCep to verify the format before attempting to fetch data to avoid invalid requests.

```php
$cep = '01310-100';

if (Cep::checkCep($cep)) {
    $data = Cep::findByCep($cep);
    // Process valid CEP data
} else {
    // Handle invalid CEP
    throw new InvalidArgumentException('Invalid CEP provided');
}
```

--------------------------------

### Handling Database Errors

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Shows how to wrap the CEP lookup in a try-catch block to handle potential database connection issues.

```php
try {
    $result = Cep::findByCep('01310-100');
} catch (\Exception $e) {
    // Handle database connection issues
    Log::error('CEP lookup failed: ' . $e->getMessage());
}
```

--------------------------------

### Enable Laravel debug mode

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Configuration setting in the .env file to enable detailed error messages.

```php
// Enable Laravel debug mode to see detailed error messages
// In .env file:
APP_DEBUG=true
```

--------------------------------

### Direct API lookup via CepService

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Use CepService to bypass the database cache and query external APIs directly.

```php
use JeffersonGoncalves\Cep\Services\CepService;

// Direct API lookup (bypasses database cache)
$result = CepService::findByCep('01001000');
```

--------------------------------

### CepServiceProvider Class Declaration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepserviceprovider.md

The class definition extending PackageServiceProvider, which configures the package name, config file, and migrations.

```php
<?php

namespace JeffersonGoncalves\Cep;

use Spatie\LaravelPackageTools\Package;
use Spatie\LaravelPackageTools\PackageServiceProvider;

class CepServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package->name('laravel-cep')
            ->hasConfigFile()
            ->hasMigration('create_cep_table');
    }
}
```

--------------------------------

### Cep::checkCep implementation

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

The internal implementation logic for the checkCep method.

```php
$result = self::findByCep($cep);

return ! empty($result['cep']);
```

--------------------------------

### Handle lookup failures gracefully

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/errors.md

Check for an empty result array to handle cases where the CEP is not found, input is invalid, or providers are unreachable without using try/catch.

```php
use JeffersonGoncalves\Cep\Models\Cep;

$result = Cep::findByCep('01310-100');

if (empty($result['cep'])) {
    // Not found / invalid input / all providers unreachable.
    // No exception was thrown; handle gracefully.
}
```

--------------------------------

### CEP Check and Database-Only Methods

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/repository-reference.md

Helper methods for verifying CEP existence and performing database-only lookups without external HTTP requests.

```php
`Cep::checkCep()` = `! empty(Cep::findByCep($cep)['cep'])`. `Cep::findByCepInDatabase()` is the database-only variant that never performs HTTP.
```

--------------------------------

### Manual Provider Registration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepserviceprovider.md

If package discovery is disabled, register the provider manually in the bootstrap/providers.php file for Laravel 12/13.

```php
// bootstrap/providers.php (Laravel 12/13)
return [
    App\Providers\AppServiceProvider::class,
    JeffersonGoncalves\Cep\CepServiceProvider::class,
];
```

--------------------------------

### Internal database caching logic

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

The package uses updateOrCreate to persist successful API responses to the database.

```php
// This is called internally after each successful API response
Cep::updateByCep($cep, $state, $city, $neighborhood, $street);

// Uses updateOrCreate - inserts new or updates existing
Cep::updateOrCreate(
    ['cep' => $cep],
    ['state' => $state, 'city' => $city, 'neighborhood' => $neighborhood, 'street' => $street]
);
```

--------------------------------

### CepService::timeout() configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

Retrieves the per-request timeout in seconds from the cep.timeout configuration key, defaulting to 5.

```php
protected static function timeout(): int
{
    return (int) config('cep.timeout', 5);
}
```

--------------------------------

### Batch Processing

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Iterate through an array of CEP strings to retrieve multiple address records.

```php
$ceps = ['01310-100', '20040-020', '30112-000'];
$results = [];

foreach ($ceps as $cep) {
    $result = Cep::findByCep($cep);
    if (!empty($result['cep'])) {
        $results[] = $result;
    }
}
```

--------------------------------

### ViaCEP Service Configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/endpoints.md

Defines the URL structure and response mapping for the ViaCEP API service as implemented in src/Services/CepService.php.

```php
'url' => fn (string $cep): string => "https://viacep.com.br/ws/{$cep}/json/",
'map' => fn (array $response): array => [
    'state' => $response['uf'],
    'city' => $response['localidade'],
    'neighborhood' => $response['bairro'] ?? '',
    'street' => $response['logradouro'] ?? '',
],
```

--------------------------------

### Create CEP Database Table

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Defines the SQL schema for the cep table, including columns for state, city, neighborhood, and street.

```sql
CREATE TABLE `cep` (
  `cep` varchar(8) NOT NULL PRIMARY KEY,
  `state` enum('AC','AL','AM','AP','BA','CE','DF','ES','GO','MA','MG','MS','MT','PA','PB','PE','PI','PR','RJ','RN','RO','RR','RS','SC','SE','SP','TO') DEFAULT NULL,
  `city` varchar(255) DEFAULT NULL,
  `neighborhood` varchar(255) DEFAULT NULL,
  `street` varchar(255) DEFAULT NULL,
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL
);
```

--------------------------------

### Mock External APIs

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Uses Laravel's Http::fake to simulate API failures and test fallback logic between providers.

```php
use Illuminate\Support\Facades\Http;

it('falls back to ViaCEP when BrasilAPI fails', function () {
    Http::fake([
        'brasilapi.com.br/*' => Http::response(null, 500),
        'viacep.com.br/*' => Http::response([
            'cep' => '01001-000',
            'uf' => 'SP',
            'localidade' => 'Sao Paulo',
            'bairro' => 'Se',
            'logradouro' => 'Praca da Se',
        ]),
    ]);

    $result = \JeffersonGoncalves\Cep\Services\CepService::findByCep('01001000');

    expect($result['state'])->toBe('SP');
});
```

--------------------------------

### BrasilAPI Provider Configuration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/endpoints.md

The URL pattern and response mapping configuration for the BrasilAPI provider.

```php
'url' => fn (string $cep): string => "https://brasilapi.com.br/api/cep/v1/{$cep}",
'map' => fn (array $response): array => [
    'state' => $response['state'],
    'city' => $response['city'],
    'neighborhood' => $response['neighborhood'] ?? '',
    'street' => $response['street'] ?? '',
],
```

--------------------------------

### Test checkCep Existence

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Verifies the boolean return value of the checkCep method for valid and null inputs.

```php
it('checks if CEP exists', function () {
    Cep::create([
        'cep' => '01001000',
        'state' => 'SP',
        'city' => 'Sao Paulo',
        'neighborhood' => 'Se',
        'street' => 'Praca da Se',
    ]);

    expect(Cep::checkCep('01001000'))->toBeTrue();
    expect(Cep::checkCep(null))->toBeFalse();
});
```

--------------------------------

### Bulk CEP Existence Check

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Optimized database query to check for the existence of multiple CEPs at once.

```php
// Bulk CEP existence check
$ceps = ['01310100', '20040020', '30112000'];
$existingCeps = Cep::whereIn('cep', $ceps)->pluck('cep')->toArray();
```

--------------------------------

### Cep::checkCep(?string $cep): bool

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Checks if a given CEP is valid and exists in the database. Returns true if the CEP is found, false otherwise.

```APIDOC
## Cep::checkCep(?string $cep): bool

### Description
Validates a CEP string and checks its existence in the database. Returns true if the CEP is resolved successfully, false for invalid formats or non-existent codes.

### Parameters
- **$cep** (string|null) - Required - The raw CEP input string to check.

### Return Type
- **bool** - Returns true if the CEP exists, false otherwise.

### Example
```php
use JeffersonGoncalves\Cep\Models\Cep;

if (Cep::checkCep('01310-100')) {
    // CEP exists
}
```
```

--------------------------------

### Retrieve Address with findByCep

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Retrieves complete address information for a given CEP, checking the local database before querying external APIs.

```php
$result = Cep::findByCep('12345-678');
```

--------------------------------

### Cep::findByCepInDatabase(?string $cep): array

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Retrieves CEP information from the local database without performing external HTTP requests.

```APIDOC
## Cep::findByCepInDatabase(?string $cep): array

### Description
Looks up a CEP using only the local database. This method does not trigger external provider lookups or database writes.

### Parameters
- **$cep** (string|null) - Required - The raw CEP input string to look up.

### Return Type
- **array** - Returns the stored record if found, otherwise an empty array.

### Example
```php
use JeffersonGoncalves\Cep\Models\Cep;

$localOnly = Cep::findByCepInDatabase('01310-100');
```
```

--------------------------------

### CepSupport::getResult()

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepsupport.md

Retrieves a fresh array representing an empty CEP result, containing keys for cep, state, city, neighborhood, and street, all initialized to empty strings.

```APIDOC
## static CepSupport::getResult()

### Description
Returns a fresh array with exactly five keys, all set to empty strings. This is used as the canonical 'empty result' structure when a CEP lookup fails.

### Return Type
`array`

### Return Structure
- **cep** (string) - ''
- **state** (string) - ''
- **city** (string) - ''
- **neighborhood** (string) - ''
- **street** (string) - ''

### Usage Example
```php
use JeffersonGoncalves\Cep\Support\CepSupport;

$empty = CepSupport::getResult();

// Use it to compare against lookup results:
$result = $someLookup();
if ($result === CepSupport::getResult()) {
    // Lookup failed
}
```
```

--------------------------------

### Define CepService providers method

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

The providers method returns an array of callables for building request URLs and mapping provider-specific responses to a normalized format.

```php
/**
 * The list of CEP providers, each describing how to build the request URL
 * and how to map the provider response to a normalized address array.
 *
 * @return array<int, array{url: callable, map: callable}>
 */
protected static function providers(): array
```

--------------------------------

### CepService Return Type Structure

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

The expected structure of the array returned by the findByCep method.

```php
[
    'cep'          => string, // the sanitized 8-digit input
    'state'        => string,
    'city'         => string,
    'neighborhood' => string, // '' when provider omits it
    'street'       => string, // '' when provider omits it
]
```

--------------------------------

### Cep::findByCepInDatabase method signature

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

The method signature for looking up a CEP exclusively in the local database.

```php
/**
 * Look up a CEP using only the local database, without ever calling the
 * external providers (and therefore without writing to the database).
 */
public static function findByCepInDatabase(?string $cep): array
```

--------------------------------

### Cep::findByCep(?string $cep)

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Retrieves address information for a given CEP. The method normalizes the input, checks the local database, and falls back to external providers if necessary.

```APIDOC
## Cep::findByCep(?string $cep)

### Description
Retrieves address information for a given CEP. The method normalizes the input, checks the local database, and falls back to external providers if necessary.

### Parameters
- **$cep** (string) - Required - Raw CEP input. Accepts various formats (dots, dashes, etc.), which are stripped and normalized to an 8-digit string.

### Return Type
- **array** - Returns an associative array containing 'cep', 'state', 'city', 'neighborhood', and 'street'. Returns an empty array if the CEP is not found or invalid.

### Example
```php
use JeffersonGoncalves\Cep\Models\Cep;

$address = Cep::findByCep('01310-100');

if (! empty($address['cep'])) {
    echo $address['state'].' / '.$address['city'];
}
```
```

--------------------------------

### CepService Class Declaration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

The abstract class structure defining the static methods for CEP lookups and internal provider configuration.

```php
abstract class CepService
{
    public static function findByCep(?string $cep): array;
    protected static function providers(): array;   // @return array<int, array{url: callable, map: callable}>
    protected static function timeout(): int;
    protected static function httpOptions(): array; // @return array<string, mixed>
}
```

--------------------------------

### CepSupport Class Declaration

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepsupport.md

The abstract class definition containing the static getResult method.

```php
abstract class CepSupport
{
    public static function getResult(): array
    {
        return [
            'cep' => '',
            'state' => '',
            'city' => '',
            'neighborhood' => '',
            'street' => '',
        ];
    }
}
```

--------------------------------

### JeffersonGoncalves\Cep\Models\Cep

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/repository-reference.md

The main entry point for CEP operations, including lookup, database retrieval, and data management.

```APIDOC
## public static function checkCep(?string $cep): bool

### Description
Checks if a given CEP string is valid.

### Parameters
- **cep** (string) - Optional - The CEP string to validate.

## public static function findByCep(?string $cep): array

### Description
Retrieves CEP information by performing a lookup.

### Parameters
- **cep** (string) - Optional - The CEP string to search for.

## public static function findByCepInDatabase(?string $cep): array

### Description
Retrieves CEP information specifically from the local database.

### Parameters
- **cep** (string) - Optional - The CEP string to search for.

## public static function sanitize(?string $cep): ?string

### Description
Sanitizes a CEP string by removing non-numeric characters.

### Parameters
- **cep** (string) - Optional - The CEP string to sanitize.

## public function isStale(): bool

### Description
Checks if the current model instance data is considered stale.

## public static function updateByCep(string $cep, string $state, string $city, string $neighborhood, string $street): void

### Description
Updates CEP information in the database.

### Parameters
- **cep** (string) - Required - The CEP to update.
- **state** (string) - Required - The state name.
- **city** (string) - Required - The city name.
- **neighborhood** (string) - Required - The neighborhood name.
- **street** (string) - Required - The street name.
```

--------------------------------

### Verify CEP validity

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/errors.md

Use checkCep to verify a CEP, which returns false instead of throwing an exception when the CEP is not found.

```php
use JeffersonGoncalves\Cep\Models\Cep;

// checkCep returns false instead of throwing:
$isValid = Cep::checkCep('00000-000');
```

--------------------------------

### Perform CEP lookup using Cep model

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/resources/boost/skills/cep-development/SKILL.md

Use the Cep model to find addresses or validate CEPs. It handles database lookups and API fallbacks automatically.

```php
use JeffersonGoncalves\Cep\Models\Cep;

// Find address by CEP - returns associative array
$address = Cep::findByCep('01001000');
// Returns: ['cep' => '01001000', 'state' => 'SP', 'city' => '...', 'neighborhood' => '...', 'street' => '...']

// Accepts various formats - automatically sanitized
$address = Cep::findByCep('01001-000');
$address = Cep::findByCep('01.001-000');

// Check if CEP exists and is valid
$isValid = Cep::checkCep('01001000'); // true or false
```

--------------------------------

### Cep::checkCep(string $cep)

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Validates if a specific CEP exists.

```APIDOC
## checkCep(string $cep)

### Description
Validates if a CEP exists and returns a boolean value.

### Parameters
- **cep** (string) - Required - The CEP code to validate.

### Response
- **bool** - Returns true if the CEP exists, false otherwise.
```

--------------------------------

### CepService::findByCep(?string $cep): array

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

Performs an external HTTP lookup for a given CEP against multiple providers, normalizes the response, and returns the address data.

```APIDOC
## CepService::findByCep(?string $cep): array

### Description
Performs an external HTTP lookup for a given CEP against a fixed fallback chain of providers (BrasilAPI, ViaCEP, AwesomeAPI). It normalizes the first successful response, persists it to the database, and returns the standardized address.

### Parameters
- **$cep** (string|null) - Required - An 8-digit numeric CEP string. If null is passed, it returns an empty result array.

### Return Type
- **array** - An associative array containing: 'cep' (string), 'state' (string), 'city' (string), 'neighborhood' (string), 'street' (string).

### Throws
- **Exception** - May propagate exceptions from the HTTP client if they are not ConnectionExceptions.

### Example
```php
use JeffersonGoncalves\Cep\Services\CepService;

$result = CepService::findByCep('01310100');
// Returns: ['cep' => '01310100', 'state' => 'SP', 'city' => 'São Paulo', ...]
```
```

--------------------------------

### Catch genuine exceptions

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/errors.md

Wrap calls in a try/catch block to handle genuine exceptions such as database errors or non-ConnectionException HTTP failures.

```php
use JeffersonGoncalves\Cep\Models\Cep;
use Illuminate\Database\QueryException;

try {
    $result = Cep::findByCep('01310-100');
} catch (QueryException $e) {
    // Database unavailable or missing cep table.
    Log::error('CEP lookup failed: '.$e->getMessage());
}
```

--------------------------------

### Cep::findByCep(string $cep)

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/README.md

Retrieves complete address information for a given CEP. The method validates the input, checks the local database, queries external APIs if necessary, and caches the result.

```APIDOC
## findByCep(string $cep)

### Description
Retrieves complete address information for a given CEP. The method automatically formats and validates the CEP, checks the local database first, queries external APIs if not found locally, and stores the result in the database for future use.

### Parameters
- **cep** (string) - Required - The CEP code to look up (e.g., '01310-100').

### Response
- **array** - Returns an array containing 'cep', 'state', 'city', 'neighborhood', and 'street'.
```

--------------------------------

### JeffersonGoncalves\Cep\Support\CepSupport

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/repository-reference.md

Utility class for handling CEP results.

```APIDOC
## public static function getResult(): array

### Description
Returns a standard empty-result array structure.
```

--------------------------------

### JeffersonGoncalves\Cep\Services\CepService

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/repository-reference.md

Service class for provider-chain HTTP lookups.

```APIDOC
## public static function findByCep(?string $cep): array

### Description
Performs an HTTP lookup for a CEP using the configured provider chain.

### Parameters
- **cep** (string) - Optional - The CEP string to search for.
```

--------------------------------

### Cep::checkCep method signature

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

The method signature for checking the validity of a CEP string.

```php
public static function checkCep(?string $cep): bool
```

--------------------------------

### Successful CEP Address Result Array

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/types.md

The shape returned by successful lookups from Cep::findByCep(), Cep::findByCepInDatabase(), CepService::findByCep(), and Cep::toArray().

```php
[
    'cep'          => '01310100',   // string — the 8-digit sanitized CEP
    'state'        => 'SP',         // string — Brazilian state abbreviation
    'city'         => 'São Paulo',  // string — city name
    'neighborhood' => 'Bela Vista', // string — neighborhood ('' when provider omits it)
    'street'       => 'Avenida Paulista', // string — street ('' when provider omits it)
]
```

--------------------------------

### Cep::sanitize(?string $cep)

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

Normalizes and validates a raw CEP string, returning a standardized 8-digit numeric string or null if invalid.

```APIDOC
## Cep::sanitize(?string $cep)

### Description
Normalizes and validates a raw CEP string. Returns null when the value is not a valid 8 digit numeric CEP, short-circuiting before any database or HTTP lookup.

### Parameters
- **$cep** (string|null) - Required - Raw CEP string to be sanitized.

### Return Type
- **string|null** - The normalized 8-digit numeric string, or null if the input is empty or invalid.

### Example
```php
use JeffersonGoncalves\Cep\Models\Cep;

Cep::sanitize('01.310-100'); // '01310100'
Cep::sanitize(null);         // null
```
```

--------------------------------

### Cep::updateByCep method definition

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cep-model.md

The method signature for updating or creating a CEP record in the database.

```php
public static function updateByCep(string $cep, string $state, string $city, string $neighborhood, string $street): void
```

--------------------------------

### Handling CEP Validation Errors

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Demonstrates that an invalid CEP input returns an empty result array.

```php
$cep = 'invalid';
$result = Cep::findByCep($cep);

// Returns empty result array:
// [
//     'cep' => '',
//     'state' => '',
//     'city' => '',
//     'neighborhood' => '',
//     'street' => ''
// ]
```

--------------------------------

### Integration with Laravel Validation

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/PACKAGE_USAGE_GUIDE.mdx

Shows how to use a custom validation rule to verify CEPs within a Laravel request validation.

```php
// Custom validation rule
use Illuminate\Validation\Rule;

$request->validate([
    'cep' => [
        'required',
        'string',
        function ($attribute, $value, $fail) {
            if (!Cep::checkCep($value)) {
                $fail('The CEP is invalid or not found.');
            }
        },
    ],
]);
```

--------------------------------

### Provider Entry Array Type Definition

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/types.md

The internal return type for CepService::providers() defining the contract for external CEP data providers.

```php
/**
 * @return array<int, array{url: callable, map: callable}>
 */
```

--------------------------------

### CepService::findByCep Method Signature

Source: https://github.com/jeffersongoncalves/laravel-cep/blob/master/_autodocs/api-reference/cepservice.md

The signature for the primary public method used to retrieve address information by CEP.

```php
public static function findByCep(?string $cep): array
```
Tokens:
Raw