### Install Laravel CEP Package

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

Installs the Laravel CEP package using Composer. This is the first step to integrate CEP lookup functionality into your Laravel application.

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

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

### Basic CEP Lookup Example

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

Demonstrates a basic usage of the Cep::findByCep method to retrieve address information for a given CEP and display the results.

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

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

if (!empty($address['cep'])) {
    echo "CEP: " . $address['cep'] . "\n";
    echo "State: " . $address['state'] . "\n";
    echo "City: " . $address['city'] . "\n";
    echo "Neighborhood: " . $address['neighborhood'] . "\n";
    echo "Street: " . $address['street'] . "\n";
} else {
    echo "CEP not found";
}
```

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

### Batch CEP Processing Example

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

Illustrates how to process multiple CEPs in a loop, retrieving and storing valid address data for each CEP in the provided list.

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

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

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

print_r($results);
```

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

### Database Error Handling Example

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

Demonstrates how to wrap a CEP lookup in a try-catch block to handle potential database connection issues or other exceptions.

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

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

### Install Laravel Cep Package

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

Installs the Laravel Cep package using Composer and publishes/runs its database migrations.

```bash
composer require jeffersongoncalves/laravel-cep

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

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

### Manual CEP Testing Examples

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

PHP code snippets for manually testing the Cep::findByCep and Cep::checkCep methods with valid, invalid, and malformed CEP values.

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

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

### Run Unit Tests

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

Composer command to execute the project's unit tests.

```Bash
composer test
```

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

### Custom HTTP Client Timeout Configuration

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

Example of customizing the HTTP client timeout using Laravel's Http facade for external API requests.

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

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

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

### Restart Web Server Services

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

Commands to restart common web server and PHP-FPM services after updating PHP configuration.

```Bash
# Apache
sudo systemctl restart apache2

# Nginx
sudo systemctl restart nginx

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

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

### CEP Validation Before Processing Example

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

Shows how to validate a CEP using Cep::checkCep before attempting to retrieve its details with Cep::findByCep, ensuring data integrity.

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

$cep = '01310-100';

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

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

### CEP Validation Error Example

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

Illustrates the expected empty result when an invalid or non-existent CEP is passed to Cep::findByCep.

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

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

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

### Laravel API Route for CEP Lookup

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

Shows an example of defining an API route in Laravel to directly query CEP data using the Cep::findByCep method.

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

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

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

### Download Certificate Bundle

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

Command to download the latest CA certificate bundle from curl.se, necessary for SSL verification in some environments.

```Bash
curl -o cacert.pem https://curl.se/ca/cacert.pem
```

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

### Custom Validation Rule for CEP

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

Example of creating a custom validation rule in Laravel to check the validity of a CEP using the Cep::checkCep method.

```PHP
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.');
            }
        },
    ],
]);
```

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

### Indexing Recommendations for CEP Table

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

SQL statements suggesting optional additional indexes for the 'cep' table, beyond the primary key, for potential reporting performance improvements.

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

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

### Publish Migrations and Migrate

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

Publishes the package's database migration files and then runs them to create the necessary 'cep' table in your database. This table is used for caching CEP data.

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

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

### CepService API Provider Chain

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

Illustrates the order in which CepService attempts to fetch CEP data from external APIs. It includes a fallback mechanism and SSL handling for requests.

```APIDOC
CepService API Provider Chain:
  The CepService queries CEP data using the following providers in sequence:
  1. BrasilAPI: https://brasilapi.com.br/api/cep/v1/{cep}
  2. ViaCEP: https://viacep.com.br/ws/{cep}/json/
  3. AwesomeAPI: https://cep.awesomeapi.com.br/json/{cep}

  SSL Handling:
  - Automatic SSL certificate detection.
  - Fallback to `verify: false` if certificates are not found.
  - Requests have a 5-second timeout.
```

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

### Update php.ini for SSL Configuration

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

Configuration settings for php.ini to specify the location of the downloaded certificate bundle for SSL verification.

