Building Your First Plugin

This is the "Plugins" category's starting point — a hands-on tutorial. Once you're through it, the rest of the category covers each piece in depth: Plugin Basics for the manifest and lifecycle, Hooks & the Plugin Lifecycle and Filters for extending the CMS, Admin Integration and Front-End Integration for actually doing something useful, and Data Storage & Security plus Distributing a Plugin for shipping it.

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, 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 a piece of furniture you bring in only if you need it. Don't need a bookshelf? Don't install it.

In SynaptikCMS, a plugin is simply a folder inside /plugins/. It contains its own PHP files, its own data storage, and optionally its own admin page. It never touches core CMS files.

A few real examples built this way: Newsletter (email signup with a digest sender), Redirects (301/302 URL redirects), Booking (appointment calendar with admin approval).

Each is self-contained. Deleting the folder removes the plugin completely — no leftover database rows, because there's no database.

---

Why not just add these features to the core?

Most CMS platforms fall into one of two traps: ship every possible feature by default (slow, bloated, confusing settings), or require a database and heavy dependencies for even basic extensions. SynaptikCMS is built to be fast and lightweight above everything else — a flat-file CMS with no database at all. Plugins let every site stay exactly as light as it needs to be.

---

How does a plugin actually work?

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

1. plugin.json is the ID card. A small file telling SynaptikCMS "I'm a real plugin, here's my name." Without it, the folder is ignored entirely.
2. Installed ≠ switched on. A plugin sits inactive until you click Activate. You're always in control of what code actually runs.
3. A plugin can add its own admin sidebar page, appearing right alongside Dashboard, Content, Settings.
4. A plugin's data stays in its own folder, separate from your articles and pages. Deactivating preserves it; deleting removes it permanently (SynaptikCMS asks you to deactivate first, as a safety check).

---

Building your first plugin

Let's build the simplest plugin imaginable: a "Hello, Admin!" page in the sidebar. It demonstrates every piece you need.

What you'll need: access to your SynaptikCMS files (FTP, or locally), a text editor, about 10 minutes.

Step 1 — Create your plugin's folder

Inside /plugins/, create a folder. Its name becomes your plugin's identifier — short, lowercase, hyphens instead of spaces:

/plugins/hello-admin/

Step 2 — Create the manifest: plugin.json

{
    "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"
}

Field	What it's for
synaptik_plugin	Must always be true
name	Shown in Admin → Extensions
slug	Unique ID — match your folder name
version	Whatever you want, for your own tracking
entry	The main PHP file to load first

Step 3 — Create the entry file

hello-admin-init.php, in the same folder:

<?php
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',
            'Hello Admin',
            hello_admin_page_url(),
            '<circle cx="12" cy="12" r="10"/><path d="M8 12h8M12 8v8"/>'
        );
    });
}

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: "{slug}_render_admin_page" (hyphens → underscores)
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

1. Zip the hello-admin folder (the ZIP must contain the folder itself, not just the loose files)
2. Admin → Extensions → Upload the ZIP
3. Click Activate

"Hello Admin" now appears in your sidebar.

---

Where to go from here

This barely scratches the surface, but shows the two things every plugin needs: a manifest and an entry file that hooks into the admin. From here, a plugin can grow to store its own JSON data, add a shortcode, add settings forms, or read your published content — see the rest of this category for hooks, filters, the options API, and security patterns.

The Newsletter and Redirects plugins are open-source — reading real, working code is often the fastest way to learn.