README

CMS - Add a CMS to any Laravel app to gain control of: pages, blogs, galleries, events, custom modules, images and more.

Índice

Introdução
Instalação
Arquitetura e Estrutura Interna
Principais Módulos e Funcionalidades
Uso Prático
Integração com o Ecossistema Rica Soluções
Extensão e Customização
Exemplos Reais
Ferramentas de Desenvolvimento
Guia de Contribuição

Introdução

O que é a biblioteca CMS

SierraTecnologia CMS é uma biblioteca Laravel completa e extensível que adiciona funcionalidades de gerenciamento de conteúdo (CMS) a qualquer aplicação Laravel existente. Desenvolvida pela Rica Soluções/SierraTecnologia, a biblioteca oferece controle total sobre:

📄 Páginas estáticas e dinâmicas
📝 Blogs e artigos
📅 Calendário de eventos
🖼️ Galeria de imagens
📁 Gerenciamento de arquivos
🧭 Menus de navegação
🧩 Widgets reutilizáveis
❓ FAQs (Perguntas Frequentes)
🎁 Promoções e destaques

Objetivo e Filosofia do Projeto

A filosofia central do SierraTecnologia CMS é fornecer uma solução modular, extensível e profissional para gerenciamento de conteúdo, seguindo os melhores padrões de desenvolvimento Laravel e arquitetura de software:

Modularidade: Ative apenas os módulos que você precisa
Extensibilidade: Crie módulos customizados facilmente
Padrões de Código: PSR-12, SOLID, e Laravel Best Practices
Testabilidade: Cobertura completa de testes unitários e de integração
Documentação: Código bem documentado e exemplos práticos

Benefícios de Uso

✅ Produtividade: Não reinvente a roda - use componentes prontos e testados ✅ Padronização: Código consistente seguindo padrões da Rica Soluções ✅ Manutenibilidade: Arquitetura limpa facilita manutenção e evolução ✅ Multiidioma: Suporte nativo a múltiplos idiomas ✅ Versionamento: Histórico completo de alterações em conteúdo ✅ SEO-Ready: Recursos otimizados para mecanismos de busca ✅ Segurança: Validações, criptografia e proteção de assets

Integração no Ecossistema Rica Soluções

O CMS faz parte do ecossistema maior da Rica Soluções, integrando-se perfeitamente com:

sierratecnologia/builder: Geração de código e scaffolding
ricardosierra/translation: Sistema de tradução e internacionalização
ricardosierra/minify: Otimização de assets (CSS/JS)
Outros pacotes: API base, GraphQL, arquiteto, técnico, etc.

Instalação

Requisitos Mínimos

PHP: 7.1.3 ou superior (recomendado PHP 8.0+)
Laravel: 7.x ou superior
MySQL: 5.7+ ou PostgreSQL 9.6+
Composer: 2.x
Extensões PHP: OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath, Fileinfo, GD

Instalação via Composer

1. Adicione o repositório ao seu `composer.json` (se necessário)

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/SierraTecnologia/CMS"
        }
    ]
}

2. Instale o pacote

composer require sierratecnologia/cms

3. Publique os assets e configurações

# Publicar todos os assets (configuração, views, controllers, rotas, temas)
php artisan vendor:publish --provider="SierraTecnologia\Cms\SierraTecnologiaCmsProvider"

# Publicar apenas as views do backend (opcional)
php artisan vendor:publish --provider="SierraTecnologia\Cms\SierraTecnologiaCmsProvider" --tag="backend"

4. Execute as migrações

php artisan migrate

5. Execute o setup inicial

php artisan cms:setup

Este comando irá:

Gerar chaves de criptografia
Criar estruturas iniciais
Configurar o ambiente

Registro de ServiceProviders

O ServiceProvider principal (SierraTecnologiaCmsProvider) é registrado automaticamente via auto-discovery do Laravel 5.5+.

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

'providers' => [
    // ...
    SierraTecnologia\Cms\SierraTecnologiaCmsProvider::class,
],

Configuração

O arquivo de configuração principal está em config/cms.php. Principais configurações:

return [
    // Analytics: 'google' ou 'internal'
    'analytics' => 'internal',

    // Prefixo de rotas do backend
    'backend-route-prefix' => 'cms',

    // Tema do frontend
    'frontend-theme' => 'default',

    // Tema do backend: 'standard' ou 'dark'
    'backend-theme' => 'standard',

    // Paginação padrão
    'pagination' => 24,

    // Módulos ativos
    'active-core-modules' => [
        'blog', 'menus', 'files', 'images',
        'pages', 'widgets', 'promotions',
        'events', 'faqs',
    ],

    // Idiomas suportados
    'languages' => [
        'en' => 'english',
        'pt' => 'portuguese',
        'es' => 'spanish',
    ],

    // Storage: 'local' ou 's3'
    'storage-location' => 'local',

    // Tamanho máximo de upload (bytes)
    'max-file-upload-size' => 6291456, // 6MB
];