```INI
; SSL certificate configuration
openssl.cafile = "/path/to/cacert.pem"
curl.cainfo = "/path/to/cacert.pem"
```

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

### Bulk CEP Existence Check

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

PHP code demonstrating an efficient way to check for the existence of multiple CEPs in the database using Eloquent's whereIn and pluck methods.

```PHP
$ceps = ['01310100', '20040020', '30112000'];
$existingCeps = Cep::whereIn('cep', $ceps)->pluck('cep')->toArray();
```

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

### Laravel Cep API Methods

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

Details the primary methods available in the Laravel Cep package for CEP lookups and validation. Includes signatures, descriptions, and usage examples.

```APIDOC
Cep::findByCep(string $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, and stores the result in the database for future use.
  Example:
    $result = Cep::findByCep('12345-678');

Cep::checkCep(string $cep): bool
  Validates if a CEP exists and returns a boolean value.
  Example:
    $isValid = Cep::checkCep('12345-678');
```

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

### Laravel Controller for CEP Lookup

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

Demonstrates how to use the Cep::findByCep method within a Laravel controller to fetch address data based on a CEP. Includes input validation and error handling for CEP not found.

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

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

### CEP Table Schema

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

Defines the SQL structure for the 'cep' table, including columns for CEP, state, city, neighborhood, street, and timestamps. Specifies the CEP as the primary key.

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

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

### Cep Model checkCep Method

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

Validates if a given CEP exists and is in a correct format. Returns a boolean value indicating the validity of the CEP.

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

$isValid = Cep::checkCep('01310-100'); // Returns true/false
$isInvalid = Cep::checkCep('00000-000'); // Returns false
$isEmpty = Cep::checkCep(''); // Returns false
```

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

### Enable Laravel Debug Mode

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

Enables Laravel's debug mode to display detailed error messages. This is typically configured by setting the APP_DEBUG variable to true in the .env file.

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

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

### Cep Model findByCep Method

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

The primary method for looking up CEP data using the Cep model. It handles automatic CEP formatting, database lookup, and API fallback. It returns an array containing address details or an empty array on failure.

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

// Various input formats accepted
$result1 = Cep::findByCep('01310-100');
$result2 = Cep::findByCep('01310100');
$result3 = Cep::findByCep('1310100'); // Auto-padded to 01310100

// Returns array structure:
// [
//     'cep' => '01310100',
//     'state' => 'SP',
//     'city' => 'São Paulo',
//     'neighborhood' => 'Bela Vista',
//     'street' => 'Avenida Paulista'
// ]
```

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

### Configure PHP SSL Certificate (cacert.pem)

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

Provides instructions on how to configure PHP's SSL certificate verification by setting the `openssl.cafile` and `curl.cainfo` directives in `php.ini` to point to a downloaded `cacert.pem` file.

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

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

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

### Run Project Tests

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

Executes the project's test suite using Composer. This command is typically used to ensure the application's functionality and identify regressions after changes.

```bash
composer test
```

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

### Set SSL Certificate Environment Variable

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

Shows how to set the `SSL_CERT_FILE` environment variable using a bash command. This is an alternative method to configure SSL certificates when `php.ini` cannot be modified. It points to a specific CA certificate bundle file.

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

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

### Configure Laravel HTTP Client for SSL Verification

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

Illustrates how to specify a custom SSL certificate verification path using Laravel's HTTP client options. This approach allows per-request control over SSL verification, overriding global configurations. Disabling verification (`'verify' => false`) is strongly discouraged.

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

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

### Test SSL Connection with PHP

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

Demonstrates how to test SSL certificate verification using PHP's `file_get_contents` function. It checks if an HTTPS request is successful, indicating correct SSL configuration. This method relies on the system's or PHP's default certificate bundle.

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

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

### Find CEP Information with Laravel Cep

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

Demonstrates how to find address details for a given Brazilian CEP using the Cep::findByCep() method. It handles formatting, validation, local database checks, and external API queries.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.