If you have outgrown WordPress but miss its flexibility, Modular is built for you. It ships with the things most teams bolt on after the fact, a field builder, relational models, role-based access and a typed API, and nothing you have to vet a plugin marketplace for.

Philosophy

One content model, two delivery modes. The same collection can render a marketing page through a PHP theme and feed a mobile app through JSON, with no duplicate setup and no second system to keep in sync.

• Headless and themed, choose per project, switch any time.
• Self-hosted, your servers, your database, your data.
• Security in the core, not a paid add-on, not a plugin.
• Open source, MIT, public roadmap, no vendor lock-in.

Architecture at a glance

A PHP application server talks to MySQL or MariaDB. The admin is a Vue 3 single-page app that consumes the same API your projects do. Themes are plain PHP templates with a small set of helper functions. Capabilities beyond the core arrive as curated modules, never an open plugin free-for-all.

Where to go next

Check the requirements, follow the installation steps, then work through the quickstart to model your first post type and read it back over the API.

Runtime

PHP extensions

Modular needs a standard set of extensions, all common on shared and managed PHP hosts:

• pdo, json, mbstring, openssl
• gd or imagick for media transforms
• intl for localisation and the Translation module

Hosting

Anything that runs PHP and MySQL runs Modular: a single VPS, a managed container platform, or Kubernetes. Persistent storage is required for the media directory. For EU data residency, pick a region you control, nothing phones home.

Get the code

Clone the repository or unzip a release, then point your web server's document root at the public directory.

git clone https://github.com/modular-cms/modular.git
cd modular
composer install

Configuration

Copy the example config and set your database credentials. This is the one file you edit by hand.

cp admin/config/config.local.php.example admin/config/config.local.php

<?php
return [
    'db_host' => '127.0.0.1',
    'db_name' => 'modular',
    'db_user' => 'modular',
    'db_pass' => 'secret',
    'base_url' => 'https://cms.acme.eu',
];

Create the schema

Open /admin/setup in your browser and follow the wizard, which creates the schema and the first admin user. To skip the wizard, import the full schema directly and run migrations.

# option B: import the schema, then apply migrations
mysql modular < core/migrations/full_schema.sql
composer migrate

1. Create a post type

In the admin, open Post Types and create articles. Add a few fields with the field builder: a title (text, required), a body (wysiwyg) and an author (relationship). The slug is generated from the title.

2. Read it over the API

The public endpoint needs no auth, so a theme or external frontend can read published content directly.

curl "https://cms.acme.eu/api/v1/public/posts?type=articles"

3. Render it in a theme

<?php
$post = get_post(null, $slug);
$data = json_decode($post['data'] ?? '[]', true); ?>
<article>
  <h1><?= e($post['title']) ?></h1>
  <?= $data['body'] ?? '' ?>
</article>

The upgrade process

Back up the database, pull the new code, then run migrations. Always take a backup first and run the upgrade on staging before production.

# 1. back up the database first (mysqldump or your host's tool)
mysqldump modular > backup.sql

# 2. pull the new release and dependencies
git pull
composer install

# 3. apply schema + data migrations
composer migrate

Modules

Official modules declare the core version they require in their module.php header. After an upgrade, their migrations run when you re-activate them in the admin Modules screen. A module that requires a newer core stays inactive rather than loading against a mismatched pair.

Support policy

• Security fixes land on the current and previous major.
• Each major is supported for 18 months after the next major ships.
• Deprecations are announced one minor in advance and logged at runtime.

Fixed and modular post types

A post type runs in one of two modes. A fixed type has a strict, schema-driven set of fields, good for a known shape like a product or an author. A modular type lets editors compose a page from reusable components. The supports setting controls which core features (title, editor, thumbnail) a type carries.

Defining a post type

Most teams use the admin builder. To script it, create the post type with the PostType class and store the field definitions as schema JSON.

$pt = new \Modular\PostType($db);
$pt->create([
    'name'     => 'Articles',
    'slug'     => 'articles',
    'mode'     => 'fixed',
    'supports' => ['title', 'editor', 'thumbnail'],
    'public'   => true,
]);

Each field is one entry in the type's schema JSON, stored in component_definitions:

{
  "fields": [
    { "name": "body",   "type": "wysiwyg", "label": "Body" },
    { "name": "author", "type": "relationship", "label": "Author" }
  ]
}

Validation

