Guide to SynaptikCMS Plugins

If you've been using SynaptikCMS for a while, you've probably noticed that the core stays intentionally small. No bloat, no features you'll never use, nothing slowing down your site. But sometimes you need something extra — a newsletter signup, a booking calendar, custom redirects — without bolting it onto the core and making every SynaptikCMS site heavier because of it.

That's exactly what plugins are for.

This guide explains what plugins are, how they work under the hood (in plain terms, no computer science degree required), and walks you through building the simplest possible plugin from scratch — even if you've never written PHP before.

What is a plugin, exactly?

Think of your CMS like an empty house. The core is the foundation, walls, and roof — solid, and the same for everyone. A plugin is like a piece of furniture you bring in only if you need it. Don't need a bookshelf? Don't install it. Your house stays light and easy to move around.

In SynaptikCMS, a plugin is simply a folder that lives inside /plugins/. It contains its own PHP files, its own data storage, and optionally its own admin page. It doesn't touch the core CMS files at all.

A few real examples already built this way:

Newsletter — lets visitors sign up for email updates, with a simple admin page to compose and send them
Redirects — lets you redirect an old URL to a new one, so you never lose visitors (or Google ranking) when you rename a page
Booking — an evolved appointment/calendar system with configurable availability, email notifications to the admin AND the client, along with ICS calendar files to add appointments to your calendar in one click
Maintenance — puts up a maintenance page for visitors while you keep working on the site as a logged-in admin

Each one is self-contained. Deleting the folder removes the plugin completely — no leftover clutter in your database, because there is no database (SynaptikCMS stores everything in simple JSON files, remember?).

Why not just add these features to the core?

Good question, and it's the whole philosophy behind SynaptikCMS.

Most CMS platforms fall into one of two traps: either they ship every possible feature by default (slow, bloated, confusing settings pages), or they require a database and heavy dependencies for even basic extensions. SynaptikCMS was built to be fast and lightweight above everything else — a flat-file CMS with no database at all.

If we added a newsletter system, a booking calendar, and every other feature someone might want directly into the core, every single SynaptikCMS site would carry that weight — even sites that will never use it. Plugins let you keep your site exactly as light as you need it. Only install what you actually use.

How does a plugin actually work?

You don't need to understand this to use a plugin — installing one is as simple as uploading a ZIP file from Admin → Tools → Extensions. But if you're curious, here's the short version.

1. Every plugin has an ID card: `plugin.json`

This is a small text file that tells SynaptikCMS "hey, I'm a real plugin, here's my name and where to find me." Without this file, SynaptikCMS ignores the folder entirely — this is what keeps the system safe from random folders being mistaken for plugins.

2. Plugins are installed but not automatically switched on

After uploading a plugin, it sits there inactive until you click Activate in Admin → Extensions. This is deliberate: you're always in control of what code actually runs on your site.

If a plugin needs its own settings page (like the Newsletter plugin's subscriber list), it can register itself in the admin sidebar. You'll see it appear right alongside Dashboard, Content, and Settings.

4. Plugins keep their data to themselves

Each plugin stores its own data (subscriber lists, redirect rules, whatever it needs) inside its own folder, completely separate from your articles, pages, and projects. Deactivating a plugin doesn't erase its data — so if you turn it back on later, everything is exactly where you left it. Deleting it permanently does remove that data, so SynaptikCMS will ask you to deactivate first as a safety check.

Building your first plugin

Let's build the simplest plugin imaginable: one that adds a small "Hello, Admin!" page to your admin sidebar. It won't do anything fancy, but it demonstrates every piece you need — and once you understand this, you can grow it into something more useful.

What you'll need

Access to your SynaptikCMS files (via FTP, or locally if you're developing on your own machine)
A text editor (VS Code, Sublime Text, or even Notepad — anything that saves plain text files)
About 10 minutes

Step 1 — Create your plugin's folder

Inside /plugins/, create a new folder. The name matters — it becomes your plugin's unique identifier, so keep it short, lowercase, and use hyphens instead of spaces:

/plugins/hello-admin/

Step 2 — Create the manifest: `plugin.json`

This is the ID card we mentioned earlier. Create a file called plugin.json inside your new folder:

{
    "synaptik_plugin": true,
    "name": "Hello Admin",
    "slug": "hello-admin",
    "version": "1.0.0",
    "description": "A minimal example plugin that adds a greeting page to the admin sidebar.",
    "author": "Your Name",
    "entry": "hello-admin-init.php"
}

A quick word on each field:

Field	What it's for
`synaptik_plugin`	Must always be `true` — this is how SynaptikCMS recognizes a real plugin
`name`	The friendly name shown in Admin → Extensions
`slug`	Your plugin's unique ID — should match your folder name
`version`	Whatever you want, used for your own tracking
`description`	A short sentence explaining what it does
`entry`	The main PHP file SynaptikCMS should load first (we'll create this next)

Step 3 — Create the entry file

This is the file SynaptikCMS actually runs when your plugin is active. Create hello-admin-init.php in the same folder:

<?php
/**
 * Hello Admin — Init
 *
 * Registers a simple admin sidebar page. This is the minimum any plugin
 * needs to appear inside the CMS admin.
 */

// Prevents this file from being loaded twice in the same request
if (defined('HA_INIT_LOADED')) return;
define('HA_INIT_LOADED', true);

// Register our page in the admin sidebar menu
if (function_exists('pl_on_admin_menu')) {
    pl_on_admin_menu(function () {
        pl_register_admin_menu(
            'hello-admin',                 // must match your plugin's slug
            'Hello Admin',                 // label shown in the sidebar
            hello_admin_page_url(),        // where clicking it should go
            '<circle cx="12" cy="12" r="10"/><path d="M8 12h8M12 8v8"/>' // a simple icon (optional)
        );
    });
}

/**
 * Builds the URL to our plugin's admin page.
 */
function hello_admin_page_url(): string
{
    $baseUrl = function_exists('getBaseUrl') ? getBaseUrl() : '/';
    return $baseUrl . 'admin/index.php?action=plugin_page&slug=hello-admin&view=dashboard';
}

/**
 * The contract SynaptikCMS expects: a function named
 * "{slug}_render_admin_page" (with hyphens turned into underscores)
 * that returns the page title and HTML to display.
 */
function hello_admin_render_admin_page(string $view): array
{
    return [
        'title' => 'Hello Admin',
        'html'  => '<div class="site-settings-section"><p>Hello, Admin! This is your first SynaptikCMS plugin. 🎉</p></div>',
    ];
}

That's genuinely it. Two files, and you have a working plugin.

Step 4 — Activate it

Zip your hello-admin folder (make sure the ZIP contains the folder itself, not just the loose files inside it)
Go to Admin → Extensions
Upload the ZIP
Click Activate

You should now see "Hello Admin" appear in your admin sidebar. Click it, and there's your message.

Where to go from here

This example barely scratches the surface, but it shows you the two things every plugin needs: a manifest (plugin.json) and an entry file that hooks into the admin. From here, a plugin can grow to:

Store its own data in JSON files (the same flat-file approach the CMS core uses)
Add a shortcode visitors can use in articles or pages, like [my_plugin_thing]
Add settings forms, buttons, tables — anything regular HTML and PHP can do
Talk to the CMS's own content (for example, reading your published articles)

If you want to see these ideas in action, the Newsletter and Redirects plugins are both open-source and available in the Downloads section — reading real, working code is often the fastest way to learn.

Got stuck?

Browse the full Plugin System documentation for the complete technical reference
Ask a question or share what you built in the GitHub Discussions
Found a bug in this guide? Let us know on GitHub

Happy building!

Tags: