PHPackages                             sierratecnologia/locaravel - 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. sierratecnologia/locaravel

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

sierratecnologia/locaravel
==========================

Recursos para GeoLocalização

0.4.4(2y ago)14366MITPHPPHP ^7.2|^8.0CI failing

Since Jul 23Pushed 6mo agoCompare

[ Source](https://github.com/SierraTecnologia/Locaravel)[ Packagist](https://packagist.org/packages/sierratecnologia/locaravel)[ Docs](https://sierratecnologia.com/packages/locaravel/)[ Fund](https://ricasolucoes.com.br/open-source/support-us)[ GitHub Sponsors](https://github.com/ricasolucoes)[ RSS](/packages/sierratecnologia-locaravel/feed)WikiDiscussions stable Synced 2d ago

READMEChangelogDependencies (17)Versions (18)Used By (6)

Locaravel
=========

[](#locaravel)

**Locaravel** - A remarkably magical tools for geolocation

[![Build Status](https://camo.githubusercontent.com/9eccd3258a53e2c2e64eab8655c7531f7b6fe6652f2b34ed195bc2b462b4ff99/68747470733a2f2f7472617669732d63692e6f72672f5369657272615465636e6f6c6f6769612f4c6f6361726176656c2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/SierraTecnologia/Locaravel)[![Maintainability](https://camo.githubusercontent.com/5e194657080f8a2c16f3ddb7b05b7594b00e9c1eecec2c8a42bc4890a8b745fe/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f38633030613034366665633332643862386163372f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/SierraTecnologia/Locaravel/maintainability)[![Packagist](https://camo.githubusercontent.com/82d298ffee82455d772e675516b2ed75dcc6d8969404a305740d8557340fea27/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7369657272617465636e6f6c6f6769612f6c6f6361726176656c2e737667)](https://packagist.org/packages/sierratecnologia/locaravel)[![license](https://camo.githubusercontent.com/850eae1099d2b05f53383473d7cd51f9bc1ab09b7d0d9e5122f1dd930efdcc6d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d6173686170652f6170697374617475732e737667)](https://packagist.org/packages/sierratecnologia/locaravel)[![Tests](https://github.com/SierraTecnologia/Locaravel/workflows/Tests/badge.svg)](https://github.com/SierraTecnologia/Locaravel/actions)[![Psalm](https://github.com/SierraTecnologia/Locaravel/workflows/Psalm/badge.svg)](https://github.com/SierraTecnologia/Locaravel/actions)[![Code Style](https://github.com/SierraTecnologia/Locaravel/workflows/Check%20&%20fix%20styling/badge.svg)](https://github.com/SierraTecnologia/Locaravel/actions)

---

📚 Índice
========

[](#-índice)

- [Introdução](#-introdu%C3%A7%C3%A3o)
- [Instalação](#-instala%C3%A7%C3%A3o)
- [Arquitetura e Estrutura Interna](#-arquitetura-e-estrutura-interna)
- [Principais Componentes](#-principais-componentes)
- [Uso Prático](#-uso-pr%C3%A1tico)
- [Integração com o Ecossistema SierraTecnologia](#-integra%C3%A7%C3%A3o-com-o-ecossistema-sierratecnologia)
- [Extensão e Customização](#-extens%C3%A3o-e-customiza%C3%A7%C3%A3o)
- [Exemplos Reais](#-exemplos-reais)
- [Guia de Contribuição](#-guia-de-contribui%C3%A7%C3%A3o)
- [Changelog](#changelog)
- [Suporte](#suporte)

---

🚀 Introdução
------------

[](#-introdução)

### O que é o Locaravel?

[](#o-que-é-o-locaravel)

O **Locaravel** é um pacote Laravel robusto e modular desenvolvido pela **SierraTecnologia** para fornecer recursos avançados de **geolocalização**, **gestão de endereços** e **manipulação de dados geoespaciais** em aplicações PHP/Laravel.

### Motivação e Objetivos

[](#motivação-e-objetivos)

No ecossistema de soluções corporativas da SierraTecnologia, a necessidade de padronizar e abstrair funcionalidades relacionadas a localização geográfica surgiu de forma recorrente em diversos projetos. O Locaravel foi criado para:

- **Padronizar** a gestão de endereços, coordenadas e dados geográficos
- **Abstrair** a complexidade de trabalhar com PostGIS e geometrias espaciais
- **Reutilizar** componentes testados e validados entre múltiplos projetos
- **Integrar** serviços externos (Correios, Google Maps, etc.) de forma consistente
- **Facilitar** a internacionalização com suporte a 32+ idiomas

### Benefícios de Uso

[](#benefícios-de-uso)

✅ **Padronização:** Estruturas consistentes de endereços e localizações ✅ **PostGIS Integration:** Suporte nativo a tipos geométricos (Point, Polygon, LineString, etc.) ✅ **Eloquent Extensions:** Query builders customizados para consultas geoespaciais ✅ **Testes Abrangentes:** 20+ testes unitários e de integração ✅ **Internacionalização:** Traduções em 32 idiomas ✅ **Integração Rica:** Conecta-se naturalmente com outros pacotes SierraTecnologia

### Como se Encaixa na Filosofia SierraTecnologia / Rica Soluções

[](#como-se-encaixa-na-filosofia-sierratecnologia--rica-soluções)

A SierraTecnologia adota uma **arquitetura modular baseada em pacotes Laravel**, onde cada pacote resolve um domínio específico do negócio. O Locaravel é a peça fundamental para:

- **Sistemas de Delivery** (rastreamento de rotas, cálculo de distâncias)
- **Gestão Imobiliária** (endereços hierárquicos: condomínios, blocos, apartamentos)
- **Turismo** (hotéis, lugares, pontos de interesse)
- **Logística** (otimização de rotas, geocodificação de endereços)

---

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

[](#-instalação)

### Requisitos

[](#requisitos)

RequisitoVersão Mínima**PHP**7.2+ ou 8.0+**Laravel**7.0+ ou 8.0+**PostgreSQL**9.5+ (com extensão PostGIS)**Composer**2.0+### Passo 1: Instalação via Composer

[](#passo-1-instalação-via-composer)

```
composer require sierratecnologia/locaravel
```

### Passo 2: Publicação de Configurações

[](#passo-2-publicação-de-configurações)

```
php artisan vendor:publish --provider="Locaravel\LocaravelProvider"
```

Este comando publicará:

- Arquivo de configuração: `config/sitec-locaravel.php`
- Migrations para as tabelas de localização
- Arquivos de tradução (opcional)

### Passo 3: Configuração do Banco de Dados

[](#passo-3-configuração-do-banco-de-dados)

O Locaravel requer **PostgreSQL com a extensão PostGIS**. Configure seu `.env`:

```
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=seu_banco
DB_USERNAME=seu_usuario
DB_PASSWORD=sua_senha
```

Habilite a extensão PostGIS no PostgreSQL:

```
CREATE EXTENSION IF NOT EXISTS postgis;
```

### Passo 4: Executar Migrations

[](#passo-4-executar-migrations)

```
php artisan migrate
```

Isso criará as tabelas:

- `localizations` - Armazena coordenadas geográficas
- `addresses` - Estrutura hierárquica de endereços
- `address_types` - Tipos de endereços (Rua, Casa, Apartamento, etc.)
- `places` - Lugares e pontos de interesse
- `hotels`, `aparts` - Modelos específicos de turismo

### Passo 5: Registro do Service Provider (Opcional)

[](#passo-5-registro-do-service-provider-opcional)

Se você desabilitou o auto-discovery do Laravel, adicione manualmente em `config/app.php`:

```
'providers' => [
    // ...
    Locaravel\LocaravelProvider::class,
],
```

---

🏛️ Arquitetura e Estrutura Interna
----------------------------------

[](#️-arquitetura-e-estrutura-interna)

### Estrutura de Diretórios

[](#estrutura-de-diretórios)

```
src/
├── Builders/              # Query builders customizados
├── Concerns/              # Traits reutilizáveis
├── Connectors/            # Factories de conexão PostGIS
├── Contracts/             # Interfaces de contratos
├── Eloquent/              # Extensões do Eloquent ORM
├── Entities/              # DTOs (Data Transfer Objects)
├── Exceptions/            # Exceções customizadas
├── Facades/               # Facades Laravel
├── Geometries/            # Classes de geometrias (Point, Polygon, etc.)
├── Http/
│   ├── Controllers/       # Controllers HTTP
│   └── Resources/         # API Resources
├── Managers/              # Gerenciadores de lógica de negócio
├── Models/                # Modelos Eloquent
├── Repositories/          # Camada de acesso a dados
├── Rules/                 # Regras de validação customizadas
├── Saas/                  # Integrações com serviços externos
├── Schema/                # Extensões do Schema Builder
├── Services/              # Camada de serviços
├── Traits/                # Traits para modelos
├── Util/                  # Classes utilitárias
├── ValueObjects/          # Objetos de valor imutáveis
└── LocaravelProvider.php  # Service Provider principal

```

### Padrões Arquiteturais

[](#padrões-arquiteturais)

O Locaravel adota os seguintes padrões:

#### 1. **Layered Architecture (Arquitetura em Camadas)**

[](#1-layered-architecture-arquitetura-em-camadas)

```
┌─────────────────────────────────────┐
│  HTTP Layer (Controllers/Resources) │
├─────────────────────────────────────┤
│  Services Layer (Business Logic)    │
├─────────────────────────────────────┤
│  Repository Layer (Data Access)     │
├─────────────────────────────────────┤
│  Models Layer (Eloquent ORM)        │
├─────────────────────────────────────┤
│  Database (PostgreSQL + PostGIS)    │
└─────────────────────────────────────┘

```

#### 2. **Repository Pattern**

[](#2-repository-pattern)

Abstração do acesso a dados para facilitar testes e manutenção:

```
PlaceRepository → acessa → Place Model
TravelRepository → acessa → Travel Models
```

#### 3. **Service Pattern**

[](#3-service-pattern)

Encapsulamento da lógica de negócio:

```
LocaravelService    # Serviço principal
AddressService      # Gestão de endereços
PlaceService        # Gestão de lugares
MapsService         # Integração com mapas
```

#### 4. **Value Objects (Imutáveis)**

[](#4-value-objects-imutáveis)

```
Coordinates    # Latitude + Longitude imutável
Latitude       # Validação automática (-90 a 90)
Longitude      # Validação automática (-180 a 180)
```

#### 5. **Traits & Concerns**

[](#5-traits--concerns)

```
PostgisTrait      # Adiciona suporte PostGIS aos models
Spatial           # Consultas espaciais
ModelHasAddress   # Relacionamento polimórfico de endereços
```

### Convenções e Boas Práticas

[](#convenções-e-boas-práticas)

✅ **PSR-12:** Padrão de estilo de código ✅ **PSR-4:** Autoloading de classes ✅ **Testes Unitários:** Cobertura com PHPUnit ✅ **Análise Estática:** Psalm (nível 8 - máximo) e PHPStan (nível 8) ✅ **Documentação PHPDoc:** Todas as classes públicas documentadas

---

🔧 Principais Componentes
------------------------

[](#-principais-componentes)

### 1. Sistema de Geometrias

[](#1-sistema-de-geometrias)

O Locaravel implementa suporte completo a **WKT (Well-Known Text)** e **WKB (Well-Known Binary)** para manipulação de geometrias espaciais.

Para uma documentação completa e detalhada de todos os componentes, incluindo:

- Sistema de Geometrias (Point, Polygon, LineString, etc.)
- Modelos Eloquent com Suporte PostGIS
- Schema Builder com Tipos Espaciais
- Sistema de Endereços Hierárquicos
- Serviços de Integração Externa (Correios, Maps)
- Value Objects Imutáveis
- Regras de Validação Customizadas
- Utilitários de Distância

**Consulte o arquivo:** [`TECHNICAL_DOCS.md`](TECHNICAL_DOCS.md)

---

💻 Uso Prático
-------------

[](#-uso-prático)

### Exemplo Rápido: Criar Model com Geolocalização

[](#exemplo-rápido-criar-model-com-geolocalização)

```
use Illuminate\Database\Eloquent\Model;
use Locaravel\Eloquent\PostgisTrait;
use Locaravel\Geometries\Point;

class Restaurante extends Model
{
    use PostgisTrait;

    protected $postgisFields = [
        'location' => 'geometry'
    ];

    protected $postgisTypes = [
        'location' => Point::class
    ];
}

// Uso
$restaurante = new Restaurante();
$restaurante->nome = 'Pizza Express';
$restaurante->location = new Point(-23.5505, -46.6333); // São Paulo
$restaurante->save();
```

### Calcular Distância Entre Pontos

[](#calcular-distância-entre-pontos)

```
use Locaravel\Util\Distance;
use Locaravel\Geometries\Point;

$pontoA = new Point(-23.5505, -46.6333); // São Paulo
$pontoB = new Point(-22.9068, -43.1729); // Rio de Janeiro

$distanciaKm = Distance::haversine($pontoA, $pontoB);
echo "Distância: " . $distanciaKm . " km"; // ~357 km
```

### Buscar CEP com Correios

[](#buscar-cep-com-correios)

```
use Locaravel\Saas\CorreiosService;

$correios = new CorreiosService();
$endereco = $correios->buscarCep('01310-100');

echo $endereco['logradouro']; // Av. Paulista
echo $endereco['cidade'];     // São Paulo
```

**Para exemplos práticos completos e casos de uso detalhados, consulte:** [`TECHNICAL_DOCS.md`](TECHNICAL_DOCS.md)

---

🔗 Integração com o Ecossistema SierraTecnologia
-----------------------------------------------

[](#-integração-com-o-ecossistema-sierratecnologia)

O Locaravel faz parte de um conjunto maior de pacotes Laravel da SierraTecnologia:

PacoteDescriçãoRelação com Locaravel**Pedreiro**Modelos base e abstraçõesLocaravel herda de `Pedreiro\Model`**Crypto**Criptografia e segurançaUsado para dados sensíveis de localização**Translation**InternacionalizaçãoLocaravel usa 32+ idiomas via Translation**Arquiteto**Arquitetura e scaffoldingGera estruturas que usam Locaravel**Técnico**Ferramentas administrativasIntegra painel admin com Locaravel### Padrão de Testes e CI/CD

[](#padrão-de-testes-e-cicd)

Todos os pacotes SierraTecnologia seguem:

✅ **PHPUnit** - Testes unitários e de integração ✅ **Psalm (nível 8)** - Análise estática máxima ✅ **PHPStan (nível 8)** - Análise estática complementar ✅ **PHPCS (PSR-12)** - Padrão de código ✅ **PHPMD** - Detecção de más práticas ✅ **GitHub Actions** - CI/CD automático

---

🎨 Extensão e Customização
-------------------------

[](#-extensão-e-customização)

### Criar Novo Tipo de Geometria

[](#criar-novo-tipo-de-geometria)

```
namespace App\Geometries;

use Locaravel\Geometries\Geometry;

class Circle extends Geometry
{
    protected $center;
    protected $radius;

    public function __construct(Point $center, float $radius)
    {
        $this->center = $center;
        $this->radius = $radius;
    }

    public function toWKT(): string
    {
        return sprintf(
            'CIRCLE(%s %s, %s)',
            $this->center->getLat(),
            $this->center->getLng(),
            $this->radius
        );
    }
}
```

### Substituir Implementação Padrão

[](#substituir-implementação-padrão)

```
// No AppServiceProvider.php
use Locaravel\Contracts\AddressManager;
use App\Managers\CustomAddressManager;

public function register()
{
    $this->app->bind(AddressManager::class, CustomAddressManager::class);
}
```

**Para mais detalhes sobre extensão e customização, consulte:** [`TECHNICAL_DOCS.md`](TECHNICAL_DOCS.md)

---

📊 Exemplos Reais
----------------

[](#-exemplos-reais)

### Caso 1: Sistema de Entregas da Rica Soluções

[](#caso-1-sistema-de-entregas-da-rica-soluções)

**Problema:** Calcular tempo de entrega baseado em distância e trânsito.

**Resultado:** Redução de **70%** no código relacionado a cálculos geográficos.

### Caso 2: Portal Imobiliário Multi-inquilino

[](#caso-2-portal-imobiliário-multi-inquilino)

**Resultado:**

- **80% menos código**
- **Estrutura padronizada**
- **Testes automatizados incluídos**

### Caso 3: App de Turismo

[](#caso-3-app-de-turismo)

**Resultado:** App lançado em **60% menos tempo** que o estimado.

**Para detalhes completos dos casos de uso, consulte:** [`TECHNICAL_DOCS.md`](TECHNICAL_DOCS.md)

---

Changelog
---------

[](#changelog)

Refer to the [Changelog](CHANGELOG.md) for a full history of the project.

---

Suporte
-------

[](#suporte)

The following support channels are available at your fingertips:

- [Chat on Slack](https://bit.ly/sierratecnologia-slack)
- [Help on Email](mailto:help@sierratecnologia.com.br)
- [Follow on Twitter](https://twitter.com/sierratecnologia)

---

🤝 Guia de Contribuição
----------------------

[](#-guia-de-contribuição)

### Como Contribuir

[](#como-contribuir)

1. **Fork** o repositório
2. **Clone** seu fork: `git clone https://github.com/SEU-USUARIO/locaravel.git`
3. **Crie uma branch**: `git checkout -b feature/minha-feature`
4. **Faça suas alterações**
5. **Execute os testes**: `composer test`
6. **Execute o Psalm**: `composer psalm`
7. **Execute o PHPStan**: `phpstan analyse`
8. **Execute o PHPCS**: `phpcs --standard=PSR12 src/`
9. **Formate o código**: `composer format`
10. **Commit**: `git commit -m "feat: adiciona nova funcionalidade X"`
11. **Push**: `git push origin feature/minha-feature`
12. **Abra um Pull Request**

### Padrões de Commits

[](#padrões-de-commits)

Seguimos o **Conventional Commits**:

```
feat: nova funcionalidade
fix: correção de bug
docs: alteração de documentação
style: formatação de código
refactor: refatoração sem mudança de comportamento
test: adição ou correção de testes
chore: tarefas de manutenção

```

### Execução Local de Testes e Qualidade

[](#execução-local-de-testes-e-qualidade)

```
# Testes unitários
composer test

# Testes com cobertura
composer test-coverage

# Análise estática (Psalm)
composer psalm

# Análise estática (PHPStan)
phpstan analyse

# Verificação de estilo (PHPCS)
phpcs --standard=PSR12 src/

# Detecção de más práticas (PHPMD)
phpmd src text phpmd.xml

# Formatação automática de código
composer format
```

**Para o guia completo de contribuição, consulte:** [`TECHNICAL_DOCS.md`](TECHNICAL_DOCS.md)

---

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

[](#security-vulnerabilities)

If you discover a security vulnerability within this project, please send an e-mail to [help@sierratecnologia.com.br](help@sierratecnologia.com.br). All security vulnerabilities will be promptly addressed.

About SierraTecnologia
----------------------

[](#about-sierratecnologia)

SierraTecnologia is a software solutions startup, specialized in integrated enterprise solutions for SMEs established in Rio de Janeiro, Brazil since June 2008. We believe that our drive The Value, The Reach, and The Impact is what differentiates us and unleash the endless possibilities of our philosophy through the power of software. We like to call it Innovation At The Speed Of Life. That’s how we do our share of advancing humanity.

License
-------

[](#license)

This software is released under [The MIT License (MIT)](LICENSE).

(c) 2008-2020 SierraTecnologia, Some rights reserved.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance47

Moderate activity, may be stable

Popularity14

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 98.6% 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 ~115 days

Recently: every ~304 days

Total

12

Last Release

848d ago

PHP version history (3 changes)0.1.0PHP >=7.0

0.2.0PHP ^7.4

0.4.3PHP ^7.2|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/c0a11577f9e4f7db7533432c22786439b3155ec7bc06be9760be7260c4ce1e0d?d=identicon)[ricardosierra](/maintainers/ricardosierra)

---

Top Contributors

[![ricardosierra](https://avatars.githubusercontent.com/u/5499444?v=4)](https://github.com/ricardosierra "ricardosierra (72 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (1 commits)")

---

Tags

SierraTecnologialocaravel

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sierratecnologia-locaravel/health.svg)

```
[![Health](https://phpackages.com/badges/sierratecnologia-locaravel/health.svg)](https://phpackages.com/packages/sierratecnologia-locaravel)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[orchestra/canvas

Code Generators for Laravel Applications and Packages

21017.2M158](/packages/orchestra-canvas)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[kirschbaum-development/commentions

A package to allow you to create comments, tag users and more

12369.2k](/packages/kirschbaum-development-commentions)[aedart/athenaeum

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

245.2k](/packages/aedart-athenaeum)[bjuppa/laravel-blog

Add blog functionality to your Laravel project

483.3k2](/packages/bjuppa-laravel-blog)

PHPackages © 2026

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