Docs 1
Home GitHub
menu_book Navigation menu
Documentation Advanced Development Extensions

Extensions

Overview

Pragma CMS is built on a modular architecture. An Extension is a self-contained package that adds specific features (e.g., Blog, E-commerce, SEO tools) to a site. Extensions are isolated within the site’s directory, ensuring that the CMS core remains lightweight and clean.

Bundled & Free Extensions

To maintain a "lean" core while providing immediate value, Pragma CMS treats major publishing features as official extensions.

Articles & Blog

The Articles & Blog extension is a complete publishing suite (supporting Categories, Tags, Archives, and Single posts). It is 100% free and is systematically proposed during the Site Creation Wizard on the Admin Platform.

If you choose not to install it during the initial setup, it remains available for a one-click installation at any time via the Extensions Marketplace.

By decoupling the Blog from the CMS core, Pragma CMS ensures that corporate or "app-only" websites remain free of unnecessary blogging code and database tables, while content-heavy sites can enable it instantly.

Extension Architecture

Each extension follows a strict directory structure to participate in the CMS's cascading resource system.

Directory Structure

Extensions are located in /sites/[site-handle]/extensions/[extension-name]/.

  • manifest.json: The identity of the extension. Contains name, version, author, and dependencies.
  • modules/: Contains the business logic, organized by sub-modules (API, CRUD, Database migrations, Lang, and Pages).
  • resources/: Holds the frontend assets, content-type schemas, and templates.
  • config.php: Global configuration specific to the extension.
  • functions.php: Helper functions exposed by the extension.
  • hooks.php: The entry point for registering event listeners (Hooks::addAction, Hooks::addFilter).
  • install.php / uninstall.php: Scripts executed during the lifecycle changes to handle database schema creation or cleanup.

The Extension Lifecycle

The CMS provides a complete management API to handle the lifecycle of an extension directly from the Admin Marketplace.

1. Discovery & Installation

Administrators can browse the Marketplace via the UI. When an installation is triggered:

  1. API Check: The CMS connects to the Pragma Central API to verify the License Key and retrieve extension metadata.
  2. Integrity Verification: The package is downloaded as a ZIP. The CMS performs a SHA256 hash check to ensure the file was not corrupted or tampered with during transit.
  3. Extraction: The files are extracted into the site's extensions/ directory.
  4. Install Script: The install.php script is executed to initialize the database or filesystem requirements.

2. Dependency Management

Pragma CMS enforces strict stability rules:

  • Activation Requirement: An extension cannot be enabled if its dependencies (listed in manifest.json) are missing or inactive.
  • Version Matching: The CMS checks that the installed version of a dependency meets the minimum required version.
  • Cascading Deactivation: To prevent system crashes, an extension cannot be disabled if other active extensions depend on it.

3. Atomic Updates & Rollback

Updates are handled using an Atomic Pattern to ensure the site never stays in a broken state:

  1. Maintenance Mode: The site is placed in maintenance mode (maintenance.flag).
  2. Backup: The current version of the extension is moved to a temporary backup directory.
  3. Deployment: The new version is extracted.
  4. Update Script: The update.php script handles database migrations.
  5. Automatic Rollback: If any part of the process fails, the CMS automatically deletes the new files and restores the backup version, then notifies the administrator.

4. Uninstallation

Uninstallation is destructive and requires the extension to be disabled first.

  1. Dependency Check: Verification that no other extension relies on this one.
  2. Cleanup Script: uninstall.php is executed to drop tables or remove specific data.
  3. Filesystem Cleanup: The extension directory is recursively deleted.

Developer API: Extension Manager

Developers can programmatically check extension states or trigger management logic using the ExtensionManager class.

Checking State

PHP 
// Check if an extension is currently enabled for the site
if (ExtensionManager::isExtensionActive('blog')) {
    // Execute blog-specific logic
}

Loading Assets from Extensions

When building templates, you should use the core helper to resolve asset paths correctly, even if the extension is moved or updated.

PHP 
// Resolves to: /assets/extensions/my-plugin/resources/assets/css/style.css
$cssPath = getAssetsPath("css/style.css", extensionName: "my-plugin");

Technical Security

  • CSRF Protection: Every action (Install, Toggle, Update) is protected by a mandatory CSRF token check.
  • Permission Enforcement: Managing extensions requires a specific permission key (usually manage_extension).
  • Execution Isolation: Extension scripts (install.php, update.php) are included within the CMS context but encouraged to use anonymous functions or classes to avoid global namespace pollution.