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(2mo ago)62.0k↑15.8%1MITPHPPHP ^8.2CI failing

Since Jun 26Pushed 1mo 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 1mo 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.jpg)](https://raw.githubusercontent.com/jeffersongoncalves/filament-cep-field/3.x/art/jeffersongoncalves-filament-cep-field.jpg)

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 95% of packages

Maintenance88

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity56

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 ~22 days

Recently: every ~4 days

Total

13

Last Release

61d 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-03-06

2.x-dev → 3.x-dev2026-03-19

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 (45 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (7 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

[guava/filament-modal-relation-managers

Allows you to embed relation managers inside filament modals.

7565.0k4](/packages/guava-filament-modal-relation-managers)[jeffersongoncalves/filament-qrcode-field

A Laravel Filament package that provides QR Code field functionality for your web applications. This package extends Filament v3 with a simple QR code input component.

113.2k](/packages/jeffersongoncalves-filament-qrcode-field)[jeffersongoncalves/filament-topbar

A simple yet effective Filament plugin that automatically adds a customized topbar to your Filament admin panel. This plugin enhances your Filament panel's user experience by replacing the default topbar component with an improved version that displays navigation and user interface elements in strategic locations.

171.2k](/packages/jeffersongoncalves-filament-topbar)[tapp/filament-webhook-client

Add a Filament resource and a policy for Spatie Webhook client

1120.2k](/packages/tapp-filament-webhook-client)[a2insights/filament-saas

Filament Saas for A2Insights

161.1k](/packages/a2insights-filament-saas)

PHPackages © 2026

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