Arquitetura e Estrutura Interna

Estrutura de Diretórios

src/
├── Assets/                   # Recursos estáticos (CSS, JS, imagens)
├── Console/                  # Comandos Artisan (8 comandos)
├── Controllers/              # Controllers do backend (18 controllers)
├── Facades/                  # Facades para serviços (6 facades)
├── Helpers/                  # Funções helpers (blade.php, general.php)
├── Middleware/               # Middleware custom (analytics)
├── Migrations/               # Migrações de banco (15 tabelas)
├── Models/                   # Modelos Eloquent (12 modelos)
├── Providers/                # Service Providers adicionais
├── Repositories/             # Padrão Repository (11 repositórios)
├── Requests/                 # Form Requests/Validações (10 requests)
├── Routes/                   # Definições de rotas (web.php, api.php)
├── Services/                 # Lógica de negócio (11 serviços + traits)
├── Templates/                # Templates para geração de código
├── Views/                    # Views Blade do backend (60+ views)
└── PublishedAssets/          # Assets publicáveis para o projeto
    ├── Config/               # Arquivo de configuração
    ├── Controllers/          # Controllers customizáveis
    ├── Middleware/           # Middleware customizável
    ├── Routes/               # Rotas customizáveis
    ├── Setup/                # Views de setup
    ├── Theme/                # Tema padrão
    └── Views/                # Views customizáveis

Padrões Arquiteturais

O SierraTecnologia CMS implementa uma arquitetura em camadas baseada no Service-Repository Pattern combinado com MVC:

┌─────────────────────────────────────────────────────────────┐
│                  PRESENTATION LAYER                          │
│  Controllers (PagesController, BlogController, etc.)         │
│  - Recebem requisições HTTP                                  │
│  - Delegam lógica para Services                              │
│  - Retornam Views ou JSON                                    │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   APPLICATION LAYER                          │
│  Services (PageService, BlogService, ModuleService)         │
│  - Contêm lógica de negócio                                 │
│  - Usam Repositories para acesso a dados                    │
│  - Implementam Traits para reutilização                     │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                  DOMAIN LAYER                                │
│  Repositories (PageRepository, BlogRepository)              │
│  - Acesso a dados via Eloquent                              │
│  - Queries e filtros                                         │
│  Models (Page, Blog, Event, etc.)                           │
│  - Entidades do domínio                                      │
│  - Relacionamentos Eloquent                                 │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│            INFRASTRUCTURE LAYER                              │
│  Eloquent ORM + Migrations + Database                       │
└─────────────────────────────────────────────────────────────┘

Comunicação entre Camadas

Fluxo típico de uma requisição (exemplo: criar página)

1. POST /cms/pages
   ↓
2. PagesController@store
   - Valida com PagesRequest
   - Prepara dados
   ↓
3. PageRepository@store
   - parseBlocks() - extrai blocos dinâmicos
   - Processa hero_image
   - Define published_at
   ↓
4. Page Model (Eloquent)
   - Aplica regras de validação
   - Mutadores/Accessors
   - afterSaved() → cria Archive (histórico)
   ↓
5. Database INSERT
   ↓
6. Response: redirect + notification

Convenções da Rica Soluções

PSR-12: Padrão de código rigorosamente seguido
Namespaces: Sempre SierraTecnologia\Cms\{Layer}\{Component}
Nomenclatura:
- Controllers: {Entity}Controller (ex: PagesController)
- Services: {Entity}Service (ex: PageService)
- Repositories: {Entity}Repository (ex: PageRepository)
- Models: {Entity} (ex: Page)
- Requests: {Entity}Request (ex: PagesRequest)
Traits: Para funcionalidades compartilhadas (MenuServiceTrait, ModuleServiceTrait)
Facades: Para acesso simplificado (Cms::, PageService::)

Principais Módulos e Funcionalidades

1. Pages (Páginas)

Gerenciamento completo de páginas estáticas e dinâmicas.

Funcionalidades:

