PHPackages jeffersongoncalves/laravel-cep - 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. [Utility & Helpers](/categories/utility) 4. / 5. jeffersongoncalves/laravel-cep ActiveLibrary[Utility & Helpers](/categories/utility) jeffersongoncalves/laravel-cep ============================== A simple and efficient PHP package for querying Brazilian postal codes (CEP). This package provides an easy way to retrieve address information from Brazilian ZIP codes through multiple providers. 1.1.2(2mo ago)32.2k↓29.1%1MITPHPPHP ^8.2|^8.3CI failing Since Mar 10Pushed 1mo ago1 watchersCompare [ Source](https://github.com/jeffersongoncalves/laravel-cep)[ Packagist](https://packagist.org/packages/jeffersongoncalves/laravel-cep)[ Docs](https://github.com/jeffersongoncalves/laravel-cep)[ RSS](/packages/jeffersongoncalves-laravel-cep/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (7)Versions (12)Used By (1) [![Laravel Cep](https://raw.githubusercontent.com/jeffersongoncalves/laravel-cep/master/art/jeffersongoncalves-laravel-cep.png)](https://raw.githubusercontent.com/jeffersongoncalves/laravel-cep/master/art/jeffersongoncalves-laravel-cep.png) Laravel Cep =========== [](#laravel-cep) [![Latest Version on Packagist](https://camo.githubusercontent.com/17d12101643cf2279c03e58baf3c63c6f57f0fd8863353b78d5964b4f90b7606/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a6566666572736f6e676f6e63616c7665732f6c61726176656c2d6365702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jeffersongoncalves/laravel-cep)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/af4a9dcc160c1ca3d8917913619600b53bdfec882de9ce9a98e79ea33a76880f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a6566666572736f6e676f6e63616c7665732f6c61726176656c2d6365702f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d6173746572266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/jeffersongoncalves/laravel-cep/actions?query=workflow%3A%22Fix+PHP+code+styling%22+branch%3Amaster)[![Total Downloads](https://camo.githubusercontent.com/33b135272fdf02a1a0b7b3edf2b2d3397294b7456c33266f0879cb722ebb30ae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a6566666572736f6e676f6e63616c7665732f6c61726176656c2d6365702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jeffersongoncalves/laravel-cep) A simple and efficient Laravel package for querying Brazilian postal codes (CEP). This package provides an easy way to retrieve address information from Brazilian ZIP codes through multiple API providers with database storage. Features -------- [](#features) - 🚀 Multiple API providers (BrasilAPI, ViaCEP, AwesomeAPI) - 💾 Database storage for queried CEPs - 🎯 CEP validation and formatting - 🇧🇷 Complete Brazilian states support Installation ------------ [](#installation) You can install the package via composer: ``` composer require jeffersongoncalves/laravel-cep ``` Publish and run the migration file: ``` php artisan vendor:publish --tag=cep-migrations php artisan migrate ``` Usage ----- [](#usage) ### Basic Usage [](#basic-usage) ``` 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 ``` ### Available Methods [](#available-methods) #### `findByCep(string $cep): array` [](#findbycepstring-cep-array) 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 - Stores the result in database for future use ``` $result = Cep::findByCep('12345-678'); ``` #### `checkCep(string $cep): bool` [](#checkcepstring-cep-bool) Validates if a CEP exists and returns a boolean value. ``` $isValid = Cep::checkCep('12345-678'); ``` ### API Providers [](#api-providers) The package uses multiple API providers in the following order: 1. **BrasilAPI** - Primary provider 2. **ViaCEP** - Fallback provider 3. **AwesomeAPI** - Secondary fallback ### Database Structure [](#database-structure) The package creates a `cep` table with the following structure: - `cep` (string, 8 chars) - Primary key - `state` (enum) - Brazilian state abbreviation - `city` (string) - City name - `neighborhood` (string) - Neighborhood name - `street` (string) - Street name - `timestamps` - Created and updated timestamps 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 Popularity25 Limited adoption so far Community14 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 82.4% 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 ~39 days Recently: every ~60 days Total 10 Last Release 83d ago ### 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 (61 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (9 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (1 commits)") --- Tags addressbrasilapibrazilcepcomposerjeffersongoncalveslaravellaravel-packagephppostal-codeviacepzipcodelaraveljeffersongoncalveslaravel-cep ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/jeffersongoncalves-laravel-cep/health.svg) ``` [![Health](https://phpackages.com/badges/jeffersongoncalves-laravel-cep/health.svg)](https://phpackages.com/packages/jeffersongoncalves-laravel-cep) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)