Download the PHP package sierratecnologia/finder without Composer

SierraTecnologia Finder

SierraTecnologia Finder Various functionality, and basic controller included out-of-the-box.

📚 Índice

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

🎯 Introdução

O que é o Finder

O Finder é um pacote Laravel avançado desenvolvido pela SierraTecnologia para gerenciar, otimizar e executar processos de busca, indexação e descoberta de informações em sistemas empresariais. Ele fornece uma camada de abstração poderosa para trabalhar com diferentes fontes de dados, permitindo consultas inteligentes, filtros dinâmicos, ranking de resultados e integração com múltiplos mecanismos de busca.

Objetivo do Projeto

O Finder foi projetado para:

• Centralizar a lógica de busca em aplicações Laravel complexas
• Abstrair diferentes fontes de dados (Eloquent, APIs externas, sistemas de arquivos, etc.)
• Facilitar a indexação automatizada de conteúdo e documentos
• Prover ferramentas de Spider/Crawler para descoberta de informações
• Gerenciar rastreamento e análise de arquivos, diretórios e URLs
• Integrar-se perfeitamente com outros módulos do ecossistema SierraTecnologia

Benefícios e Diferenciais

• ✅ Busca Unificada: Interface consistente para múltiplas fontes de dados
• ✅ Spider Integrado: Rastreamento inteligente de arquivos, diretórios e conteúdo web
• ✅ Extensível: Arquitetura baseada em contratos e pipelines
• ✅ Performance: Cache e otimizações integradas
• ✅ Observabilidade: Logging e métricas detalhadas
• ✅ Laravel Native: Integração completa com Service Providers, Facades e Artisan Commands

Contexto no Ecossistema SierraTecnologia

O Finder faz parte do ecossistema SierraTecnologia / Rica Soluções, trabalhando em conjunto com outros módulos:

• Stalker: Monitoramento e rastreamento
• Casa: Gerenciamento de ambiente
• Operador: Operações e tarefas automatizadas
• Integrations: Integrações com serviços externos
• MediaManager: Gerenciamento de mídia e arquivos

📦 Instalação

Requisitos Mínimos

• PHP: 8.2 ou superior
• Laravel: 10.x ou 11.x
• Extensões PHP: mbstring, xml, dom, curl, gd, zip, pdo

Instalação via Composer

Publicação dos Arquivos de Configuração

Publique os arquivos de configuração, views e assets:

Registro Automático do Service Provider

O Finder utiliza descoberta automática de pacotes do Laravel. O FinderProvider será registrado automaticamente através da seção extra.laravel.providers no composer.json:

Configuração

O arquivo de configuração principal está em config/sitec/finder.php. Após publicar, você pode configurar:

🏗️ Arquitetura e Estrutura Interna

Estrutura de Diretórios

Namespaces e Padrões

O Finder utiliza o namespace base Finder\ mapeado para o diretório src/:

Padrões de Design

1. Repository Pattern

O Finder abstrai o acesso a dados através de services e repositories:

2. Search Abstraction

Camada de abstração para diferentes mecanismos de busca:

3. Spider/Crawler Pattern

Sistema de rastreamento com extensões e identificadores:

4. Pipeline Pattern

Processamento de dados através de pipelines:

Comunicação Entre Camadas

Convenções e Boas Práticas

1. Naming Conventions:

   • Controllers: {Resource}Controller
   • Actions: {Resource}{Action}Action (ex: PostCreateAction)
   • Services: {Resource}Service
   • Commands: {Resource}{Action} (ex: PhotosPrepare)

2. Dependency Injection:

   • Sempre use injeção de dependência nos construtores
   • Prefira contratos (interfaces) em vez de implementações concretas
3. Logging:
   • Canal específico: sitec-finder
   • Logs em storage/logs/sitec-finder.log

🚀 Principais Funcionalidades

1. Busca e Filtragem Avançada

O Finder fornece uma camada unificada para busca em diferentes fontes:

2. Sistema de Spider/Crawler

Rastreamento de Diretórios

Extensões do Spider

O Spider suporta diferentes tipos de extensões para processamento especializado:

• Identificadores: Identificam tipos de arquivos/conteúdo
• Groups: Agrupam resultados por critérios
• Extensions: Processadores customizados
• Metrics: Coletam métricas durante o rastreamento

3. Indexação Automática

4. Comandos Console

Preparação de Dados

Sincronização

Verificação

5. API HTTP

