Overview

VelvetCMS Core is a modular content application framework built for PHP 8.4+. It provides the foundation for building content-driven applications with a focus on explicit architecture, file-native pages, and practical extension points.

What is VelvetCMS? #

VelvetCMS is not a traditional CMS with a pre-built admin panel. Instead, it's a framework that gives you the building blocks to create exactly the content system you need:

• Headless API backends - Serve content to any frontend
• Static site generators - Build blazing-fast static sites
• Traditional dynamic sites - Server-rendered pages with caching
• Hybrid applications - Mix static and dynamic as needed

Think of it as Laravel's elegance meets content-first architecture, without the overhead.

Why VelvetCMS? #

Performance First #

VelvetCMS is designed to be fast out of the box:

• <1ms response times with warm cache
• Minimal memory footprint (~4MB baseline)
• Lazy loading everywhere - services instantiate only when used
• Multiple cache layers - opcode, content, query caching

Truly Modular #

Everything is a module. The core itself is minimal - functionality is added through composable modules:

VelvetCMS Core (routing, DI, events)
    └── Your Modules
        ├── Blog
        ├── Shop  
        ├── API
        └── Admin Panel

Modules can:

• Register routes, commands, and event listeners
• Provide services and configuration
• Override views and assets
• Depend on other modules

File-Native Content #

Core 2.x treats page content as files and keeps the query side fast with an index:

• .md and .vlt pages live under user/content/pages
• frontmatter carries metadata like title, status, layout, and timestamps
• a JSON or SQLite page index powers lists, counts, and sorted lookups
• the PageService API stays simple while the storage layer remains inspectable and Git-friendly

Modern PHP #

Built exclusively for PHP 8.4+:

• Constructor property promotion
• Named arguments throughout
• Readonly properties

No legacy compatibility baggage.

Core Concepts #

The Container #

At the heart of VelvetCMS is a powerful dependency injection container:

// Bind a service
$container->singleton('search.index', fn () => new SearchIndex(storage_path('search')));

// Resolve with automatic injection
$service = $container->make(MyService::class);

Services are lazy-loaded - they're only instantiated when first requested.

Routing #

Routes map URLs to handlers with a clean, expressive syntax:

$router->get('/posts/{slug}', [PostController::class, 'show']);
$router->post('/api/posts', [ApiController::class, 'store']);

// Route groups with middleware
$router->group(['prefix' => '/admin', 'middleware' => ['auth']], function($router) {
    $router->get('/dashboard', [AdminController::class, 'dashboard']);
});

Content & Pages #

The PageService provides a unified API for working with content:

$page = $pageService->load('about');
$page->title;      // From frontmatter
$page->html();     // Rendered HTML
$page->meta;       // All metadata

// Query pages
$posts = $pageService->list(['status' => 'published', 'limit' => 10]);

Events #

Decouple your application with events:

// Dispatch an event
$events->dispatch('page.saved', $page);

// Listen for events
$events->listen('page.saved', function ($page) {
    $this->cache->forget("page:{$page->slug}");
});

Modules #

Extend VelvetCMS through self-contained modules:

modules/Blog/
├── module.json          # Manifest
├── src/
│   └── BlogModule.php   # Service provider
├── routes/
│   └── web.php          # Routes
├── resources/
│   └── views/
│       └── post.velvet.php
└── config/
    └── blog.php         # Configuration

Modules are auto-discovered from user/modules/ and loaded based on their dependencies.

Architecture at a Glance #

Request
    │
    ▼
┌─────────────────────────────────────────────────────┐
│  HTTP Kernel                                        │
│  ├─ Middleware Pipeline                             │
│  │   ├─ Session                                     │
│  │   ├─ CSRF Protection                             │
│  │   └─ Your Middleware                             │
│  └─ Router                                          │
│      └─ Controller / Closure                        │
└─────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────┐
│  Application Services                               │
│  ├─ PageService (content management)                │
│  ├─ Cache (file, apcu, redis)                       │
│  ├─ Database (query builder, migrations)            │
│  └─ Storage (filesystem abstraction)                │
└─────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────┐
│  File-Native Content                                │
│  ├─ FileDriver                                      │
│  ├─ PageIndex (json or sqlite)                      │
│  └─ PageService                                     │
└─────────────────────────────────────────────────────┘
    │
    ▼
Response

Directory Structure #

A typical VelvetCMS installation:

my-project/
├── config/              # Default configuration
├── database/
│   └── migrations/      # Database migrations
├── public/
│   └── index.php        # Web entry point
├── src/                 # Core framework code (don't edit)
├── storage/
│   ├── cache/           # Cached data
│   ├── logs/            # Application logs
│   └── database.sqlite  # SQLite database (if used)
├── user/
│   ├── config/          # Your configuration overrides
│   ├── content/
│   │   └── pages/       # Your content files
│   ├── modules/         # Your custom modules
│   └── views/           # Your view templates (.velvet.php)
├── vendor/              # Composer dependencies
├── composer.json
└── velvet               # CLI tool

The user/ directory contains everything specific to your project. The rest can be updated independently.

Who Should Use VelvetCMS? #

VelvetCMS is ideal for:

• Developers who want full control over their content architecture
• Agencies building multiple content sites with shared modules
• Teams practicing Git-based content workflows
• Projects that need a transparent content framework without a heavyweight CMS runtime

VelvetCMS might not be right if you need:

• A ready-to-use admin interface (though modules can add this)
• Visual page builders out of the box
• Non-technical content editors (without building UI for them)

What's Next? #

Ready to dive in?

1. Requirements - Check your environment
2. Installation - Get up and running
3. Configuration - Customize your setup
4. Modules - Extend with modules
5. Upgrading - Review version-to-version migration notes

For release-by-release feature summaries, see the GitHub releases.

Or jump straight to the API Reference for detailed documentation on every component.