ddev-cmsms

A DDEV add-on that turns a CMS Made Simple extension repository (module, plugin, or theme) into a full, disposable CMSMS dev site. It downloads the official CMSMS installer, drives it headlessly (no browser wizard), symlinks your extension into a running core, and installs it — all from ddev start. The core lives in a gitignored .cmsms/ directory next to your extension source, so the repo you’re developing stays clean.

Requirements

• DDEV v1.24.0 or newer — new to DDEV? Follow the installation guide first; it also installs everything below.
• A Docker provider supported by DDEV (Docker Desktop, OrbStack, Colima, …).

Everything else (PHP, MariaDB, the CMSMS core itself) runs inside DDEV’s containers — nothing CMSMS-related is installed on your machine.

Quickstart

cd my-module/
mkdir -p .cmsms/public
ddev config --project-type=php --docroot=.cmsms/public
ddev add-on get dearaujoj/ddev-cmsms
ddev cmsms setup
ddev start
ddev launch        # frontend; `ddev cmsms admin` opens /admin (admin/admin)

Admin credentials default to admin / admin. Override them with the CMSMS_ADMIN_USER / CMSMS_ADMIN_PASSWORD environment variables before the first install (see Configuration).

Starting from an empty directory

No code yet? The same flow works — ddev cmsms setup notices the empty repo and generates a starter for you (or run ddev cmsms scaffold explicitly):

mkdir my-module && cd my-module
mkdir -p .cmsms/public
ddev config --project-type=php --docroot=.cmsms/public
ddev add-on get dearaujoj/ddev-cmsms
ddev cmsms setup --type module --name MyModule --yes   # scaffolds MyModule.module.php & co.
ddev start                                             # installs CMSMS with your new module live

Workspace mode: several extensions, one site

Developing modules that depend on each other (plus plugins, or the admin theme that showcases them)? Make the project root a workspace — one subdirectory per extension, named after it. Subdirectories can be separate git clones, submodules, or plain folders in a monorepo; the add-on doesn’t care:

my-suite/
├── ModuleA/ModuleA.module.php
├── ModuleB/ModuleB.module.php      # GetDependencies() → ModuleA
└── MyTags/function.mytag.php

ddev config --project-type=php --docroot=.cmsms/public
ddev add-on get dearaujoj/ddev-cmsms
ddev cmsms setup                    # detects the subdirs, proposes the list
ddev start                          # installs the site with ALL of them linked

The list lives in .ddev/config.cmsms-project.yaml as CMSMS_EXTENSIONS=module:ModuleA module:ModuleB plugin:MyTags — order is install order, so list dependencies before dependents. Grow the workspace with ddev cmsms add module ModuleC (scaffolds the subdir if missing), check everything with ddev cmsms status, and package one module with ddev cmsms package ModuleA. A failing entry (missing directory, failed registration) is warned and skipped — it never breaks ddev start. If you list several theme: entries, the last one becomes the active admin theme.

Commands

Setup validates --name against ^[A-Za-z0-9_]+$ and --version against a dotted-numeric pattern; invalid values are rejected with an error before anything is written.

The install pipeline itself (fetch → files → db → link) runs automatically via a post-start hook (ddev cmsms-install all), and each stage is idempotent — safe to re-run individually with ddev cmsms-install <stage> for debugging.

Configuration

Extension identity and target CMSMS version live in .ddev/config.cmsms-project.yaml, written by ddev cmsms setup (edit it by hand and ddev restart if you prefer):

Other environment variables, settable via .ddev/config.cmsms-project.yaml’s web_environment block or any other DDEV env mechanism:

Using a local installer zip

Have the installer on disk (offline work, betas, or cores you built yourself)? Load it — the version is derived from the zip’s payload, and versions.json is bypassed entirely for that version:

ddev cmsms load ~/Downloads/cmsms-2.2.23-install.zip --use
ddev restart && ddev cmsms reinstall --yes   # if the project was already installed

Without --use, the zip just lands in .ddev/cmsms/cache/ and you select it with ddev cmsms setup --version 2.2.23. Power users can also drop a correctly named cmsms-<version>-install.zip into .ddev/cmsms/cache/ by hand, or point CMSMS_INSTALLER_URL at any http(s):// or file:// URL reachable from inside the web container. A loaded zip for the configured version always wins over CMSMS_INSTALLER_URL.

Testing against another core / PHP version

# another CMSMS core
edit .ddev/config.cmsms-project.yaml   # change CMSMS_VERSION
ddev restart && ddev cmsms reinstall --yes

# another PHP
ddev config --php-version=8.1 && ddev restart

Supported core versions are the keys of cmsms/versions.json, regenerated with scripts/update-versions.sh (scrapes the CMSMS Forge file listing). CI verifies 2.2.22 (PHP 8.3 and 8.1), 2.2.21, and 2.2.19 on every push and weekly on a schedule (to catch download-URL rot); other listed versions are expected to work but aren’t continuously tested — see .github/workflows/tests.yml.

Xdebug

ddev xdebug on

Set a single IDE path mapping from your repository root to /var/www/html — the CMSMS core (.cmsms/public) lives inside the repo, so this one mapping covers breakpoints in both your extension code and core files.

Mail

Mailpit is preconfigured — the installed site’s mail preferences point at localhost:1025 (SMTP) out of the box. View captured mail with:

ddev launch -m

How it works

CMSMS’s official installer is a self-extracting phar that runs a browser wizard and explicitly refuses to run non-interactively from the CLI. ddev-cmsms sidesteps the wizard entirely: it extracts the phar’s bundled core and installer app, then includes the installer’s own app/install/*.php scripts (schema, base data, admin account, content, system modules) directly inside a small PHP driver that reconstructs the scope and globals they expect — the same steps the wizard’s wizard_step8/wizard_step9 perform, without a browser in the loop.

Your extension isn’t copied into the core. Modules and themes-at-repo-root get an individual symlink per top-level file/directory into modules/<Name>/ or admin/themes/<Name>/, skipping a configurable exclusion list (.ddev, .cmsms, .git, etc.) — per-entry linking, rather than symlinking the whole repo root in one shot, is what avoids a symlink cycle (the core lives inside .cmsms/, which lives inside the repo being linked). Plugins link only their function.*.php/modifier.*.php files into plugins/. A theme that lives in its own subdirectory is simpler: the whole subdirectory gets a single symlink into admin/themes/<Name>/, since it can’t contain .cmsms/ itself.

The .cmsms/ directory (downloaded core, installer scratch space, generated config.php) is disposable and gitignored automatically by the add-on’s post-install hook, so it never pollutes your extension’s repository.

Troubleshooting

• Installer download fails: set CMSMS_INSTALLER_URL to a working direct cmsms-X.Y.Z-install.zip URL (mirror or local file) and re-run.
• Install partially completed / left in a bad state: ddev cmsms-install all is safe to re-run — every stage (fetch, files, db, link) checks its own completion marker and skips work already done.
• Not sure what’s installed or linked: ddev cmsms status reports the core version and configured extension in one shot; for module projects it also reports symlink state and DB registration.
• Need a database GUI: this add-on depends on ddev/ddev-phpmyadmin — run ddev phpmyadmin to open it.

Contributing

PRs welcome — see CONTRIBUTING.md for the test requirements (CI enforces that implementation changes come with tests), how to run the bats suites locally, and the portability conventions.

Credits / License

Built for CMS Made Simple extension developers on top of DDEV.

Licensed under the Apache License 2.0.