O Finder fornece actions prontas para uso em APIs:

Actions disponíveis:

• PostCreateAction, PostGetByIdAction, PostUpdateByIdAction, PostDeleteByIdAction
• PhotoCreateAction, PhotoUpdateByIdAction, PhotoDeleteByIdAction
• UserCreateAction, UserGetByIdAction, UserUpdateByIdAction, UserDeleteByIdAction
• E muitas outras...

6. Entities e Abstração

💻 Uso Prático

Exemplo 1: Busca com Eloquent e Filtros Dinâmicos

Exemplo 2: Spider Customizado

Exemplo 3: Integração com Cache

Boas Práticas de Performance

1. Use Cache Agressivamente:

2. Otimize Queries com Eager Loading:

3. Use Chunks para Grandes Volumes:

🔗 Integração com o Ecossistema SierraTecnologia

Módulos Integrados

O Finder se integra nativamente com:

1. Stalker

Monitoramento e rastreamento de atividades:

2. Casa

Gerenciamento de ambiente e configuração:

3. Operador

Execução de tarefas e operações:

4. MediaManager

Gerenciamento de arquivos e mídia:

Padrões de Testes

O Finder segue os padrões de teste do ecossistema:

Versionamento

O Finder segue Semantic Versioning 2.0.0:

• MAJOR: Mudanças incompatíveis na API
• MINOR: Novas funcionalidades compatíveis
• PATCH: Correções de bugs

🔧 Extensão e Customização

Adicionar Novos Adaptadores

Para criar um novo adaptador de busca:

Registre o adaptador no Service Provider:

Personalizar Indexação

Criar Extensões do Spider

Boas Práticas para Evitar Quebras

1. Use Contratos em vez de Implementações:

2. Versione suas Extensões:

3. Documente suas Customizações:

📊 Exemplos Reais

Caso de Uso 1: E-commerce com Alto Volume

Cenário: Loja online com 100.000+ produtos

Ganhos:

• ⚡ 80% redução no tempo de resposta (cache)
• 📈 Capacidade de lidar com 10x mais consultas simultâneas
• 💰 Redução de 60% nos custos de servidor

Caso de Uso 2: Sistema de Gestão Documental

Cenário: Indexação de 50.000+ documentos PDF

Ganhos:

• 🔍 Busca instantânea em milhares de documentos
• 📁 Organização automática por tipo/categoria
• 🔒 Controle de versão e duplicatas

Caso de Uso 3: Plataforma de Conteúdo

Cenário: Portal de notícias com múltiplas fontes

Ganhos:

• 📰 Agregação de múltiplas fontes em tempo real
• 🎯 Personalização por usuário
• 📊 Analytics e métricas integradas

🤝 Guia de Contribuição

Como Contribuir

1. Fork o repositório

2. Clone sua fork:

3. Crie uma branch para sua feature:

4. Faça suas alterações e commit:

5. Push para sua fork:

6. Abra um Pull Request

Padrões de Commits

Seguimos o Conventional Commits:

Padrões de Branches

• main / master: Produção
• develop: Desenvolvimento
• feature/*: Novas funcionalidades
• fix/*: Correções de bugs
• hotfix/*: Correções urgentes
• release/*: Preparação de releases

Execução Local das Ferramentas

PHPUnit

PHPCS (PSR-12)

PHPStan (Nível 8)

PHPMD

Psalm

CI/CD

O projeto utiliza GitHub Actions para CI/CD. Todos os PRs passam por:

• ✅ Testes automatizados (PHPUnit)
• ✅ Análise estática (PHPStan nível 8)
• ✅ Verificação de estilo (PHPCS PSR-12)
• ✅ Análise de qualidade (PHPMD)
• ✅ Security check

Política de Licença

Este projeto está licenciado sob a MIT License.

Contato da Equipe Técnica

• Email: [email protected]
• Chat: Slack da SierraTecnologia
• Twitter: @sierratecnologia
• Issues: GitHub Issues

Changelog

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

Support

The following support channels are available at your fingertips:

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

Contributing & Protocols

Thank you for considering contributing to this project! The contribution guide can be found in CONTRIBUTING.md.

Bug reports, feature requests, and pull requests are very welcome.

• Versioning
• Pull Requests
• Coding Standards
• Feature Requests
• Git Flow

Security Vulnerabilities

If you discover a security vulnerability within this project, please send an e-mail to [email protected]. 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-2025 SierraTecnologia, Some rights reserved.