Download the PHP package sierratecnologia/muleta without Composer

SierraTecnologia Muleta

SierraTecnologia common Muleta helpers, contracts, and traits required by various SierraTecnologia packages. Validator functionality, and basic controller included out-of-the-box.

Nota: Este pacote é uma biblioteca de suporte para outros pacotes SierraTecnologia, que pode não ser útil por si só, mas contém funcionalidades genéricas complementares e pode não respeitar SemVer em releases iniciais.

📚 Í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
• Testes e Qualidade de Código

🎯 Introdução

O que é Muleta

Muleta é a biblioteca fundacional do ecossistema SierraTecnologia - um conjunto abrangente de contratos, traits, helpers e utilitários que servem como base para todos os pacotes Laravel da SierraTecnologia. O nome "Muleta" (muleta em português) reflete perfeitamente seu propósito: fornecer suporte essencial e estrutural para o desenvolvimento ágil e padronizado de aplicações empresariais.

Objetivo e Filosofia do Projeto

A filosofia do Muleta é baseada em três pilares fundamentais:

1. Reutilização: Componentes compartilhados que eliminam duplicação de código entre pacotes
2. Padronização: Contratos e padrões arquiteturais consistentes em todo o ecossistema
3. Produtividade: Helpers e traits que aceleram o desenvolvimento de funcionalidades comuns

Benefícios de Uso

• Redução de Código Boilerplate: Traits composíveis para funcionalidades comuns (tags, slugs, imagens, traduções)
• Validação Estendida: Validadores customizados prontos para uso (unique_with, file, video)
• Padrões Arquiteturais: Implementação completa de Repository Pattern, API Controllers e Resources
• Análise de Banco de Dados: Módulo Analysator para inspeção profunda de estruturas de BD
• Helpers Globais: Mais de 30 funções auxiliares disponíveis globalmente
• Contratos Bem Definidos: Interfaces para garantir consistência (Arrayable, Outputable, Sortable)

Integração com o Ecossistema SierraTecnologia

Muleta é a camada de fundação que suporta pacotes como:

• Transmissor: Sistema de comunicação e notificações
• Sanitizer: Limpeza e validação de dados
• MediaManager: Gerenciamento de mídias e arquivos
• SafeMaps: Sistemas de mapas e geolocalização
• Architect: Ferramentas de arquitetura de software

Todos compartilham os mesmos traits, contratos e padrões definidos pelo Muleta, garantindo coesão arquitetural.

📦 Instalação

Requisitos Mínimos

• PHP: 8.2 ou superior
• Laravel: 10.x ou 11.x
• Composer: 2.x

Instalação via Composer

Dependências Sugeridas

Para funcionalidade completa, considere instalar:

Publicação de Configurações

O Muleta é projetado para funcionar sem publicação de assets, mas se necessário:

Registro de Service Provider

O Service Provider é auto-descoberto no Laravel 5.5+. Para versões anteriores, adicione manualmente em config/app.php:

🏗️ Arquitetura e Estrutura Interna

Estrutura de Diretórios

Namespaces Principais

Padrões Arquiteturais Adotados

1. Repository Pattern

2. Trait Composition Pattern

Ao invés de herança profunda, Muleta favorece composição via traits:

3. Service Layer Pattern

4. API Resource Pattern

Convenções da SierraTecnologia

1. Nomenclatura em Português: Classes e métodos principais em PT-BR
2. PSR-12 Compliance: Padrão de código PSR-12
3. Type Hints Rigorosos: PHP 8.2+ com tipos estritos
4. Documentação Inline: PHPDoc completo em todos os métodos públicos
5. Testes Unitários: Cobertura de código > 70%

🔧 Principais Componentes

1. Contracts (Interfaces)

Arrayable

Garante que objetos possam ser convertidos em arrays:

Uso: Models, DTOs, Value Objects que precisam serialização.

Outputable

Define objetos que podem gerar saída formatada:

Uso: Reports, exportações, geradores de arquivos.

Sortable

Implementa ordenação customizada:

2. Traits Essenciais

HasSlug

Gera slugs URL-friendly automaticamente:

Localização: src/Traits/Models/HasSlug.php

HasTags

Sistema completo de tags com relacionamento polimórfico:

Localização: src/Traits/Models/HasTags.php

HasImages

Gerenciamento de múltiplas imagens associadas:

Localização: src/Traits/Models/HasImages.php

HasTranslations

Suporte multi-idioma nativo:

Localização: src/Traits/Models/HasTranslations.php

ValidatingTrait

Validação automática no save/update:

Localização: src/Traits/Models/ValidatingTrait.php

GetSetTrait

Geração automática de getters/setters via anotações:

Localização: src/Traits/Coder/GetSetTrait.php

3. Validadores Customizados

O Service Provider registra validadores estendidos:

unique_with

Valida unicidade combinando múltiplos campos:

file

Validação avançada de arquivos:

video

Validação específica para vídeos:

