Developer Handbook

1. System Requirements

2. Repository Layout Highlights

app/                 Application code (controllers, config, libraries, filters)
modules/             Feature modules (Auth, Backend, Blog, etc.)
public/
  index.php          Front controller
  be-assets/         Admin UI build artifacts (CSS/JS)
  templates/         Front-end themes (default shipped)
  media/             Media storage (ensure writable)
writable/            Cache, logs, temporary files (must be writable)
vendor/              Composer packages
.docker/             Dockerfile, Apache vhost, and php.ini
.github/workflows/   GitHub Actions CI pipeline
docs/                Developer documentation (this file and companions)

Key config files:

• composer.json — PHP dependencies and scripts.
• app/Config/DefaultRoutes.php — Routes template; copy to Routes.php on setup.
• app/Config/Paths.php — Path constants including $supportDirectory (required by CI4 4.4+).
• app/Config/*.php — Framework configuration; many classes consume cached settings populated at runtime.
• .env — Environment overrides; generated from the env template.

3. Getting Started

3.1 Standard (local PHP)

1. Clone & install

   git clone <repo-url> ci4ms
   cd ci4ms
   composer install

2. Environment

   cp env .env

   Update: app.baseURL, database.default.*, mail credentials, etc.

3. Prepare routes

   cp app/Config/DefaultRoutes.php app/Config/Routes.php

4. One-command setup

   php spark ci4ms:setup

   This single command runs all migrations, seeds default data (admin user, sample pages, settings), and prepares the application.

5. Serve

   php spark serve

3.2 Docker

cp env .env
cp app/Config/DefaultRoutes.php app/Config/Routes.php
# Edit .env: set database.default.hostname=db
docker compose up -d --build
docker exec ci4ms_app composer install
docker exec ci4ms_app php spark ci4ms:setup

Refer to DOCKER_SETUP.md for full configuration details.

4. Dependency Management

composer install
composer update vendor/package
composer outdated

5. Coding Guidelines

• Namespaces: PSR-4 via Composer. Modules live under Modules\<Name>, app code under App\.
• Controllers: Backend controllers extend Modules\Backend\Controllers\BaseController; frontend extends App\Controllers\BaseController.
• Views: Stored per module (Modules\Blog\Views\list etc.).
• Helpers/Filters: Keep helpers/filters modular; app/Config/Filters discovers them dynamically.
• Configuration: Module-specific configs live in modules/<Module>/Config.
• Translations: Use modules/<Module>/Language/<locale>. 11 languages are currently supported.
• Testing: Run composer test; add linting tooling if desired.

6. Modules & Permissions

Permissions are stored in auth_permissions_pages (CRUD JSON flags) and auth_users_permissions (overrides). The Modules\Methods\Controllers\Methods::moduleScan() command inspects routes and helps keep permissions in sync.

Workflow for a new module:

1. Scaffold with php spark make:module <Name> (provided by ext_module_generator).
2. Define routes in modules/<Name>/Config/Routes.php with role metadata.
3. Implement controllers, models, views.
4. Update permissions (run module scan or insert records manually).
5. Create migrations/seeds for new tables if required.

Clear cached permissions with php spark cache:clear or cache()->delete("{userId}_permissions").

7. Configuration & Settings Cache

• Settings: Stored in the settings table and cached for 24h. Clear via cache()->delete('settings').
• Canonical decode: The settings key can be warmed by whichever entry point hits it first while it is cold (app/Config/Filters.php, the generated app/Config/Routes.php, or modules/Auth/Controllers/BaseController.php). Every filler must use the same decode — json_decode($value) gated on json_last_error() === JSON_ERROR_NONE && (is_object($decoded) || is_array($decoded)) — so a cold cache always warms to a consistent stdClass shape. Read nested settings with object access ($settings->group->key); only JSON-array levels stay PHP arrays and remain foreach-iterable. Never (object) json_decode(...)-cast the top level: nested levels stay arrays and the mixed shape fatals under PHP 8. Scalar flags such as maintenanceMode and convertWebp are read as raw strings, not through a ->scalar wrapper.
• Backend cache panel: Settings → "Cache Management" clears individual keys through the server-side allowlist Modules\Settings\Libraries\CacheRegistry. Adding a new clearable cache means adding an entry there (logical id, label key, and its exact/glob operations) — the client only ever sends the logical id.
• Menus: Cached as menus_{locale} (per-locale); automatically refreshed when editing via the Menu module.
• Maintenance mode: Controlled by settings.maintenanceMode; triggers redirect in App\Filters\Ci4ms.

8. Media, File, & Theme Handling

9. Public Assets & Front Controller

• public/index.php bootstraps CodeIgniter; production servers should expose only public/.
• public/maintenance/ serves the maintenance splash when enabled.
• public/be-assets/ houses admin CSS/JS, images, plugins, and package manifests.
• public/media/ contains uploaded media (include in backups).
• public/templates/default/ is the bundled theme—use it as a blueprint for custom themes.

10. Testing & QA

• Unit tests live under tests/. Add module-specific tests in tests/Modules/<Module>.
• The GitHub Actions workflow (.github/workflows/docker-test.yaml) runs on every push:
  • Builds the Docker image.
  • Runs composer install.
  • Executes php spark ci4ms:setup.
  • Syntax checks across app/ and modules/.
  • Validates HTTP responses for homepage and backend.
• Use maintenance mode to hide upcoming changes during manual QA.

Testing against the live schema without touching it

There is no separate test database: CommonModel hardcodes the default connection group, so a test that exercises a real query-builder path runs against your development database. Two patterns keep that non-destructive — use whichever fits:

• Marker-scoped rows. Write only rows carrying a per-run marker (a random type value, a throwaway high user id), assert counts as deltas so unrelated existing rows cannot skew them, and delete exactly those rows in tearDown(). Never mutate a pre-existing row.
• Shadow tables (CREATE TEMPORARY TABLE). When a test needs a schema the development database does not have — a column or table added by a migration that has not run there — do not run the migration. Create a TEMPORARY table of the same name on the same connection the production code uses: in MySQL/MariaDB a temporary table masks a permanent one of the same name for that connection only, so the real schema is never altered, real rows are neither read nor written, and the shadow disappears when the connection closes.

Rules that make the shadow safe:

• tearDown() still drops it explicitly, always with the TEMPORARY keyword — which makes the statement a no-op against a permanent table.
• Foreign keys are omitted: temporary tables cannot carry them, which is also what lets such tests address throwaway user ids.
• If the MySQL user lacks CREATE TEMPORARY TABLES, skip the test rather than weakening it.
• Any request-scoped schema memoisation (e.g. Modules\Notifications\Libraries\SchemaGuard) must be reset both when a shadow is created and when it is dropped; otherwise a stale true leaks into later test classes and they emit SQL for columns the real table does not have.

tests/_support/Notifications/ShadowSchemaTrait.php implements the technique — including a pre-migration variant used to assert fail-closed behaviour — and assertPermanentSchemaIntact() proves the shadow never leaked into real DDL.

11. Debugging Tips

• Enable the debug toolbar via CI_ENVIRONMENT=development.
• Logs reside in writable/logs/; ensure permissions allow writing or inspect them via the backend viewer at /backend/logs.
• Clear cache via php spark cache:clear or delete contents of writable/cache/.
• Migration issues? Check logs and the ci_migrations table for batch sync.
• Mail issues? Trigger the AJAX Test Mail button in Settings after configuring SMTP.
• Docker issues? Run docker compose logs app to inspect container output.

12. Security Architecture

CI4MS implements modern security practices to protect the application and user data:

• CSRF Protection: Enabled globally. For AJAX requests, public/be-assets/js/ci4ms.js automatically reads the CSRF token from the meta tag and injects it into all AJAX requests. Do not disable CSRF per module unless absolutely necessary.
• XSS & HTML Sanitization: Content editors utilize CustomRules::getClean() to scrub HTML through HTMLPurifier. Dangerous schemes like data: and properties like CSS.Trusted are disabled by default.
• File System Integrity: The Fileeditor module enforces strict blacklisting for executable extensions (.php, .phtml, .phar, etc.) to prevent Remote Code Execution (RCE). Operations are restricted strictly to safe paths using realpath() boundary validations.

13. Notifications Module (Developer Guide)

Modules\Notifications is a drop-in HMVC module that renders a bell dropdown in the admin header and a list page at backend/notifications. Producing modules never write to the database directly: every notification flows through one service, and every read passes through one relevance chokepoint.

13.1 Sending a notification

Resolve the shared service with service('notifier') and use the fluent builder. Nothing else is required — the in-app channel writes the row and invalidates the unread-badge caches.

// Notify a single user
service('notifier')
    ->notify('comment.new')                // machine-readable event type
    ->title('New comment awaiting moderation')
    ->body('A visitor commented on "Hello World".')
    ->url('/backend/blog/comments')        // site-relative or http(s) only
    ->severity('info')                     // info | warning | critical
    ->toUser(5)
    ->dispatch();

// Notify every member of a Shield group (one row; membership resolved on read)
service('notifier')
    ->notify('update.available')
    ->title('A new platform update is available')
    ->severity('warning')
    ->toGroup('superadmin')
    ->dispatch();

• Several toUser() / toGroup() directives may be combined; each survivor becomes one global row and identical directives are deduplicated. broadcast() overrides every other target.
• exceptUser(int|array) excludes ids from every row of the dispatch, broadcast() included, and wins over toUser().
• createdBy(?int) records who produced the notification — pass a server-derived id such as auth()->id(). It is an audit trail, not a target, so it changes no delivery decision.
• via(string ...$channels) selects channels; the default is ['inapp', 'realtime'].
• Sanitisation is centralised in the NotificationMessage DTO — do not repeat strip_tags or URL validation in your caller. Lengths are clamped in characters (mb_substr) to match the max_length validation rule.

13.2 Was it actually delivered?

dispatch() returns a ChannelResult[]. Do not read that array as "any result is ok, therefore it was sent": under Model B only a channel that persists a row has delivered anything. Wrap the results in DispatchOutcome instead.

$outcome = DispatchOutcome::fromResults(
    service('notifier')->notify('announcement')
        ->title('Scheduled maintenance')
        ->toGroup('superadmin')
        ->dispatch()
);

$outcome->attempted();     // durable rows attempted
$outcome->stored();        // durable rows actually written
$outcome->isComplete();    // every attempted row stored (and at least one was)
$outcome->isPartial();     // some stored, some refused
$outcome->storedNothing(); // nothing stored, incl. "no durable channel ran"
$outcome->refusals();      // ['exclusion-unsupported', 'insert-failed', ...]

A partial result must never be reported to an operator as success. The back-compat wrappers Notifier::toUser() / toRole() and php spark notifications:test still use the old "any channel ok" predicate — treat their return value as "a delivery was attempted", never as "a row exists".

13.3 The applyRelevance() rule

Notifier::applyRelevance() is the single relevance and IDOR chokepoint. It layers three filters in order — target, row-level exclusion, per-user preference — and all four existing read paths (unreadCount, listFor, markAllRead, isRelevant) go through it.

If you add a new read path, it must call applyRelevance(). Do not re-implement any of the three layers in a controller, a view, or a channel:

• A hand-written target predicate is an IDOR waiting to happen — group membership is resolved at read time, so a query that forgets the group leg either leaks or silently drops rows.
• The exclusion filter relies on the sentinel-wrapped CSV shape (,5,12,); a LIKE written by hand without the wrapping commas matches the wrong ids.
• The preference anti-join keeps n.severity <> 'critical' on the join's ON side; moving it into WHERE would make critical notifications mutable and would let countAllResults() be inflated by several matching mute rows.

The same rule holds for the transport: Notifier::topicsFor() is the mirror of applyRelevance() used by the SSE stream, so realtime channels are derived from the session and never from the client.

13.4 Adding a channel

A channel is any class implementing Libraries\Channels\ChannelInterface:

public function send(NotificationMessage $message): ChannelResult;

If your channel persists the notification — an ok result means a record will still be there when the user reconnects — implement Libraries\Channels\DurableChannelInterface instead. It extends ChannelInterface and adds no methods; that marker is what DispatchOutcome counts. A channel that forgets it is treated as transient, so the mistake under-reports delivery rather than over-reporting it.

Register the channel from your own module the same way Filters.php discovers $csrfExcept — declare it on Config/{Name}Config.php:

public array $notificationChannels = [
    'slack' => \Modules\MyModule\Libraries\Channels\SlackChannel::class,
];

Notifier::resolveChannels() scans every modules/*/Config/{Module}Config.php, and a module-declared slug overrides the base map. Opt a notification into it with ->via('inapp', 'slack').

