PHPackages                             jeffersongoncalves/filament-cep-field - 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. jeffersongoncalves/filament-cep-field

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

jeffersongoncalves/filament-cep-field
=====================================

The Filament CEP Field is a custom input component designed specifically for Brazilian postal codes (CEP - Código de Endereçamento Postal). This component extends Filament's form capabilities by providing a specialized input field that handles CEP formatting, validation, and automatic address lookup.

3.0.2(4mo ago)93.3k↓43.4%1MITPHPPHP ^8.2CI passing

Since Jun 26Pushed 1w ago1 watchersCompare

[ Source](https://github.com/jeffersongoncalves/filament-cep-field)[ Packagist](https://packagist.org/packages/jeffersongoncalves/filament-cep-field)[ Docs](https://github.com/jeffersongoncalves/filament-cep-field)[ GitHub Sponsors](https://github.com/jeffersongoncalves)[ RSS](/packages/jeffersongoncalves-filament-cep-field/feed)WikiDiscussions 3.x Synced 3d ago

READMEChangelog (10)Dependencies (16)Versions (14)Used By (0)

[![Filament Cep Field](https://raw.githubusercontent.com/jeffersongoncalves/filament-cep-field/3.x/art/jeffersongoncalves-filament-cep-field.png)](https://raw.githubusercontent.com/jeffersongoncalves/filament-cep-field/3.x/art/jeffersongoncalves-filament-cep-field.png)

Filament CEP Field
==================

[](#filament-cep-field)

[![Latest Version on Packagist](https://camo.githubusercontent.com/2ef342fdfc4bc79f15340a1873bee5f92118009b328f063ae7170e19d380f04b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a6566666572736f6e676f6e63616c7665732f66696c616d656e742d6365702d6669656c642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jeffersongoncalves/filament-cep-field)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/6d4b05b51cd8a05f20c058081be0614726f6a1a3fab868fd75d5bf399cf09a28/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a6566666572736f6e676f6e63616c7665732f66696c616d656e742d6365702d6669656c642f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d332e78266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/jeffersongoncalves/filament-cep-field/actions?query=workflow%3A%22Fix+PHP+code+styling%22+branch%3A3.x)[![Total Downloads](https://camo.githubusercontent.com/4d9fd2afa3794c6ec5c05a3db443cdcab8e5d57f252e43c54cb0f54728723a2d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a6566666572736f6e676f6e63616c7665732f66696c616d656e742d6365702d6669656c642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jeffersongoncalves/filament-cep-field)[![License](https://camo.githubusercontent.com/104567436a9d79dd87dfb9071ecb0ec2e26ae33d8067f4ae962e9ac8d905d4b5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a6566666572736f6e676f6e63616c7665732f66696c616d656e742d6365702d6669656c642e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

The Filament CEP Field is a custom input component designed specifically for Brazilian postal codes (CEP - Código de Endereçamento Postal). This component extends Filament's form capabilities by providing a specialized input field that handles CEP formatting, validation, and automatic address lookup.

### What it does:

[](#what-it-does)

- **CEP Formatting**: Automatically applies the standard Brazilian CEP mask (99999-999) as users type
- **Address Lookup**: Integrates with CEP APIs to automatically fetch and populate address information
- **Form Integration**: Seamlessly integrates with Filament forms and follows Filament's design patterns
- **Validation**: Provides built-in validation for CEP format and existence
- **Customization**: Offers extensive customization options for labels, error messages, and field mappings

This component is perfect for Brazilian applications that need to collect address information efficiently and accurately.

Features
--------

[](#features)

- 🚀 Multiple API providers (BrasilAPI, ViaCEP, AwesomeAPI)
- 💾 Automatic database caching with Laravel Model Caching
- 🔄 Automatic cache invalidation
- 🎯 CEP validation and formatting
- ⚡ Queue-based cache management
- 🇧🇷 Complete Brazilian states support

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

[](#requirements)

- PHP 8.2 or higher
- Filament 5.0
- Laravel 10.0 or higher

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

[](#installation)

You can install the package via composer:

```
composer require jeffersongoncalves/filament-cep-field
```

Publish and run the migration file:

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

Usage
-----

[](#usage)

Once installed, you can use the CepInput component in your Filament forms. The component automatically applies a CEP mask (99999-999), validates the input, and can automatically populate address fields when a valid CEP is found.

```
use JeffersonGoncalves\Filament\CepField\Forms\Components\CepInput;

// Basic usage
CepInput::make('cep')
    ->required(),

// Advanced usage with all available options
CepInput::make('cep')
    ->required()
    ->setMode('suffix') // 'prefix' or 'suffix' (default: 'suffix')
    ->setActionLabel('Buscar CEP') // Custom search button label
    ->setActionLabelHidden(false) // Show/hide action label (default: false)
    ->setErrorMessage('CEP não encontrado.') // Custom error message
    ->setStreetField('street') // Field to populate with street name
    ->setNeighborhoodField('neighborhood') // Field to populate with neighborhood
    ->setCityField('city') // Field to populate with city name
    ->setStateField('state'), // Field to populate with state
```

### Available Methods

[](#available-methods)

#### `setMode(string $mode)`

[](#setmodestring-mode)

Sets the position of the search action button.

- `'suffix'` (default): Places the button after the input field
- `'prefix'`: Places the button before the input field

#### `setActionLabel(string $label)`

[](#setactionlabelstring-label)

Customizes the label text for the search action button.

- Default: `'Buscar CEP'`

#### `setActionLabelHidden(bool $hidden)`

[](#setactionlabelhiddenbool-hidden)

Controls whether the action button label is visible.

- `true`: Shows only the magnifying glass icon
- `false` (default): Shows both icon and label

#### `setErrorMessage(string $message)`

[](#seterrormessagestring-message)

Sets a custom error message when CEP lookup fails.

- Default: `'CEP inválido.'`

#### Field Mapping Methods

[](#field-mapping-methods)

These methods allow you to specify which form fields should be automatically populated with the address information:

- `setStreetField(string $fieldName)` - Default: `'street'`
- `setNeighborhoodField(string $fieldName)` - Default: `'neighborhood'`
- `setCityField(string $fieldName)` - Default: `'city'`
- `setStateField(string $fieldName)` - Default: `'state'`

### Features

[](#features-1)

- **Automatic Masking**: Applies the Brazilian CEP format (99999-999)
- **Real-time Validation**: Validates CEP format and existence
- **Automatic Address Population**: Fills related address fields when a valid CEP is found
- **Customizable Search Button**: Can be positioned as prefix or suffix with custom labels
- **Error Handling**: Provides validation errors for invalid CEPs

### Usage Examples

[](#usage-examples)

#### Simple CEP Input

[](#simple-cep-input)

```
CepInput::make('postal_code')
    ->label('CEP')
    ->required()
```

#### CEP with Custom Field Mapping

[](#cep-with-custom-field-mapping)

```
CepInput::make('cep')
    ->label('CEP')
    ->required()
    ->setStreetField('endereco')
    ->setNeighborhoodField('bairro')
    ->setCityField('cidade')
    ->setStateField('estado')
```

#### CEP with Prefix Button and Custom Labels

[](#cep-with-prefix-button-and-custom-labels)

```
CepInput::make('cep')
    ->label('Código Postal')
    ->setMode('prefix')
    ->setActionLabel('Consultar')
    ->setActionLabelHidden(false)
    ->setErrorMessage('CEP não encontrado ou inválido.')
```

SSL Certificate Configuration (cacert.pem)
------------------------------------------

[](#ssl-certificate-configuration-cacertpem)

This package makes HTTPS requests to external APIs (BrasilAPI, ViaCEP, and AwesomeAPI) to retrieve CEP information. If you encounter SSL certificate errors, you may need to configure PHP to use a proper CA certificate bundle.

### What is cacert.pem?

[](#what-is-cacertpem)

The `cacert.pem` file is a bundle of Certificate Authority (CA) certificates that PHP uses to verify SSL/TLS connections. Without proper CA certificates, PHP cannot verify the authenticity of HTTPS connections, leading to SSL errors.

### Common SSL Errors

[](#common-ssl-errors)

You might encounter errors like:

- `cURL error 60: SSL certificate problem: unable to get local issuer certificate`
- `SSL certificate verification failed`
- Connection timeouts when making API requests

### How to Configure cacert.pem

[](#how-to-configure-cacertpem)

#### Step 1: Download cacert.pem

[](#step-1-download-cacertpem)

Download the latest CA certificate bundle from the official cURL website:

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

Or download it manually from:

#### Step 2: Place the File

[](#step-2-place-the-file)

Place the `cacert.pem` file in a secure location on your server, for example:

- **Windows**: `C:\php\extras\ssl\cacert.pem`
- **Linux/macOS**: `/etc/ssl/certs/cacert.pem` or `/usr/local/etc/ssl/cacert.pem`

#### Step 3: Configure PHP

[](#step-3-configure-php)

Edit your `php.ini` file and add/update the following lines:

```
; 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
```

#### Step 4: Restart Web Server

[](#step-4-restart-web-server)

After modifying `php.ini`, restart your web server (Apache, Nginx, etc.) or PHP-FPM service.

### Verification

[](#verification)

To verify that SSL certificates are working correctly, you can test the configuration:

```
// 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.";
}
```

### Alternative Solutions

[](#alternative-solutions)

If you cannot modify `php.ini`, you can also:

1. **Set environment variable** (not recommended for production):

    ```
    export SSL_CERT_FILE=/path/to/cacert.pem
    ```
2. **Use Laravel HTTP client options** in your application:

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

**Note**: Disabling SSL verification (`'verify' => false`) is strongly discouraged as it makes your application vulnerable to man-in-the-middle attacks.

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Jèfferson Gonçalves](https://github.com/jeffersongoncalves)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance89

Actively maintained with recent releases

Popularity28

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 83.3% 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

Every ~30 days

Total

13

Last Release

9d ago

Major Versions

1.1.0 → 3.0.02026-02-16

1.1.1 → 2.1.22026-03-04

2.1.2 → 3.0.22026-03-04

1.x-dev → 2.x-dev2026-04-26

2.x-dev → 3.x-dev2026-06-25

PHP version history (2 changes)1.0.0PHP ^8.2|^8.3

3.0.0PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/411493?v=4)[Jefferson Gonçalves](/maintainers/jeffersongoncalves)[@jeffersongoncalves](https://github.com/jeffersongoncalves)

---

Top Contributors

[![jeffersongoncalves](https://avatars.githubusercontent.com/u/411493?v=4)](https://github.com/jeffersongoncalves "jeffersongoncalves (50 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (8 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")

---

Tags

cepfilamentfilament-fieldfilament-pluginlaravelfilamentjeffersongoncalvesfilament-cep-field

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/jeffersongoncalves-filament-cep-field/health.svg)

```
[![Health](https://phpackages.com/badges/jeffersongoncalves-filament-cep-field/health.svg)](https://phpackages.com/packages/jeffersongoncalves-filament-cep-field)
```

###  Alternatives

[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)[stephenjude/filament-jetstream

A Laravel starter kit built with Filament inspired by Jetstream.

17760.2k3](/packages/stephenjude-filament-jetstream)[stephenjude/filament-two-factor-authentication

Filament Two Factor Authentication: Google 2FA + Passkey Authentication

84215.9k9](/packages/stephenjude-filament-two-factor-authentication)[croustibat/filament-jobs-monitor

Background Jobs monitoring like Horizon for all drivers for FilamentPHP

274326.6k8](/packages/croustibat-filament-jobs-monitor)[marcelweidum/filament-passkeys

Use passkeys in your filamentphp app

6649.5k1](/packages/marcelweidum-filament-passkeys)[stephenjude/filament-debugger

About

104162.2k2](/packages/stephenjude-filament-debugger)

PHPackages © 2026

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