✏️ Editor WYSIWYG (Redactor)
📋 Templates dinâmicos
🧱 Blocos customizáveis (JSON)
🔍 SEO (title, description, keywords)
📅 Publicação agendada
🖼️ Imagem hero/destaque
📜 Histórico de versões
🌐 Multilíngue

Exemplo de uso (src/Controllers/PagesController.php:145):

// No Controller
use SierraTecnologia\Cms\Repositories\PageRepository;

$pageRepo = app(PageRepository::class);

// Criar página
$page = $pageRepo->store([
    'title' => 'Sobre Nós',
    'url' => 'sobre-nos',
    'entry' => '<h1>Nossa História</h1><p>...</p>',
    'is_published' => true,
    'published_at' => now(),
    'seo_description' => 'Conheça nossa história',
    'seo_keywords' => 'sobre, empresa, história',
]);

// Buscar por URL
$page = $pageRepo->findPagesByURL('sobre-nos');

// Listar publicadas
$pages = $pageRepo->published();

Rotas:

GET    /cms/pages           → PagesController@index
GET    /cms/pages/create    → PagesController@create
POST   /cms/pages           → PagesController@store
GET    /cms/pages/{id}/edit → PagesController@edit
PATCH  /cms/pages/{id}      → PagesController@update
DELETE /cms/pages/{id}      → PagesController@destroy
POST   /cms/pages/search    → PagesController@search

2. Blog (Artigos/Posts)

Sistema completo de blog com tags, SEO e publicação agendada.

Funcionalidades:

📝 Posts com editor rico
🏷️ Sistema de tags
🔍 SEO otimizado
📅 Publicação agendada
🖼️ Imagem de destaque
📊 RSS Feed
🌐 Multilíngue

Exemplo de uso (src/Controllers/BlogController.php:98):

use SierraTecnologia\Cms\Repositories\BlogRepository;

$blogRepo = app(BlogRepository::class);

// Criar post
$post = $blogRepo->store([
    'title' => 'Laravel 10 - Novidades',
    'url' => 'laravel-10-novidades',
    'entry' => '<p>O Laravel 10 trouxe várias melhorias...</p>',
    'tags' => 'laravel,php,framework',
    'is_published' => true,
    'published_at' => now(),
]);

// Listar posts publicados
$posts = $blogRepo->published();

Blade Helpers:

{{-- Listar últimos posts --}}
@foreach(app('SierraTecnologia\Cms\Repositories\BlogRepository')->published()->take(5) as $post)
    <article>
        <h2>{{ $post->title }}</h2>
        <p>{{ $post->seo_description }}</p>
        <a href="/blog/{{ $post->url }}">Ler mais</a>
    </article>
@endforeach

3. Menus (Navegação)

Sistema de menus dinâmicos com ordenação (src/Controllers/MenuController.php:67).

Funcionalidades:

🧭 Estrutura hierárquica
🔢 Ordenação customizável
🔗 Links internos/externos
🌐 Multilíngue

Blade Helpers:

{{-- Renderizar menu --}}
@menu('main')

{{-- Com view customizada --}}
@menu('main', 'partials.navigation')

4. Images (Galeria de Imagens)

Sistema completo de upload e gerenciamento (src/Controllers/ImagesController.php:213).

Blade Helpers:

{{-- Renderizar imagem --}}
@image('produto-destaque.jpg', 'alt text')

{{-- Listar imagens por tag --}}
@images('portfolio')

5. Widgets (Componentes Reutilizáveis)

Blocos de conteúdo reutilizáveis via slug (src/Controllers/WidgetsController.php:45).

{{-- Renderizar widget --}}
@widget('footer-contato')

6. Outros Módulos

Events: Calendário de eventos (src/Controllers/EventController.php:72)
Files: Gerenciamento de arquivos (src/Controllers/FilesController.php:165)
FAQs: Perguntas frequentes (src/Controllers/FAQController.php:34)
Promotions: Promoções e destaques (src/Controllers/PromotionsController.php:56)

Uso Prático

Instalação em Projeto Laravel Existente

Cenário: Você tem um projeto Laravel de e-commerce e quer adicionar blog, páginas institucionais e FAQs.

Passo 1: Instalar o CMS

composer require sierratecnologia/cms
php artisan vendor:publish --provider="SierraTecnologia\Cms\SierraTecnologiaCmsProvider"
php artisan migrate
php artisan cms:setup

Passo 2: Configurar módulos ativos

Em config/cms.php:

'active-core-modules' => [
    'blog',
    'pages',
    'faqs',
],

Passo 3: Acessar o painel admin

http://seusite.com/cms

Passo 4: Integrar no frontend

