◆ v0.0.2 — Early Development

A CMS that gets
out of your way

MinimalCMS is a flat-file PHP CMS with a familiar hook, plugin, and theme architecture — no database, no framework, no container required.

► Quick Start ↗ View on GitHub
Version 0.0.2 PHP 8.2+ GPL-2.0 License Early Development
0
Database tables
PHP 8.2
Minimum version
1
Front controller
4
User roles
256-bit
User-data encryption
∞
Plugins & themes
Features

Everything you need, nothing you don't

MinimalCMS borrows the best ideas from multiple sources — hooks, plugins, themes, a clean admin panel — and strips away the database dependency entirely.

📄

Flat-File Content

Write in Markdown. Metadata lives in a JSON sidecar next to each file. No migration scripts, no schema changes — just folders.

  • Pages, posts, and custom content types
  • JSON sidecar: title, slug, status, metadata
  • Archive routes with auto-permalink slugs
  • Shortcode parser [tag attr="val"]
🔒

Security First

Applying security at every layer so you can focus on building, not patching.

  • User data encrypted with sodium_crypto_secretbox (256-bit)
  • Passwords hashed with bcrypt
  • HMAC-SHA256 nonces on every form and link action
  • mc-data/ double-locked: Apache Deny all + PHP die()
  • Full sanitization & escaping API
🧰

Hook-Driven Architecture

Actions and filters run at well-defined points throughout the request lifecycle.

  • mc_add_action / mc_add_filter
  • Content, admin, and plugin lifecycle hooks
  • MU-plugins directory for must-run code
  • Settings API for plugin config pages
🎨

Theme System

A full template hierarchy so themes can override any part of the request, from 404s to custom content-type archives.

  • Template fallback chain (type → singular → index)
  • Child theme support
  • theme.json manifest with metadata
  • Live theme switching from the admin panel
👥

User Management

A built-in role & capability system with four built-in roles and full CRUD from the admin panel.

  • Roles: administrator, editor, author, contributor
  • mc_user_can() / mc_current_user_can()
  • Custom capabilities via mc_add_cap()
  • Encrypted flat-file user store
🔧

Developer Experience

Pre-configured tooling means you can clone, run tests, and start building within minutes.

  • PHPUnit test suite — unit & integration
  • PHPStan + MinimalCMS Coding Standards (PHPCS)
  • SCSS build pipeline via npm + Sass
  • File-based PHP cache with configurable TTL
  • PHP-WASM browser demo via npm

See it in action

A tour of the admin panel and front-end rendering.

Admin Dashboard

Admin Dashboard

Markdown Editor

Markdown Editor

Content List

Content List

Plugin Manager

Plugin Manager

Theme Switcher

Theme Switcher

Settings Page

Settings Page
Architecture

How it works

Every HTTP request flows through a single front controller. There is no routing framework — just PHP includes and a clean hook system.

Browser request
.htaccess
Apache rewrites every non-file URL to index.php.
Front controller
index.php → mc-blog-header.php
Bootstraps the CMS and orchestrates boot → route → render.
Bootstrap
mc-load.php · mc-settings.php
Defines constants, loads config, fires plugins, activates theme.
URL routing
mc-includes/rewrite.php
Resolves the request path to a content item (slug, type, archive).
Template selection
mc-includes/template-loader.php
Walks the template hierarchy to find the most specific match.
Render
theme template file
Template calls template-tag helpers, Markdown is parsed, content is output.
Directory structure (abbreviated)
minimalcms/
├── index.php          # front controller
├── .htaccess          # rewrite all → index.php
├── config.json        # keys, active theme/plugins
├── mc-load.php        # constants & autoload
├── mc-settings.php    # boot sequence
├── mc-includes/       # core libraries
│   ├── hooks.php
│   ├── rewrite.php
│   ├── content.php
│   ├── user.php
│   └── …
├── mc-content/        # all user data
│   ├── pages/
│   ├── plugins/
│   └── themes/
│       └── default/
├── mc-admin/          # admin panel
│   ├── login.php
│   ├── setup.php
│   ├── index.php      # dashboard
│   └── …
└── mc-data/           # encrypted; Deny all
    └── users.php
Get Started

Up and running in minutes

MinimalCMS requires only PHP 8.2+ and Apache with mod_rewrite. No database. No container.

1

Clone the repo

Download or git clone into your web root.

2

Install deps (optional)

Run composer install for tests & linting. Not needed for production.

3

Point Apache

Set the document root to the project folder and enable mod_rewrite.

4

Run the wizard

Visit /mc-admin/ — the setup wizard creates your config and first admin account.

bash 
# 1. Clone
git clone https://github.com/namithj/MinimalCMS.git my-site
cd my-site

# 2. Install dev dependencies (tests & linting only)
composer install

# 3. Point Apache at the project root and enable mod_rewrite

# 4. Open the admin panel — setup wizard runs on first visit
open http://your-site.local/mc-admin/

# ── Optional: build CSS assets ──────────────────────────────────
npm install
npm run build

# ── Optional: run tests ─────────────────────────────────────────
composer test:unit
composer test:integration
Requirements

What you need

Requirement Version / Detail Notes
PHP 8.2+ Sodium bundled since 7.2; tested on 8.3
Web server Apache + mod_rewrite .htaccess included
Disk access Write on project root Config, content, sessions, and cache are written at runtime
Database None Flat files only ✓