Validation rules are declared on the field and enforced on every write, in the admin editor and over the authenticated API alike. See the validation reference.

The full set covers more than forty types, including code, embed, gallery, audio, video, checkbox, radio, button_group, date, time, range, currency, email, url, phone, password, taxonomy, color and layout helpers like tab, accordion, message and divider.

Relationship fields

A relationship is a field type, configured in the Post Types builder. Point an article's author field at the authors post type, and a single relationship can reference one or many related posts. There is no separate relation DSL: a relationship is just another field in the schema.

Resolving relations

The list endpoint returns the bare post rows. The single-post endpoint resolves relationship fields and the author server-side, so one request gives you the related data already expanded.

GET /api/v1/public/posts/field-notes-7?type=articles

{
  "id": 142,
  "slug": "field-notes-7",
  "title": "Field notes, no. 7",
  "author": { "id": 3, "name": "Lena Vos" },
  "content": {
    "related": { "type": "relationship", "data": [ { "id": 98, "title": "Field notes, no. 6" } ] }
  }
}

Built-in rules

Rules are declared on each field in its schema. They run server-side on every write.

{
  "fields": [
    { "name": "sku", "type": "text", "required": true, "unique": true, "pattern": "^[A-Z0-9-]+$" },
    { "name": "price", "type": "currency", "required": true, "min": 0 },
    { "name": "summary", "type": "textarea", "max": 280 },
    { "name": "status", "type": "select", "options": ["draft", "published"], "default": "draft" }
  ]
}

Error responses

A failed write returns 422 with a per-field error map you can render straight into a form.

{
  "message": "The given data was invalid.",
  "errors": {
    "sku": [ "sku must be unique" ],
    "price": [ "price must be at least 0" ]
  }
}

Custom rules

A module can hook validation and add its own checks, for example a VAT-number rule, with add_filter.

add_filter('validate_field', function ($errors, $field, $value) {
    if ($field['name'] === 'vat' && !vat_is_valid($value)) {
        $errors[] = 'Invalid VAT number';
    }
    return $errors;
}, 10, 3);

Uploading

Drop files into the Media library in the admin, or push them over the authenticated API. Each upload is stored once and referenced by id, so the same asset can appear in many posts without duplication.

curl -X POST https://cms.acme.eu/api/v1/media \
  -H "Authorization: Bearer $JWT" \
  -F "file=@cover.webp"

Referencing media in a theme

A post's featured image and any media fields are stored as ids. Resolve a URL with the media helpers.

<?php $coverId = get_post_thumbnail_id($post['id']); ?>
<img src="<?= esc_url(get_attachment_url($coverId)) ?>"
     alt="<?= e($post['title']) ?>">

Storage

Uploads are written to the media directory under public, served as static files. Put that directory on persistent storage so assets survive a redeploy.

Built-in blocks

• Headings, paragraphs, lists and quotes
• Images and galleries from the media library
• Code, tables and dividers
• Embeds and call-to-action blocks

How it serializes

The public single-post endpoint returns the blocks as an array of typed objects, predictable to traverse and safe to render on any client.

{
  "blocks": [
    { "type": "heading", "level": 2, "text": "Field notes" },
    { "type": "paragraph", "text": "We rebuilt our model…" },
    { "type": "image", "media": 88, "caption": "The new editor" }
  ]
}

Rendering in a theme

In a theme the blocks live in the post's component_data column. Decode it and render each block with a template part named for its type.

<?php
$blocks = json_decode($post['component_data'] ?? '[]', true);
foreach ($blocks as $block) {
    get_template_part('blocks/' . $block['type'], null, $block);
} ?>

Custom blocks

Define a new component type in the Post Types builder, then add a matching template part in your theme. Ship reusable components in a module to share them across projects.

Draft vs published

An entry can hold a published version and a separate working draft. The public endpoint serves published content only. To read a draft, request it over the authenticated admin API with a JWT.

curl https://cms.acme.eu/api/v1/posts/142 \
  -H "Authorization: Bearer $JWT"

History

Open any entry to see its timeline: who changed what, when. Restore a revision from the admin and it becomes a new revision, so nothing is ever lost.

States

A post's status moves it through the workflow: draft, review, scheduled and published. Status is a column on the post, so the same value drives the admin, the theme and the API.

Scheduling