// app/Http/Controllers/PageController.php
public function show($url)
{
    $pageRepo = app(\SierraTecnologia\Cms\Repositories\PageRepository::class);
    $page = $pageRepo->findPagesByURL($url);

    if (!$page) {
        abort(404);
    }

    return view('pages.show', compact('page'));
}

{{-- resources/views/pages/show.blade.php --}}
@extends('layouts.app')

@section('title', $page->title)
@section('meta_description', $page->seo_description)

@section('content')
    <h1>{{ $page->title }}</h1>
    {!! $page->entry !!}
@endsection

Integração com o Ecossistema Rica Soluções

Relação com Outras Bibliotecas

O SierraTecnologia CMS integra-se perfeitamente com outras bibliotecas da Rica Soluções:

sierratecnologia/builder

Geração automática de código
Scaffolding de módulos
CRUD generators

# Gerar CRUD completo
php artisan builder:crud Produto

ricardosierra/translation

Sistema completo de tradução
Suporte multilíngue
Gestão de idiomas

// Models usam trait HasTranslations
$page->translate('pt')->title = 'Sobre Nós';
$page->translate('en')->title = 'About Us';

ricardosierra/minify

Minificação automática de CSS/JS
Otimização de assets
Cache de recursos

Testes Automatizados

O CMS possui cobertura completa de testes:

# Executar todos os testes
composer test

# Com cobertura
composer test-coverage

# Apenas testes de feature
vendor/bin/phpunit --testsuite=Feature

Extensão e Customização

Como Criar Módulos Customizados

O CMS oferece comandos para gerar módulos rapidamente:

1. Gerar módulo completo

php artisan module:make Produto

Isso criará:

cms/modules/produto/
├── Controllers/
│   └── ProdutoController.php
├── Models/
│   └── Produto.php
├── Repositories/
│   └── ProdutoRepository.php
├── Requests/
│   └── ProdutoRequest.php
├── Routes/
│   └── web.php
├── Views/
│   ├── index.blade.php
│   ├── create.blade.php
│   └── edit.blade.php
└── migrations/
    └── create_produtos_table.php

2. Gerar apenas CRUD

php artisan module:crud Categoria

3. Gerar tema

php artisan theme:generate MeuTema

Em config/cms.php:

'frontend-theme' => 'MeuTema',

Ferramentas de Desenvolvimento

Configuração de Qualidade de Código

O projeto está configurado com ferramentas profissionais de verificação:

PHPCS (PHP_CodeSniffer) - PSR-12

# Verificar código
composer cs
# ou
vendor/bin/phpcs

# Corrigir automaticamente
composer cs-fix
# ou
vendor/bin/phpcbf

Configuração: phpcs.xml

PHPStan - Análise Estática (Nível 5)

# Analisar código
composer stan
# ou
vendor/bin/phpstan analyse

Configuração: phpstan.neon

PHPUnit - Testes Automatizados

# Executar testes
composer test

# Com cobertura HTML
composer test-coverage

Configuração: phpunit.xml

GitHub Actions - CI/CD

O pipeline automatizado executa:

✅ Testes em PHP 7.4, 8.0, 8.1, 8.2 ✅ Testes em Laravel 7.x, 8.x, 9.x, 10.x ✅ PHPCS (PSR-12) ✅ PHPStan (Nível 5) ✅ Security Check ✅ Cobertura de testes (Codecov)

Arquivo: .github/workflows/ci.yml

Scripts Composer Úteis

# Verificar tudo de uma vez
composer check

Comandos Artisan do CMS

# Setup inicial
php artisan cms:setup

# Gerar chaves de criptografia
php artisan cms:keys

# Módulos
php artisan module:make {name}         # Criar módulo completo
php artisan module:crud {name}         # Criar CRUD
php artisan module:composer {name}     # Gerar composer.json
php artisan module:publish             # Publicar módulo

# Temas
php artisan theme:generate {name}      # Criar tema
php artisan theme:publish              # Publicar tema
php artisan theme:link                 # Criar symlink

Guia de Contribuição

Como Contribuir

Contribuições são muito bem-vindas! Siga os passos:

1. Fork e Clone

git clone https://github.com/SEU-USUARIO/CMS.git
cd CMS
composer install

2. Criar Branch

git checkout -b feature/minha-funcionalidade

3. Fazer Mudanças

Escreva código limpo e documentado
Siga PSR-12
Adicione testes
Atualize documentação se necessário

4. Executar Verificações

composer check

5. Commit e Push

