PHPackages                             risetechapps/address-for-laravel - 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. risetechapps/address-for-laravel

ActiveLibrary[Utility & Helpers](/categories/utility)

risetechapps/address-for-laravel
================================

1.8.1(3w ago)0437↓56%1MITPHPPHP ^8.3

Since May 23Pushed 3w ago1 watchersCompare

[ Source](https://github.com/risetechapps/address-for-laravel)[ Packagist](https://packagist.org/packages/risetechapps/address-for-laravel)[ Docs](https://github.com/risetechapps/address-for-laravel)[ RSS](/packages/risetechapps-address-for-laravel/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (42)Versions (13)Used By (1)

🏠 Laravel Address
=================

[](#-laravel-address)

**Laravel Address** é um pacote para Laravel que permite gerenciar diferentes tipos de endereços (padrão, entrega e cobrança) associados aos seus models de forma simples e eficiente.

---

📦 Instalação
------------

[](#-instalação)

### ✅ Requisitos

[](#-requisitos)

- PHP >= 8.3
- Laravel >= 12
- Composer

### ⚙️ Passo a Passo

[](#️-passo-a-passo)

1. Instale o package via Composer:

```
  composer require risetechapps/address-for-laravel
```

2. Adicione as traits ao seu model:

```
use RiseTechApps\Address\Traits\HasAddress\HasAddress;
use RiseTechApps\Address\Traits\HasAddress\HasAddressBilling;
use RiseTechApps\Address\Traits\HasAddress\HasAddressDelivery;

class Client extends Model
{
    use HasFactory, HasAddress, HasAddressDelivery, HasAddressBilling;
}
```

3. Execute as migrations:

```
  php artisan migrate
```

---

✨ Funcionalidades
-----------------

[](#-funcionalidades)

- 🏷 **Address:** Endereço padrão para qualquer model.
- 🏷 **Address Delivery:** Suporte a múltiplos endereços de entrega.
- 🏷 **Address Billing:** Suporte a múltiplos endereços de cobrança.

---

💡 Exemplos de Uso
-----------------

[](#-exemplos-de-uso)

### Criar um endereço padrão (manual)

[](#criar-um-endereço-padrão-manual)

```
$client = Client::find(1);

$client->address()->create([
    'street' => 'Rua Exemplo',
    'number' => '123',
    'city' => 'São Paulo',
    'state' => 'SP',
    'zipcode' => '01234-567',
]);
```

### Criar via sync (recomendado para APIs)

[](#criar-via-sync-recomendado-para-apis)

```
// Sincroniza automaticamente a partir do request
$client->syncAddress($request->all());

// Com array manual
$client->syncAddress([
    'person' => [
        'name' => 'João',
        'address' => [
            'street' => 'Rua Principal',
            'number' => '100',
            'city' => 'São Paulo',
            'state' => 'SP',
            'zipcode' => '01000-000'
        ]
    ]
]);
```

### Adicionar endereço de cobrança

[](#adicionar-endereço-de-cobrança)

```
// Manual
$client->addressBilling()->create([
    'street' => 'Rua da Cobrança',
    'number' => '789',
    'city' => 'Ribeirão Preto',
    'state' => 'SP',
    'zipcode' => '14000-000',
]);

// Via sync (suporta múltiplos)
$client->syncAddressBilling([
    'address_billing' => [
        ['street' => 'Rua A', 'number' => '1'],
        ['street' => 'Rua B', 'number' => '2'],
    ]
]);
```

### Adicionar endereço de entrega

[](#adicionar-endereço-de-entrega)

```
// Manual
$client->addressDelivery()->create([
    'street' => 'Av. das Entregas',
    'number' => '456',
    'city' => 'Campinas',
    'state' => 'SP',
    'zipcode' => '13000-000',
]);

// Via sync (suporta múltiplos)
$client->syncAddressDelivery([
    'address_delivery' => [
        ['street' => 'Av. A', 'number' => '100'],
        ['street' => 'Av. B', 'number' => '200'],
    ]
]);
```

### Definir endereço principal (default)

[](#definir-endereço-principal-default)

```
$address = $client->addressBilling()->create([...]);
$address->setAsDefault();

// Ou buscar o endereço padrão
$defaultBilling = $client->billingAddressDefault();
$defaultDelivery = $client->deliveryAddressDefault();
$defaultAddress = $client->address;  // Relação morphOne
```

---

📊 Histórico de Uso
------------------

[](#-histórico-de-uso)

Rastreie quantas vezes cada endereço foi utilizado:

```
// Registrar uso de um endereço
$address->incrementUsage();
$address->incrementUsage('delivery', ['order_id' => 123]);

// Ver contador
$address->usage_count;      // 15
$address->last_used_at;     // 2025-04-27 14:30:00

// Endereços mais usados
Address::mostUsed(10)->get();
$client->mostUsedBillingAddresses(5);
$client->mostUsedDeliveryAddress(); // O mais usado
$client->mostUsedBillingAddress();  // O mais usado

// Scopes úteis
Address::mostUsed()->get();           // Ordenado por uso
Address::recentlyUsed(30)->get();    // Usados nos últimos 30 dias
Address::neverUsed()->get();          // Nunca usados
Address::usedMoreThan(10)->get();     // Mais de 10 vezes

// Logs detalhados
$address->usageLogs()->get();
$address->usageLogs()->byAction('delivery')->get();
$address->usageLogs()->lastDays(7)->get();
```

🔧 Sincronizando Endereços
-------------------------

[](#-sincronizando-endereços)

Os métodos `sync*` buscam automaticamente o endereço nos dados, suportando múltiplos formatos de payload:

### Endereço Padrão (syncAddress)

[](#endereço-padrão-syncaddress)

```
$client->syncAddress($data);  // Busca em 'address' ou 'person.address'
```

**Payloads suportados:**

```
// Formato 1: person.address
{
  "person": {
    "name": "João",
    "address": { "street": "Rua Principal", "number": "100" }
  }
}

// Formato 2: address direto
{
  "address": { "street": "Rua Principal", "number": "100" }
}

// Formato 3: array do endereço diretamente
{ "street": "Rua Principal", "number": "100" }
```

### Endereço de Cobrança (syncAddressBilling)

[](#endereço-de-cobrança-syncaddressbilling)

```
$client->syncAddressBilling($data);  // Busca em 'address_billing' ou 'person.address_billing'
```

Aceita múltiplos endereços:

```
{
  "person": {
    "address_billing": [
      { "street": "Rua da Fatura", "number": "200" },
      { "street": "Rua Secundária", "number": "300" }
    ]
  }
}
```

### Endereço de Entrega (syncAddressDelivery)

[](#endereço-de-entrega-syncaddressdelivery)

```
$client->syncAddressDelivery($data);  // Busca em 'address_delivery' ou 'person.address_delivery'
```

**Exemplo completo no Controller:**

```
public function update(Request $request)
{
    $client = $request->user();
    $data = $request->validated();

    // Atualiza dados básicos
    $client->update($data['person']);

    // Sincroniza endereços (busca automaticamente nos lugares certos)
    $client->syncAddress($data);
    $client->syncAddressBilling($data);
    $client->syncAddressDelivery($data);

    // Recarrega relacionamentos para retornar na resposta
    $client->load(['address', 'addressBilling', 'addressDelivery']);

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

---

🔍 Scopes de Consulta
--------------------

[](#-scopes-de-consulta)

O pacote inclui diversos scopes para facilitar consultas:

```
// Buscar por estado
Address::byState('SP')->get();

// Buscar por cidade
Address::byCity('São Paulo')->get();

// Buscar por CEP
Address::byZipCode('01310-100')->first();

// Buscar por país
Address::byCountry('BR')->get();

// Buscar por bairro
Address::byDistrict('Centro')->get();

// Combinar scopes
Address::byState('SP')->byCity('São Paulo')->byDistrict('Jardins')->get();

// Buscar endereços padrão
Address::default()->get();
```

---

📝 Histórico de Alterações
-------------------------

[](#-histórico-de-alterações)

Todas as alterações em endereços são automaticamente registradas:

```
// Ver histórico de um endereço
$history = $address->history()->get();

// Última alteração
$latest = $address->latestHistory();

// Filtrar por tipo de ação
$createdEntries = $address->history()->created()->get();
$updatedEntries = $address->history()->updated()->get();
$deletedEntries = $address->history()->deleted()->get();

// Ver mudanças específicas
foreach ($history as $entry) {
    echo $entry->description; // "Endereço atualizado"
    print_r($entry->changes);   // ['city' => ['old' => 'SP', 'new' => 'RJ']]
}
```

O histórico inclui:

- **Ação**: created, updated, deleted, restored
- **Valores antigos e novos**
- **IP e User Agent** do usuário
- **ID do usuário** que fez a alteração
- **Data/hora** da alteração

---

📋 Campos do Endereço
--------------------

[](#-campos-do-endereço)

Campos disponíveis para todos os tipos de endereço:

CampoTipoObrigatórioDescrição`zip_code`stringSimCEP`country`stringSimPaís (ex: BRA)`state`stringSimEstado/Província`city`stringSimCidade`district`stringSimBairro`address`stringSimLogradouro`number`stringSimNúmero`complement`stringNãoComplemento**Nota:** Campos vazios ou nulos são automaticamente filtrados pelo método `sync*`.

---

🤝 Como Contribuir
-----------------

[](#-como-contribuir)

Contribuições são super bem-vindas! Para colaborar:

1. Faça um fork do repositório
2. Crie uma branch com sua feature (`feature/nome-da-feature`)
3. Faça o commit das suas alterações
4. Envie um Pull Request

---

📄 Licença
---------

[](#-licença)

Este projeto é licenciado sob a licença MIT. Consulte o arquivo [LICENSE](LICENSE) para mais detalhes.

---

💡 Autor
-------

[](#-autor)

Desenvolvido com 💙 por [Rise Tech](https://risetech.com.br)

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance94

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~17 days

Recently: every ~8 days

Total

11

Last Release

25d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/160299136?v=4)[Rise Tech](/maintainers/risetechapps)[@risetechapps](https://github.com/risetechapps)

---

Top Contributors

[![risetechapps](https://avatars.githubusercontent.com/u/160299136?v=4)](https://github.com/risetechapps "risetechapps (100 commits)")

---

Tags

addressrisetechapps

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/risetechapps-address-for-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/risetechapps-address-for-laravel/health.svg)](https://phpackages.com/packages/risetechapps-address-for-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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