Set published_at in the future and the entry goes live automatically when a scheduled task publishes due posts. Add a cron entry that runs the publisher script on your server.

* * * * * php /srv/modular/core/cron/publish-scheduled.php

Permission gates

Each transition is gated by a capability, so only the right roles can advance a post. Authors hold post:review but not post:publish; editors hold both. Capabilities are assigned to roles in the admin under Roles.

if (!current_user_can('post:publish')) {
    require_auth();   // blocks the transition
}

Reading published content

The public endpoints need no authentication. Pass the post type with type. The list endpoint returns up to 100 published posts; the single endpoint resolves relationships and the author.

# list
curl "https://cms.acme.eu/api/v1/public/posts?type=articles"

# single, resolved, by slug
curl "https://cms.acme.eu/api/v1/public/posts/field-notes-7?type=articles"

Response shape

Responses are not wrapped in a data envelope. The list endpoint returns the post type and an array of posts.

{
  "post_type": "articles",
  "posts": [
    { "id": 142, "slug": "field-notes-7", "title": "Field notes, no. 7", "status": "published", "published_at": "2026-03-12" }
  ]
}

There are no filter, fields, sort or pagination parameters: the list is capped at 100 and ordered by the server. Filtering happens in your theme or client.

Authenticated writes

Writes use the authenticated admin API. Obtain a JWT from POST /api/v1/auth/login, then send it as a Bearer token. Writes pass through validation and permissions.

curl -X POST https://cms.acme.eu/api/v1/posts \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"post_type":"articles","title":"Hello","status":"draft"}'

Reading content today

The public REST endpoints serve published content with no auth. The single-post endpoint resolves relationships and the author server-side, so nested data arrives in one request.

curl "https://cms.acme.eu/api/v1/public/posts?type=articles"

Response

{ "post_type": "articles", "posts": [ { "id": 142, "title": "Field notes, no. 7", "slug": "field-notes-7" } ] }

Why REST today

• REST is simple to cache, simple to consume, and already covers reading and writing every post type.
• GraphQL, when it lands, will suit clients that need deeply nested data in one round trip.

Structure

theme.json          # name, version
index.php           # homepage
single-article.php  # single article
archive-article.php # article listing
parts/
  header.php
  card.php
css/
  theme.css

Theme helpers

Query content with get_posts() and render each row with a template part. The post's custom fields live in its data column as JSON.

$posts = get_posts([
    'post_type'      => 'articles',
    'posts_per_page' => 12,
    'orderby'        => 'published_at',
    'order'          => 'DESC',
]);

foreach ($posts as $post) {
    get_template_part('parts/card', null, $post);
}

Routing

Modular maps a request to a template by post type and context: a single post renders single-{type}.php, a listing renders archive-{type}.php, and the home route renders index.php. Read the current post in a single template with get_post().

$post = get_post(null, $slug);
include_header();
get_template_part('parts/article', null, $post);
include_footer();

Querying

Rendering, URLs & output

Reading a field value

Custom field values are stored as JSON in the post's data column. Decode it once, then read fields by name.

$data   = json_decode($post['data'] ?? '[]', true);
$author = $data['author'] ?? null;
echo e($data['summary'] ?? '');

Layers

• Media transforms, generated once and written next to the original, so a resized image is computed a single time.
• Full-page cache, optional, for themed routes with no per-user state.

Configuration

Caching is configured in admin/config/config.local.php. Enable the page cache and set a default lifetime.

return [
    // ...
    'page_cache' => true,
    'cache_ttl'  => 3600,   // seconds
];

Invalidation

Publishing or updating a post clears the cached pages that reference it. To clear everything by hand, delete the contents of the cache directory; there is no separate CLI command for it.

Roles & capabilities

A role is a named set of capabilities, stored in the roles, capabilities and role_capabilities tables and managed in the admin under Roles. Common roles ship by default: admin, editor, author and viewer. Capabilities are plain strings like manage_options, post:create or post:publish.

Checking a capability

Anywhere in a theme or a module, ask the same question with current_user_can(). It takes a single capability string.

if (is_logged_in() && current_user_can('post:publish')) {
    // show the publish button
}

if (current_user_can('manage_options')) {
    // administrator-only settings
}

User sessions

The admin uses signed, http-only session cookies with CSRF protection. Password hashing uses PHP's password API. The public read API needs no authentication at all.

API tokens

