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

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:

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:

• Chat on Slack
• Help on Email
• Follow on Twitter

🤝 Guia de Contribuição

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

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).

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