13.5 Realtime and the ext-redis version trap

Realtime SSE is optional and disabled by default (notificationsconfig.realtimeEnabled; note the env prefix is the lowercased short class name, so notificationsconfig. and not notifications.). It reuses the Redis connection from Config\Cache::$redis — there is no separate connection setting — and needs ext-redis (phpredis).

phpredis must be installed for the PHP version that actually serves the site, not merely "somewhere on the machine". This costs more debugging time than anything else in the module:

• It is a compiled extension tied to PHP's ABI. The extension_dir carries the API number (.../pecl/20240924 = PHP 8.4, .../pecl/20250925 = PHP 8.5), and a redis.so in the wrong directory is never loaded.
• On a multi-version install pecl install redis builds against whichever php-config is first on the PATH, which is easily not the one FPM runs.
• Nothing errors, because everything degrades gracefully: RealtimeSignal becomes a no-op, the connection registry cannot reserve a slot, the stream answers 429 (fail-closed), and the bell quietly stays on 60s polling.
• Verify with the real binary, not the shell's php alias: /path/to/the/fpm/php -m | grep redis. The CLI matters too — the Redis-backed tests skip rather than fail when the extension is absent, so a green suite is not evidence that realtime works in the browser.

13.6 Registering the permissions

Permission strings are derived from the route's as name, not from the controller class: Modules\Methods\Libraries\ModuleScanner stores pagename = '{Module}.{route name}' and Ci4MsAuthFilter then checks strtolower(pagename) . '.{action}'. Registration is not a spark command — run Backend → Methods / Modules → Module Scan, then php spark cache:clear.