For authenticated API access, exchange credentials for a JWT at POST /api/v1/auth/login, then send it as a Bearer token on subsequent requests. The token carries the user's role, so it inherits the same capabilities.

# 1. log in, receive a JWT
curl -X POST https://cms.acme.eu/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"me@acme.eu","password":"…"}'

# 2. use it
curl https://cms.acme.eu/api/v1/me \
  -H "Authorization: Bearer $JWT"

Secure defaults

• CSRF protection on every state-changing request
• Scoped, expiring API tokens
• Rate limiting on auth and write endpoints
• Security headers (HSTS, X-Frame-Options, CSP scaffold)
• Argon2id password hashing

Headers & CSP

Set the security headers in admin/config/config.local.php. Force HTTPS, send HSTS, and add a Content-Security-Policy scaffold.

return [
    // ...
    'force_https' => true,
    'hsts'        => true,
    'csp'         => "default-src 'self'",
];

Activity log

The activity log is a core system module. Every sign-in, permission change and destructive action is recorded with the user behind it, viewable in the admin and available in the database for export to your SIEM.

Why not plugins?

Open plugin ecosystems trade control for volume: a dozen competing options for the same job, uneven quality, abandoned code and the security surface that comes with it. Modules take the opposite stance.

• One module per job. We develop a single official module for each capability, held to one standard.
• API-first and fully wired. Every module integrates through the core, permissions, migrations and the headless API included.
• Reviewed, or it does not ship. Anyone can build a module, but until it meets our requirements and we approve it, it is unsupported and never appears in your install.

Official modules

How modules are funded

Some modules are commercial. Built and maintained by Atypisch, paid modules fund Modular's open-source core, so the platform itself stays free and open, for good.

Add a module

Place the module folder under public/modules, then open the admin Modules screen and activate it. Activation sets the module active and runs any migrations it ships, no command line involved.

# place the module, then activate it in admin → Modules
public/modules/seo/module.php
public/modules/seo/...

Manage

The Modules screen lists every module under public/modules with its status. Activate or deactivate from there; deactivating runs the module's module_deactivate hook. Remove a module by deleting its folder.

Configuration

A module exposes its settings in the admin once it is active. The SEO module, for example, takes a default title suffix and a sitemap toggle from its own settings panel, stored in the database rather than a config file.

Configuration

Place the module in public/modules/seo and activate it in the admin Modules screen. Defaults, like the title suffix and robots directive, are set in the module's settings panel and stored in the database. Everything else is managed per entry in the admin.

Per-entry SEO and the theme head

With the module active, an SEO panel is added to every post type: title, description, social image and indexing controls, with fallbacks from your content. In a theme, the head reads those values through filters.

<title><?= e(apply_filters('seo_meta_title', $post['title'] ?? '', $post)) ?></title>
<meta name="description" content="<?= e(apply_filters('seo_meta_description', '', $post)) ?>">

Sitemaps

A sitemap is generated and kept current as you publish, available at /sitemap.xml with no configuration. Add your own entries with the seo_sitemap_entries filter.

add_filter('seo_sitemap_entries', function ($entries) {
    $entries[] = ['loc' => base_url('/specials'), 'lastmod' => date('Y-m-d')];
    return $entries;
});

Redirects

Manage redirects in the admin or import them in bulk. The module also captures changed slugs automatically so old links keep working.

Locales

Activate the module in the admin Modules screen, then set your locales, the default and the fallback in its settings panel. The intl PHP extension is required.

Translatable fields

Mark a field translatable in the Post Types builder and the editor shows a tab per locale. Untranslated fields fall back to the default locale automatically.

{
  "fields": [
    { "name": "title", "type": "text",    "translatable": true },
    { "name": "body",  "type": "wysiwyg", "translatable": true }
  ]
}

Reading a locale

Pass locale to the public single-post endpoint to get the post in that language, with untranslated fields filled from the default locale.

curl "https://cms.acme.eu/api/v1/public/posts/field-notes-7?type=articles&locale=de"

Roles per locale

Give translators a role with translation capabilities and scope them to the locales they own, so they can edit those languages and nothing else. Roles and capabilities are managed in the admin under Roles.

Member accounts

Visitors register, sign in and manage a profile. Members are a collection like any other, so they relate to your content and respect permissions.

Comments

The module adds its features as actions on the core hook system. A handler reads the signed-in member, validates the input and returns JSON. Nothing custom is needed in the core.

