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').
• Menus: Cached as menus; 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.

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. 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. Disable the debug toolbar in production.
7. Set secure permissions (775/664 depending on user/group).
8. Back up uploads, database, and .env before major upgrades.

13. 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.

14. Further Reading & Resources

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

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