Until a route has a record in auth_permissions_pages it is fail-closed 403 for everyone, superadmin included — the superadmin bypass only applies once the page record exists.

14. Session Geo Lookup (Local, Opt-In)

Login sessions can be enriched with an approximate city / region / country resolved entirely against a local DB-IP City Lite database (MMDB). The visitor's IP address never leaves the server and no third-party request is made — this replaced an inline ip-api.com HTTP call.

• Library: Modules\Auth\Libraries\GeoLocator reads the MMDB file through maxmind-db/reader. It returns null on any failure, so a missing or corrupt database can never break login — a lesson from the crash it replaced, where a failed fetch returned false and json_decode(false) raised an uncaught TypeError under declare(strict_types=1) (the @ operator does not suppress a TypeError).
• Call site: Modules\Auth\Models\UserSessionModel::recordLogin().
• Gate: the Auth.geoLookupEnabled setting (config default false), exposed as the Settings → "Session Location Tracking" toggle (route saveGeoLookup; AJAX + role=update + CSRF + in_list validation) and as an opt-in checkbox in the web installer. Behaviour change on upgrade: existing installations stop collecting geo data until an administrator enables the setting and downloads the database.
• Database file: lives outside the web root under writable/geoip/ and is downloaded or refreshed with php spark ci4ms:geoip-update — the command gunzips, verifies with a test lookup, and atomically renames into place. It is flock-guarded against concurrent runs and is designed to be scheduled as a monthly cron job.
• Attribution: DB-IP data is CC BY 4.0 and requires attribution; the credit is surfaced in the README, the installer hint, and the command output.
• The UI warns when the toggle is enabled while the database file is still missing.

