PHPackages sierratecnologia/muleta - 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/muleta ActiveLibrary[Utility & Helpers](/categories/utility) sierratecnologia/muleta ======================= SierraTecnologia common support helpers, contracts, and traits required by various SierraTecnologia packages. Validator functionality, and basic controller included out-of-the-box. 0.4.3(4y ago)098617MITPHPPHP ^7.2|^8.0CI failing Since Jul 8Pushed 6mo ago1 watchersCompare [ Source](https://github.com/SierraTecnologia/muleta)[ Packagist](https://packagist.org/packages/sierratecnologia/muleta)[ Docs](https://sierratecnologia.com/packages/muleta/)[ Fund](https://ricasolucoes.com.br/open-source/support-us)[ GitHub Sponsors](https://github.com/ricasolucoes)[ RSS](/packages/sierratecnologia-muleta/feed)WikiDiscussions stable Synced yesterday READMEChangelogDependencies (15)Versions (19)Used By (17) SierraTecnologia Muleta ======================= [](#sierratecnologia-muleta) **SierraTecnologia common** Muleta helpers, contracts, and traits required by various SierraTecnologia packages. Validator functionality, and basic controller included out-of-the-box. [![Packagist](https://camo.githubusercontent.com/dcb4840837dd7f6fdcfb14115335e4df11fb20d796b2a8861ac98918ea0e453f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7369657272617465636e6f6c6f6769612f6d756c6574612e7376673f6c6162656c3d5061636b6167697374267374796c653d666c61742d737175617265)](https://packagist.org/packages/sierratecnologia/muleta)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/cd5595783e3ab37a9981182c175d7128ae588b5e241e3de4ae0d1e63c2526ca3/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f7369657272617465636e6f6c6f6769612f6d756c6574612e7376673f6c6162656c3d5363727574696e697a6572267374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/sierratecnologia/muleta/)[![Travis](https://camo.githubusercontent.com/4a957d071270ee1d71c7756afee95ea03fa98d74e6eab0c6a4b53333d5992cc0/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f7369657272617465636e6f6c6f6769612f6d756c6574612e7376673f6c6162656c3d5472617669734349267374796c653d666c61742d737175617265)](https://travis-ci.org/sierratecnologia/muleta)[![StyleCI](https://camo.githubusercontent.com/4191b35d1ee7b0da2e27c1fe2bd612ce3dfe1673a64523a762f99155892e2142/68747470733a2f2f7374796c6563692e696f2f7265706f732f36303936383838302f736869656c64)](https://styleci.io/repos/60968880)[![License](https://camo.githubusercontent.com/36a47e65c10b9a4b5e8b31eb9364a8057f9e59196be419b09d6bfd39ba537101/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7369657272617465636e6f6c6f6769612f6d756c6574612e7376673f6c6162656c3d4c6963656e7365267374796c653d666c61742d737175617265)](https://github.com/sierratecnologia/muleta/blob/develop/LICENSE) > **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 -------- [](#-í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) - [Testes e Qualidade de Código](#testes-e-qualidade-de-c%C3%B3digo) --- 🎯 Introdução ------------ [](#-introdução) ### O que é Muleta [](#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 [](#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 [](#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 [](#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 ------------ [](#-instalação) ### Requisitos Mínimos [](#requisitos-mínimos) - **PHP**: 8.2 ou superior - **Laravel**: 10.x ou 11.x - **Composer**: 2.x ### Instalação via Composer [](#instalação-via-composer) ``` composer require sierratecnologia/muleta ``` ### Dependências Sugeridas [](#dependências-sugeridas) Para funcionalidade completa, considere instalar: ``` composer require sierratecnologia/crypto composer require laravel/helpers composer require vanderlee/php-sentence composer require ricardosierra/changelog ``` ### Publicação de Configurações [](#publicação-de-configurações) O Muleta é projetado para funcionar sem publicação de assets, mas se necessário: ``` php artisan vendor:publish --provider="Muleta\Library\ServiceProvider" ``` ### Registro de Service Provider [](#registro-de-service-provider) O Service Provider é auto-descoberto no Laravel 5.5+. Para versões anteriores, adicione manualmente em `config/app.php`: ``` 'providers' => [ // ... Muleta\Library\ServiceProvider::class, ], ``` --- 🏗️ Arquitetura e Estrutura Interna ---------------------------------- [](#️-arquitetura-e-estrutura-interna) ### Estrutura de Diretórios [](#estrutura-de-diretórios) ``` muleta/ ├── src/ # Código fonte principal │ ├── Contracts/ # Interfaces e contratos │ ├── Models/ # Base models e traits │ ├── Services/ # Camada de serviços │ ├── Traits/ # 33+ traits reutilizáveis │ │ ├── Controllers/ # Traits para controllers │ │ ├── Models/ # Traits para models │ │ ├── Coder/ # Traits de geração de código │ │ └── ... │ ├── Modules/ # Módulos funcionais │ │ ├── Analysator/ # Análise de banco de dados │ │ ├── Features/ # Features específicas │ │ └── Recursos/ # Recursos compartilhados │ └── Library/ # Biblioteca core │ ├── Laravel/ # Integrações Laravel │ └── ServiceProvider.php # Service Provider principal ├── arsenal/ # Biblioteca estendida (legacy + moderno) │ ├── utils/ # Utilitários diversos │ ├── helper/ # Classes helper │ ├── logic/ # Lógica de negócio │ ├── objects/ # Objetos de domínio │ └── recursos/ # Recursos especializados ├── utils/ # Funções e classes utilitárias │ ├── funcs/ # Funções globais │ └── classes/ # Classes utilitárias ├── config/ # Arquivos de configuração ├── database/ # Migrations e seeders └── tests/ # Testes automatizados ``` ### Namespaces Principais [](#namespaces-principais) NamespacePropósitoExemplo`Muleta\`Core do pacote`Muleta\Models\BaseModel``SiUtils\`Utilitários gerais`SiUtils\StringHelper``SiHelper\`Classes auxiliares`SiHelper\ArrayHelper``SiLogic\`Lógica de negócio`SiLogic\ValidationLogic``SiObjects\`Objetos de domínio`SiObjects\ValueObject``SiWeapons\`Recursos especializados`SiWeapons\AdvancedSearcher`### Padrões Arquiteturais Adotados [](#padrões-arquiteturais-adotados) #### 1. **Repository Pattern** [](#1-repository-pattern) ``` // Interface interface RepositoryInterface { public function findById($id); public function create(array $data); public function update($id, array $data); public function delete($id); } // Implementação base abstract class Repository implements RepositoryInterface { // Implementação genérica de CRUD } ``` #### 2. **Trait Composition Pattern** [](#2-trait-composition-pattern) Ao invés de herança profunda, Muleta favorece composição via traits: ``` class Article extends Model { use HasSlug; // Gera slugs automaticamente use HasTags; // Adiciona sistema de tags use HasImages; // Gerencia imagens associadas use HasTranslations; // Suporte multi-idioma use ValidatingTrait; // Validação automática } ``` #### 3. **Service Layer Pattern** [](#3-service-layer-pattern) ``` // Lógica de negócio isolada em services class ArticleService { public function publish(Article $article) { // Lógica complexa de publicação } } ``` #### 4. **API Resource Pattern** [](#4-api-resource-pattern) ``` class ArticleResource extends JsonResource { public function toArray($request) { return [ 'id' => $this->id, 'title' => $this->title, 'slug' => $this->slug, 'tags' => TagResource::collection($this->tags), ]; } } ``` ### Convenções da SierraTecnologia [](#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 ------------------------ [](#-principais-componentes) ### 1. Contracts (Interfaces) [](#1-contracts-interfaces) #### Arrayable [](#arrayable) Garante que objetos possam ser convertidos em arrays: ``` interface Arrayable { public function toArray(): array; } ``` **Uso**: Models, DTOs, Value Objects que precisam serialização. #### Outputable [](#outputable) Define objetos que podem gerar saída formatada: ``` interface Outputable { public function output(): string; } ``` **Uso**: Reports, exportações, geradores de arquivos. #### Sortable [](#sortable) Implementa ordenação customizada: ``` interface Sortable { public function sortBy(string $field, string $direction = 'asc'); } ``` --- ### 2. Traits Essenciais [](#2-traits-essenciais) #### HasSlug [](#hasslug) Gera slugs URL-friendly automaticamente: ``` use Muleta\Traits\Models\HasSlug; class Post extends Model { use HasSlug; protected $slugSourceField = 'title'; // Campo fonte para slug } // Uso $post = Post::create(['title' => 'Meu Artigo Incrível']); echo $post->slug; // "meu-artigo-incrivel" ``` Localização: `src/Traits/Models/HasSlug.php` #### HasTags [](#hastags) Sistema completo de tags com relacionamento polimórfico: ``` use Muleta\Traits\Models\HasTags; class Article extends Model { use HasTags; } // Uso $article->attachTag('Laravel'); $article->attachTags(['PHP', 'Backend', 'API']); $tags = $article->tags; // Collection de tags $article->detachTag('Laravel'); ``` Localização: `src/Traits/Models/HasTags.php` #### HasImages [](#hasimages) Gerenciamento de múltiplas imagens associadas: ``` use Muleta\Traits\Models\HasImages; class Product extends Model { use HasImages; } // Uso $product->addImage($imagePath, 'featured'); $product->addImages($imagePaths, 'gallery'); $featuredImage = $product->getImage('featured'); $allImages = $product->images; ``` Localização: `src/Traits/Models/HasImages.php` #### HasTranslations [](#hastranslations) Suporte multi-idioma nativo: ``` use Muleta\Traits\Models\HasTranslations; class Page extends Model { use HasTranslations; protected $translatable = ['title', 'content']; } // Uso $page->setTranslation('title', 'pt_BR', 'Sobre Nós'); $page->setTranslation('title', 'en_US', 'About Us'); echo $page->getTranslation('title', 'pt_BR'); // "Sobre Nós" ``` Localização: `src/Traits/Models/HasTranslations.php` #### ValidatingTrait [](#validatingtrait) Validação automática no save/update: ``` use Muleta\Traits\Models\ValidatingTrait; class User extends Model { use ValidatingTrait; protected $validationRules = [ 'name' => 'required|min:3', 'email' => 'required|email|unique:users', ]; } // Validação automática $user = new User(['name' => 'Ab']); // Exception: nome muito curto $user->save(); // Valida automaticamente antes de salvar ``` Localização: `src/Traits/Models/ValidatingTrait.php` #### GetSetTrait [](#getsettrait) Geração automática de getters/setters via anotações: ``` use Muleta\Traits\Coder\GetSetTrait; class MyClass { use GetSetTrait; /** * @var string * @getter true * @setter false * @serializable true */ protected $modelClass; } // Uso $obj->getModelClass(); // Auto-gerado ``` Localização: `src/Traits/Coder/GetSetTrait.php` --- ### 3. Validadores Customizados [](#3-validadores-customizados) O Service Provider registra validadores estendidos: #### unique\_with [](#unique_with) Valida unicidade combinando múltiplos campos: ``` // Garante que combinação email + tenant_id seja única 'email' => 'unique_with:users,tenant_id' ``` #### file [](#file) Validação avançada de arquivos: ``` 'document' => 'file|max:10240|mimes:pdf,doc,docx' ``` #### video [](#video) Validação específica para vídeos: ``` 'video' => 'video|max:51200|mimes:mp4,avi,mov' ``` Localização: `src/Library/Laravel/Validator.php` --- ### 4. Helpers Globais [](#4-helpers-globais) #### intend() [](#intend) Retorna redirect response com suporte a múltiplos métodos: ``` return intend([ 'route' => 'dashboard', 'with' => ['success' => 'Salvo com sucesso!'], 'withErrors' => ['field' => 'Erro de validação'], ]); // Suporta: back, route, url, with, withErrors, withInput ``` Localização: `utils/funcs/helpers.php` #### mimetypes() [](#mimetypes) Retorna array de mimetypes válidos: ``` $mimetypes = mimetypes(); // ['image/jpeg', 'image/png', 'application/pdf', ...] ``` #### timezones() [](#timezones) Lista de timezones formatados: ``` $timezones = timezones(); // ['America/Sao_Paulo' => 'São Paulo (UTC-3)', ...] ``` #### lower\_case() / upper\_case() [](#lower_case--upper_case) Conversão de caso com suporte UTF-8: ``` $lower = lower_case('TEXTO EM MAIÚSCULA'); // "texto em maiúscula" $upper = upper_case('texto em minúscula'); // "TEXTO EM MINÚSCULA" ``` --- ### 5. Módulo Analysator [](#5-módulo-analysator) Sistema sofisticado de análise de banco de dados: ``` use Muleta\Modules\Analysator\DatabaseAnalyzer; $analyzer = new DatabaseAnalyzer(); // Analisa estrutura completa $schema = $analyzer->analyzeDatabase(); // Detecta anomalias $issues = $analyzer->findIndexMissingIssues(); $duplicates = $analyzer->findDuplicateIndexes(); // Otimizações sugeridas $suggestions = $analyzer->suggestOptimizations(); ``` **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 ------------- [](#-uso-prático) ### Exemplo Completo: Sistema de Blog [](#exemplo-completo-sistema-de-blog) ```