README

Locaravel - A remarkably magical tools for geolocation

📚 Índice

Introdução
Instalação
Arquitetura e Estrutura Interna
Principais Componentes
Uso Prático
Integração com o Ecossistema SierraTecnologia
Extensão e Customização
Exemplos Reais
Guia de Contribuição
Changelog
Suporte

🚀 Introdução

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

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

✅ 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

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

Requisitos

Requisito	Versã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

composer require sierratecnologia/locaravel

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

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

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)

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

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

🏛️ Arquitetura e Estrutura Interna

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

O Locaravel adota os seguintes padrões:

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

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

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

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)

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

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

✅ 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

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

💻 Uso Prático

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

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

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

🔗 Integração com o Ecossistema SierraTecnologia

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

Pacote	Descrição	Relação com Locaravel
Pedreiro	Modelos base e abstrações	Locaravel herda de `Pedreiro\Model`
Crypto	Criptografia e segurança	Usado para dados sensíveis de localização
Translation	Internacionalização	Locaravel usa 32+ idiomas via Translation
Arquiteto	Arquitetura e scaffolding	Gera estruturas que usam Locaravel
Técnico	Ferramentas administrativas	Integra painel admin com Locaravel

Padrão de Testes e CI/CD

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

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

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

📊 Exemplos Reais

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

Resultado:

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

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

Changelog

Refer to the Changelog for a full history of the project.

Suporte

The following support channels are available at your fingertips:

🤝 Guia de Contribuição

Como Contribuir

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

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

# 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

Security Vulnerabilities

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

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

This software is released under The MIT License (MIT).

sierratecnologia / locaravel

Maintainers

Details