15. Migrations & Schema Guards

Schema and ledger can drift apart — a partial dump restore, a ledger reset, or a manual ALTER leaves a column present while its row in the migrations table is missing. The runner then sees the migration as pending, re-runs it, and MySQL rejects it (error 1060, Duplicate column name). Because the ledger row can never be written, every subsequent run aborts at the same point and every later migration in the batch is blocked.

Rules for a schema-altering migration:

• Guard addColumn() with fieldExists() and return early when the column is already there, so the run records the migration and moves on.
• Guard table creation with tableExists(), or use CI4's own createTable($table, true) (CREATE TABLE IF NOT EXISTS).
• Supply an after clause only when the anchor column actually exists — MySQL rejects the whole ALTER for an unknown anchor.
• When a foreign-key target may be absent, log a warning and create the object without the constraint rather than failing the run.
• Keep down() non-destructive for objects that carry data: document the reverse ALTER / DROP as a manual step in a comment instead of executing it.
• Guarded migrations are behaviour-neutral on a consistent database, so there is no downside to adding the check.

For code that must run before its migration has been applied, pair the guard with a runtime capability check. The Notifications module's SchemaGuard memoises per request — keyed by database name plus table prefix, so a second DB group cannot inherit the answer — whether an optional column or table exists, and the dependent SQL is simply not emitted when it does not. Long-running workers must call SchemaGuard::reset() after a migration.