git add .
git commit -m "feat: adiciona suporte a vídeos no blog"
git push origin feature/minha-funcionalidade

6. Abrir Pull Request

Descreva suas mudanças
Referencie issues relacionadas
Aguarde code review

Padrões de Commit

Use Conventional Commits:

feat: adiciona nova funcionalidade
fix: corrige bug
refactor: refatora código sem mudar funcionalidade
docs: atualiza documentação
test: adiciona ou corrige testes
style: mudanças de formatação
chore: tarefas de manutenção
perf: melhoria de performance
ci: mudanças no CI/CD

Code Review

Toda contribuição passa por code review:

✅ Código segue PSR-12 ✅ Testes passam ✅ PHPStan nível 5 passa ✅ Cobertura de testes adequada ✅ Documentação atualizada ✅ Sem breaking changes não documentadas

License

SierraTecnologia CMS is open-sourced software licensed under the MIT license

Redactor License

SierraTecnologia has an OEM licence for the use of Redactor in the SierraTecnologia CMS package. You are fully welcome to use SierraTecnologia CMS package and incorporate it into any apps you build, you are permitted to offer those apps as SaaS or other products. However, you are not entitle to strip out parts of Redactor and resell them, please see this license for more information

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About SierraTecnologia

SierraTecnologia is a software development company specializing in Laravel-based solutions for enterprise applications. We are part of the Rica Soluções ecosystem, providing high-quality, maintainable, and scalable packages for the Laravel community.

Our Mission

To empower developers with robust, well-architected components that accelerate development while maintaining code quality and best practices.

Our Packages

CMS: Content Management System for Laravel
Builder: Code generation and scaffolding tools
Translation: Comprehensive internationalization system
Minify: Asset optimization and minification
API Base: RESTful API foundation
GraphQL Laravel: GraphQL integration
And many more...

Contact

Website: https://cms.sierratecnologia.ca
Documentation: https://docs.sierratecnologia.ca/cms
Gitter: Join the chat
GitHub Issues: Report a bug
Email: ricardo@sierratecnologia.com.br

Authors

Matt Lantz (@mattylantz) - Original creator
Ricardo Rebello Sierra - Lead maintainer and Rica Soluções architect

Contributing

We welcome contributions from the community. Please see our contribution guidelines above.

Made with ❤️ by SierraTecnologia & Rica Soluções

sierratecnologia / cms

Maintainers

Details

README

Índice

Introdução

O que é a biblioteca CMS

Objetivo e Filosofia do Projeto

Benefícios de Uso

Integração no Ecossistema Rica Soluções

Instalação

Requisitos Mínimos

Instalação via Composer

1. Adicione o repositório ao seu composer.json (se necessário)

2. Instale o pacote

3. Publique os assets e configurações

4. Execute as migrações

5. Execute o setup inicial

Registro de ServiceProviders

Configuração

Arquitetura e Estrutura Interna

Estrutura de Diretórios

Padrões Arquiteturais

Comunicação entre Camadas

Convenções da Rica Soluções

Principais Módulos e Funcionalidades

1. Pages (Páginas)

2. Blog (Artigos/Posts)

3. Menus (Navegação)

4. Images (Galeria de Imagens)

5. Widgets (Componentes Reutilizáveis)

6. Outros Módulos

Uso Prático

Instalação em Projeto Laravel Existente

Passo 1: Instalar o CMS

Passo 2: Configurar módulos ativos

Passo 3: Acessar o painel admin

Passo 4: Integrar no frontend

Integração com o Ecossistema Rica Soluções

Relação com Outras Bibliotecas

sierratecnologia/builder

ricardosierra/translation

ricardosierra/minify

Testes Automatizados

Extensão e Customização

Como Criar Módulos Customizados

1. Gerar módulo completo

2. Gerar apenas CRUD

3. Gerar tema

Ferramentas de Desenvolvimento

Configuração de Qualidade de Código

PHPCS (PHP_CodeSniffer) - PSR-12

PHPStan - Análise Estática (Nível 5)

PHPUnit - Testes Automatizados

GitHub Actions - CI/CD

Scripts Composer Úteis

Comandos Artisan do CMS

Guia de Contribuição

Como Contribuir

1. Fork e Clone

2. Criar Branch

3. Fazer Mudanças

4. Executar Verificações

5. Commit e Push

6. Abrir Pull Request

Padrões de Commit

Code Review

License

Redactor License

Disclaimer

About SierraTecnologia

Our Mission

Our Packages

Contact

Authors

Contributing

1. Adicione o repositório ao seu `composer.json` (se necessário)