VelvetCMS Core Overview
What ships out of the box, why it exists, and how the core pieces fit together.
VelvetCMS Core is a lean, modular PHP 8.3 framework that powers the upcoming VelvetCMS Extended CMS. It delivers just the essentials—service container, routing, content drivers, theming, events, and a batteries-included CLI—so you can assemble content-driven products without hauling in a full Laravel install.
Core ideas #
- One bootstrap for everything.
bootstrap/app.phpinstantiatesVelvetCMS\Core\Application, registers aliases (events,router,db,cache,pages,theme), boots modules, and shares the container with both HTTP and CLI entrypoints. - Convention-driven services. Every major service (page rendering, Markdown, cache, DB) is a singleton resolved through the container. Public helper functions in
src/Support/helpers.php(base_path(),config(),view()…) are thin facades over those services. - Modular by design. Modules register through
VelvetCMS\Core\ModuleManager, which loads metadata fromstorage/modules-compiled.json, validates dependencies withVersionRegistry, and boots each module in order. - File-first content, swappable drivers. Pages are Markdown files with YAML frontmatter by default (
FileDriver), but you can switch toDBDriver,HybridDriver, orAutoDriverviaconfig/content.phporCONTENT_DRIVER. - Secure defaults. Auto-escaped template engine (
TemplateEngine), CSRF middleware, secure session config, and exception handling pipeline (VelvetCMS\Exceptions\Handler) ship out of the box.
Repository layout #
VelvetCMS keeps HTTP, CLI, content, and theming concerns in predictable top-level folders so every entrypoint shares the same mental model. Browse the snapshot below, then head to Directory Structure for deep dives and rationale.
| Path | Purpose | Key files |
|---|---|---|
bootstrap/ |
Shared bootstrap that creates the Application container. |
bootstrap/app.php |
config/ |
PHP arrays that drive every service. Cached via config:cache. |
app.php, content.php, theme.php, modules.php, … |
content/ |
Markdown pages (default store). Drivers resolve via content_path(). |
content/pages/welcome.md |
database/ |
SQL migrations + seeds. | database/migrations/*.sql |
public/ |
Front controller + public assets. Serves as web root. | public/index.php |
routes/ |
Route definition closures, cacheable. | routes/web.php |
src/ |
All framework code. Namespaces map 1:1 via Composer PSR‑4. | src/Core, src/Commands, src/Http, … |
storage/ |
Cache, logs, sessions, compiled module manifests. | storage/cache, storage/modules-compiled.json |
themes/ |
Theme folders with .velvet.php templates and assets. |
themes/default/layouts/default.velvet.php |
velvet |
CLI entry script registered as Composer bin. | invokes VelvetCMS\Commands\CommandRegistry |
What you can build today #
- A documentation site (see the bundled Docs module).
- Marketing landing pages or product microsites with file-based content.
- Minimal APIs or webhook receivers (routing supports any callable handler).
- Foundation for VelvetCMS Extended (admin UI, auth, media) or your own modules.
When to reach for Extended #
VelvetCMS Core intentionally skips user management, media libraries, and admin panels. VelvetCMS Extended (a separate repo) layers those on top but still uses the same container, routing, and content services described in these docs. Everything you learn here applies there.