Petrovo CMS - Deterministic Microframework

Petrovo CMS je minimalistický PHP framework pro interní projektové řešení. Zaměřuje se na determinismus, transparentnost a čitelnost kódu namísto abstrakčních vrstev a konvencí.

Základní Principy

• Determinismus > Abstrakce - Když čteš kód, přesně víš, co se stane. Žádná skrytá logika.
• Transparentnost > Konvence - Přímý SQL, explicitní routy, viditelný middleware.
• Čitelnost > Chytrost - Malý tým (3-5 vývojářů) který zná celý codebase.
• MariaDB-first - Přímé SQL dotazy přes prepared statements. Bez ORM.
• Minimální konfigurace - YAML soubory, žádné DI kontejnery, žádné framework overhead.

Požadavky

PHP 8.4+, MariaDB 10+

Rychlý Start

Spuštění

./server                    # Vývojový server
./console list              # Dostupné CLI příkazy
./pest                      # Spuštění testů

Vytváření Komponent

./console make:cubetype     # Nový cube (blok obsahu)
./console make:tag          # Nový template tag
./console make:module       # Nový admin modul

Běžné Operace

./console db:create:page    # Vytvoří novou stránku
./console db:create:user    # Vytvoří admin uživatele
./console cron:purge-cache  # Vymaže cache
./console auth:invite       # Pošle passkey invite do administrace

Architektura v Kostce

Request Flow

HTTP Request
    ↓
public/index.php → app/bootstrap.php
    ↓
Named Middleware Pipeline (website|admin|adminTools|run|run-admin)
    ↓
Router
    ↓
Handler (Controller, Tag, Route file)
    ↓
Template Engine → Response (PSR-7)

Klíčové Komponenty

Komponenta	Umístění	Účel
Database	core/Database/	Přímý SQL přes PDO, parameterized queries
Template Engine	core/Template/	Custom tag-based šablony + RainTPL
Cube System	core/Cube/	Reusable dynamické obsahové bloky (komponenty)
Modules	app/Modules/	Aplikační logika, controllery a služby
Middleware	app/Middlewares/	PSR-15 pipelines pro routing
Routes	app/routes/	Vlastní Core\Route registry-based routing

Struktura Projektu

app/
├── bootstrap.php          # Inicializace, routes, middleware
├── Modules/               # Hlavní aplikační moduly
├── Middlewares/           # Middleware komponenty
├── Cubes/                 # Cube komponenty
├── website/               # Website tagy, šablony a route handlery
├── admin/                 # Sdílené admin šablony a legacy tools
├── routes/                # Route definice
└── commands/              # CLI příkazy

core/
├── Database/              # DB layer (PDO wrapper)
├── Template/              # Template engine
├── Cube/                  # Cube system
├── Data/                  # Data API
├── Menu/                  # Menu system
├── Cache/                 # Caching layer
└── ...                    # Ostatní komponenty

public/
├── index.php              # Hlavní entry point
└── ADMIN/                 # Statické assety administrace

var/                       # Runtime cache a tmp soubory
tests/                     # Pest testy

Dokumentace

Aplikace (App Layer)

Logika CMS, routing, middleware, templating, CRM funkce.

• Router - URL routing a přepisování
• Admin - Současná struktura administrace
• Website Auth - Website login, registrace a passwordless flow
• Integrace - Externí služby a jejich role v systému
• Templates - Šablonovací systém (tagy, RainTPL)
• Middlewares - Request pipeline
• Console - CLI příkazy
• Uploads - Nahrávání souborů
• Translations - Internacionalizace
• Admin Icons - Ikony v administraci
• Admin Auth (Passkey) - Přihlášení administrace přes centrální auth server

Core Framework

Základní infrastruktura a utility.

• Database - SQL queries, prepared statements, transaction
• Menu System - Hierarchické menu struktura
• Validation - Validační pravidla
• Dotenv - Environment configuration
• JSON - JSON utilities
• PSR Standards - PSR-7 HTTP, PSR-15 Middleware

Běžné Vzory

Database Query

use DB;

// Parameterized queries vždy
$user = DB::row("SELECT * FROM users WHERE id = ? AND active = ?", [$userId, 1]);
$users = DB::results("SELECT * FROM users WHERE status = ?", ['active']);
$count = DB::var("SELECT COUNT(*) FROM users");

Template Tag

// app/tags/myTag.php
return function(array $params, object $BOX, array $calls): array {
    $output = '<div>' . ($params['text'] ?? '') . '</div>';
    return [$output, $BOX];
};

// V šabloně: {T myTag text="Hello"}

Route Handler

// app/routes/website.php
get('/newsletter-email-activation', __DIR__ . '/../website/tags/newsletter/add-email/activation.php', PIPE_WEBSITE);

Cube Komponenta

Cube systém je dvouúrovňový - Cube Types (šablony) + Cube Instances (vyplněná data):

Cube Type (Blueprint - vytvořte jednou, používejte všude):

app/Cubes/mycube/
├── data.yaml         # ⭐ Klíč: Deklarativní definice formulářových polí
├── template.tpl      # Frontend šablona
├── frontend.php      # Volitelná logika zpracování dat
├── controller.php    # Volitelná příprava selectů pro admin
├── _data.json        # Metadata typu
└── images/           # Náhled v administraci

Cube Instance (Konkrétní obsah - mnoho instancí z jednoho typu):

• Redaktor v adminu vybere typ a vyplní formulář
• Automaticky se vygeneruje z data.yaml
• Data se uloží do DB a vloží do stránky

Vytvoření typu:

./console make:cubetype

Workflow: Type (struktura) → Admin Form (automaticky z YAML) → Instance (data) → Frontend Rendering

Filosofie: Proč tenhle přístup?

Malé týmy pracující na interních projektech nemusí enterprise framework. Potřebují:

• Jasnost - Čteš kód a víš přesně co se stane
• Rychlost - Bez abstrakčních vrstev je kód jednodušší
• Kontrola - Nic není skryto, všechno je viditelné
• Flexibilita - Funkční přístup, ne OOP dogmatismus

Tyhle principy dělají Petrovo CMS ideální pro interní korporátní řešení, kde všichni vývojáři znají codebase.

---

Podrobnější dokumentaci najdeš v sekci App a Core.