add_action('community_post_comment', function () {
    $member = get_current_user();
    $entry  = (int) ($_POST['entry_id'] ?? 0);
    $body   = trim((string) ($_POST['body'] ?? ''));

    // validate, store, then return JSON
    echo json_encode(['success' => true, 'data' => ['id' => 9]]);
});

Every handler returns { "success": true, "data": { … } }. Members call the action with their own scoped token.

Moderation

Comments carry a status and can be hidden or removed from the admin. Reported content routes to a moderation queue.

What the module provides

Activating the module registers a set of member-facing actions through the hook system, each backed by its own tables.

Anatomy

A public module is a folder under public/modules with a module.php entry file. Its metadata lives in a PHP docblock header at the top of that file.

module.php          # header + hook registrations
migrations/
  001_events.sql    # run on activation
views/
  panel.php         # admin UI

Registering

Declare the module in the header docblock, then wire it up with add_action and add_filter.

<?php
/**
 * Module Name: Acme Events
 * Version: 1.0.0
 * Description: Adds an events post type.
 * Author: Acme
 * Requires PHP: 8.1
 * Requires Modular: 1.0
 */

add_action('init', function () {
    // register routes, post types, admin pages
});

add_filter('the_title', fn($t) => $t);

Core hooks include init, module_activate, module_deactivate, admin_menu, the_title, the_content, public_routes, public_fixed_routes and seo_sitemap_entries. System modules instead ship a module.json manifest under core/system/{slug}.

The review bar

To be approved, supported and listed, a module must:

• Be API-first, every feature reachable over the REST API.
• Integrate with permissions, validation and migrations, no side doors.
• Pass the security review.
• Ship docs and a maintenance commitment.

Submitting

Test the module against a local install by dropping it in public/modules and activating it, then submit it for review through the project's repository. An unreviewed module runs only in your own install.

Running migrations

Apply pending migrations with Composer's script, or run the migration runner directly.

composer migrate                    # apply pending
# or, equivalently:
php core/migrations/migrate.php

Most model changes you make in the admin Post Types builder are applied directly. For schema changes that need version control, add a migration file by hand.

Writing one by hand

A migration is a SQL file in core/migrations, applied in order and tracked so it runs once.

ALTER TABLE posts
  ADD COLUMN summary TEXT NULL;

Production checklist

• Point the web root at public; keep admin/config/config.local.php out of version control.
• Set force_https in the config and terminate TLS at your reverse proxy.
• Run composer migrate on deploy.
• Schedule database backups with mysqldump and test a restore.
• Put the media directory on persistent storage.

Web server

Any PHP host with MySQL runs Modular: a VPS, shared hosting or a managed PHP platform. Point the document root at public and route requests through its front controller. A typical Nginx site looks like this.

server {
  root /srv/modular/public;
  index index.php;

  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
}

Creating a backup

A backup is the database plus the media directory. Use mysqldump for the data and copy the media folder.

mysqldump modular > modular-2026-05-18.sql
tar czf media-2026-05-18.tgz public/media

Restoring

mysql modular < modular-2026-05-18.sql
tar xzf media-2026-05-18.tgz

Scheduling

Run the backup from cron and rotate old files. This nightly job dumps the database and prunes dumps older than two weeks.

0 3 * * * mysqldump modular > /backups/modular-$(date +\%F).sql
0 4 * * * find /backups -name '*.sql' -mtime +14 -delete

The config file

Copy the example, set your values, and keep the real file out of version control.

<?php
return [
    'db_host'     => '127.0.0.1',
    'db_name'     => 'modular',
    'db_user'     => 'modular',
    'db_pass'     => 'secret',
    'base_url'    => 'https://cms.acme.eu',
    'force_https' => true,
    'page_cache'  => true,
];

Per environment

Each environment keeps its own config.local.php with its own database credentials and base URL. The rest of the codebase is identical, so promoting between environments changes only this one file.

Start with the basics

Most problems trace back to the config file, the database connection or a missing PHP extension. Confirm admin/config/config.local.php exists and has the right credentials, and check that migrations have run.

composer migrate              # apply any pending migrations
php -m | grep -E 'pdo|mbstring|gd'   # confirm extensions

Common issues

Logs

Application errors go to the PHP error log for your web server. Security and editorial events are recorded by the activity log system module and viewable in the admin.