Localização: src/Library/Laravel/Validator.php

4. Helpers Globais

intend()

Retorna redirect response com suporte a múltiplos métodos:

Localização: utils/funcs/helpers.php

mimetypes()

Retorna array de mimetypes válidos:

timezones()

Lista de timezones formatados:

lower_case() / upper_case()

Conversão de caso com suporte UTF-8:

5. Módulo Analysator

Sistema sofisticado de análise de banco de dados:

Funcionalidades:

• Análise de índices e performance
• Detecção de relacionamentos implícitos
• Sugestões de otimização
• Mapeamento de dependências entre tabelas

Localização: src/Modules/Analysator/

💡 Uso Prático

Exemplo Completo: Sistema de Blog

Controller usando Repository Pattern:

Resource para API:

Boas Práticas

1. Use Traits Moderadamente: Não adicione todos os traits a um model, apenas os necessários
2. Valide Dados: Sempre use ValidatingTrait ou Form Requests
3. Repository para Lógica Complexa: Mantenha controllers magros
4. Type Hints: Aproveite PHP 8.2+ para type safety
5. Testes: Escreva testes para lógica customizada que usa Muleta

🔗 Integração com o Ecossistema SierraTecnologia

Arquitetura do Ecossistema

Padrões de Versionamento

• Semantic Versioning: Major.Minor.Patch (com exceções em early releases)
• Branch Strategy:
  • main: Produção estável
  • develop: Desenvolvimento ativo
  • feature/*: Novas funcionalidades
  • hotfix/*: Correções urgentes

Testes e CI/CD

O Muleta implementa CI/CD rigoroso:

Todos os pacotes SierraTecnologia que dependem de Muleta devem:

1. Usar as mesmas ferramentas de qualidade
2. Seguir os mesmos padrões de código
3. Implementar testes com cobertura mínima de 70%

Como Diferentes Equipes Usam Muleta

Equipe de Produto (CMS)

Equipe de Infraestrutura (DevOps)

Equipe de API (Backend)

🎨 Extensão e Customização

Como Estender Muleta

1. Criando Traits Customizados

2. Extendendo Repositories

3. Criando Validadores Customizados

Boas Práticas para Manter Compatibilidade

1. Não Modifique Diretamente: Nunca altere código do Muleta, sempre estenda
2. Use Composition Over Inheritance: Prefira traits a herança de classes
3. Documente Extensões: Mantenha documentação clara de customizações
4. Testes de Integração: Teste compatibilidade após updates do Muleta
5. Namespace Separado: Mantenha extensões em namespace próprio (App\Extensions\Muleta)

Como Adicionar Novos Helpers

Registre em composer.json:

📊 Exemplos Reais

Caso 1: E-commerce com Múltiplos Idiomas

Desafio: Sistema de e-commerce que precisa suportar PT-BR, EN e ES com produtos taggeados e imagens múltiplas.

Solução com Muleta:

Resultado: Implementação completa em < 50 linhas vs 300+ sem Muleta.

Caso 2: Sistema de Análise de Performance de BD

Desafio: Identificar gargalos em banco de dados legado de ERP com 200+ tabelas.

Solução com Analysator:

Resultado: Identificação automática de 47 índices faltantes, 12 duplicados, reduzindo tempo de queries em 65%.

Caso 3: API RESTful Multi-tenant

Desafio: API para SaaS multi-tenant com isolamento de dados e validação rigorosa.

Antes (sem Muleta):

• 15+ arquivos duplicados entre controllers
• Validação manual em cada endpoint
• Sem padronização de responses

Depois (com Muleta):

Ganhos:

• Código reduzido: 70% menos código boilerplate
• Padronização: Todas as respostas seguem mesmo formato
• Manutenção: Mudanças centralizadas no Muleta
• Testes: Cobertura aumentou de 40% para 85%

🧪 Testes e Qualidade de Código

Ferramentas de Qualidade Configuradas

O Muleta utiliza as melhores ferramentas de qualidade de código PHP:

PHPStan (Nível 8)

Análise estática mais rigorosa:

Configuração: phpstan.neon

PHPCS (PSR-12)

Verificação de padrões de código:

Configuração: phpcs.xml

Psalm

Análise de tipos e bugs:

Configuração: psalm.xml

PHPUnit

Testes unitários e de integração:

Configuração: phpunit.xml

CI/CD com GitHub Actions

Todos os PRs e commits passam por:

1. Tests (PHP 8.2 e 8.3, Laravel 10 e 11)
2. PHPStan (nível 8, sem erros)
3. PHPCS (PSR-12 compliance)
4. Psalm (análise de tipos)

Workflows: .github/workflows/run-tests.yml e .github/workflows/code-quality.yml

📄 Changelog

Consulte o CHANGELOG.md para histórico completo de versões e mudanças.

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 Alexandria, Egypt since June 2016. 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) 2016-2020 SierraTecnologia LLC, Some rights reserved.