16. Deployment Checklist

1. Switch to CI_ENVIRONMENT=production.
2. Set the public app.baseURL.
3. Point the web server root to public/; restrict other directories.
4. Run migrations/seeds (php spark migrate --all, relevant seeders).
5. Optional cache warm-up via scripted requests.
6. Proxy IPs: If behind Cloudflare or Nginx, configure App.php::$proxyIPs with trusted IP ranges (see commented examples in the file) so $request->getIPAddress() returns real client IPs.
7. Disable the debug toolbar in production.
8. Set secure permissions (775/664 depending on user/group).
9. Back up uploads, database, and .env before major upgrades.
10. Realtime notifications (optional). The Redis-backed SSE bell is self-contained — no external hub, JWT, or nginx config change. To enable it: install ext-redis for the PHP version that serves the site, point Config\Cache::$redis at a reachable Redis, set the notificationsconfig.* env keys (realtimeEnabled = true, plus the optional realtimeStreamTtl / realtimeSignalTtl / realtimeConnCapDefault / realtimeConnCapByGroup.superadmin), register the stream route as a permission (notifications.realtimecontroller.read — the same permission the read endpoints use) via the Methods module scan, then php spark cache:clear. Because each open stream holds a short-lived php-fpm worker for up to realtimeStreamTtl seconds (120s ceiling), size pm.max_children for concurrent admins times their connection cap and keep PHP max_execution_time / FPM request_terminate_timeout above realtimeStreamTtl. Left disabled (the default), the bell keeps its 60s polling behaviour.
11. Notification upgrade steps. After php spark migrate --all has added notifications.exclude_users / notifications.created_by and created notification_preferences, run the Methods Module Scan so the preference and composer routes land in auth_permissions_pages, grant them deliberately (the send permission is the right to broadcast to the whole installation), then php spark cache:clear. Until the migrations run the module still delivers ordinary notifications, but a dispatch carrying an explicit exceptUser() exclusion is refused rather than delivered to an excluded user.

17. Contribution Workflow

• Branching: Prefix with scope (e.g., feature/blog-scheduling).
• Commits: Reference modules/issues ([Blog] Add scheduling support).
• Pull requests: Note migrations, env vars, npm steps.
• Reviews: Highlight permission changes, cache impacts, and CHANGELOG.md updates.
• Changelog: Update CHANGELOG.md (Keep a Changelog format) before merging.

18. Further Reading & Resources

• CodeIgniter 4 Documentation
• Composer Docs
• CI4MS Architecture Guide (Markdown)
• CI4MS User Guide (HTML)
• Notifications Module README (Markdown)

Update this handbook whenever the stack or workflows evolve so the team always has a current source of truth.