Update all guides (NL + EN) for CodePress 2.5.2 features
- Admin guide: RBAC roles, role-based dashboard, plugin types (content/system) - CodePress developer guide: plugin types, admin plugin API, SCSS compilation, asset serving - Theme developer guide: SCSS sole CSS source, css_compiled read-only, guide layout - Content manager guide: layout selection from theme.json, plugin order in frontmatter - Both NL and EN updated with identical structure - 35 files updated
This commit is contained in:
@@ -1,11 +1,84 @@
|
||||
# CMS Architecture
|
||||
|
||||
CodePress is a file-based CMS without a database. Content, configuration and users are stored in files.
|
||||
|
||||
## Folder structure
|
||||
|
||||
```
|
||||
codepress/
|
||||
├── cms/core/ # Core engine
|
||||
├── admin/ # Admin console
|
||||
├── themes/ # Themes
|
||||
├── plugins/ # Plugins
|
||||
├── content/ # Content
|
||||
└── public/ # Web root
|
||||
```
|
||||
├── cms/ # Core CMS engine
|
||||
│ ├── core/
|
||||
│ │ ├── class/
|
||||
│ │ │ ├── CodePressCMS.php # Main CMS class (routing, rendering, breadcrumb)
|
||||
│ │ │ ├── ThemeManager.php # Theme resolver + Twig render + SCSS compile
|
||||
│ │ │ ├── ContentAPI.php # Read-only API for PHP content
|
||||
│ │ │ ├── ContentSecurityPolicy.php # CSP header management
|
||||
│ │ │ ├── Analytics.php # Visitor statistics
|
||||
│ │ │ ├── BotGuard.php # Bot/AI detection
|
||||
│ │ │ ├── Cache.php # Cache system
|
||||
│ │ │ ├── GeoIP.php # GeoIP lookup (country, flag)
|
||||
│ │ │ ├── Logger.php # Basic logging
|
||||
│ │ │ ├── LogManager.php # Dynamic logging (SQLite/syslog)
|
||||
│ │ │ ├── RateLimiter.php # Rate limiting per IP
|
||||
│ │ │ ├── RequestLogger.php # Request logging + visitor info
|
||||
│ │ │ ├── SearchEngine.php # Full text search
|
||||
│ │ │ └── AccessibilityManager.php # Accessibility features
|
||||
│ │ ├── plugin/
|
||||
│ │ │ ├── PluginManager.php # Plugin loader (hooks, filters, sidebar, admin routes)
|
||||
│ │ │ └── CMSAPI.php # API for plugins (getPage, getConfig, etc.)
|
||||
│ │ ├── config.php # Config loader (reads config.json)
|
||||
│ │ └── index.php # Bootstrap (autoloader, requires)
|
||||
│ ├── lang/ # Language files (nl.php, en.php)
|
||||
│ └── router.php # PHP dev server router
|
||||
├── themes/ # Dynamic themes
|
||||
│ └── default/ # Default theme (views + assets)
|
||||
│ ├── theme.json # { title, config.default_template, template: layout→.twig }
|
||||
│ ├── base.twig # Main layout
|
||||
│ ├── *.twig # Layout templates
|
||||
│ ├── partials/ # header.twig, navigation.twig, footer.twig
|
||||
│ └── assets/
|
||||
│ ├── scss/theme.scss # SCSS source (only CSS source)
|
||||
│ ├── css_compiled/ # Generated by scssphp (read-only)
|
||||
│ ├── css/ # External CSS (bootstrap.min.css, etc.)
|
||||
│ ├── js/ # JavaScript
|
||||
│ └── img/ # Images
|
||||
├── admin/ # Admin panel
|
||||
│ ├── config/
|
||||
│ │ ├── app.php # Admin app configuration
|
||||
│ │ └── admin.json # Users & security (file-based, .gitignore'd)
|
||||
│ ├── src/
|
||||
│ │ └── AdminAuth.php # Authentication + RBAC
|
||||
│ ├── theme/default/ # Admin theme (views + assets)
|
||||
│ │ ├── theme.json
|
||||
│ │ ├── assets/ # CSS, JS, CodeMirror, fonts
|
||||
│ │ └── views/ # login.twig, layouts/, pages/
|
||||
│ └── storage/ # Logs, cache, geoip
|
||||
├── plugins/ # CMS plugins
|
||||
│ ├── Navigation/ # Essential navigation plugin (protected)
|
||||
│ │ ├── Navigation.php # Plugin code (NOT plugin.php)
|
||||
│ │ ├── plugin.json # Metadata with type field
|
||||
│ │ └── assets/ # SCSS + CSS
|
||||
│ └── HTMLBlock/ # Example sidebar plugin
|
||||
├── content/ # Website content (.md, .php, .html) — .gitignore'd
|
||||
├── guide/ # Guides (nl/en)
|
||||
├── public/ # Web root
|
||||
│ ├── index.php # Website entry point
|
||||
│ ├── admin.php # Admin entry point + routing
|
||||
│ ├── asset.php # Asset server for Apache (themes/, admin/assets/, plugins/)
|
||||
│ ├── .htaccess # Forwards asset URLs to asset.php
|
||||
│ ├── favicon.ico
|
||||
│ └── robots.txt
|
||||
├── var/ # Cache (twig) — .gitignore'd
|
||||
├── config.json # Site configuration — .gitignore'd
|
||||
├── composer.json # PHP dependencies (CommonMark, Twig, scssphp)
|
||||
└── version.php # Version information (2.5.2)
|
||||
```
|
||||
|
||||
## Principles
|
||||
|
||||
- **No database** — Everything in files (content in `content/`, users in `admin/config/admin.json`, config in `config.json`)
|
||||
- **File-based auth** — `AdminAuth` uses bcrypt hashes in `admin.json`, sessions for login
|
||||
- **Twig templating** — Themes use Twig; `ThemeManager` renders via Twig
|
||||
- **SCSS compilation** — `assets/scss/theme.scss` → `assets/css_compiled/theme.css` via scssphp (read-only output)
|
||||
- **Plugin system** — `PluginManager` loads content and system plugins with hooks/filters
|
||||
- **Asset serving** — PHP dev router (`cms/router.php`) or Apache (`.htaccess` → `public/asset.php`)
|
||||
@@ -10,6 +10,13 @@ $cms->init();
|
||||
$cms->renderPage($pagePath);
|
||||
```
|
||||
|
||||
Responsibilities:
|
||||
- Routing and page rendering
|
||||
- Breadcrumb generation (dynamic: Home > [subfolders] > [page])
|
||||
- Loading guide pages (`getGuidePage()`)
|
||||
- Title extraction from H1 (`getTitleFromFile()`)
|
||||
- Display name processing (`formatDisplayName()`)
|
||||
|
||||
## ThemeManager.php
|
||||
|
||||
Theme management in `cms/core/class/ThemeManager.php`:
|
||||
@@ -19,14 +26,84 @@ $themeManager = new ThemeManager($config);
|
||||
$themeManager->getActiveTheme();
|
||||
$themeManager->renderTwig($template, $data);
|
||||
$themeManager->compileCss($force);
|
||||
$themeManager->getCssUrl();
|
||||
```
|
||||
|
||||
Responsibilities:
|
||||
- Resolving the active theme from `config.json`
|
||||
- Loading `theme.json` (title, config.default_template, template mapping)
|
||||
- Building the Twig environment (rooted in the theme folder)
|
||||
- **SCSS compilation** — compiles `assets/scss/theme.scss` to `assets/css_compiled/theme.css` via scssphp
|
||||
- Resolving the layout to a `.twig` template (fallback to `config.default_template`)
|
||||
|
||||
`getCssUrl()` priority: 1) `assets/css/theme.css` (manual), 2) `assets/css_compiled/theme.css` (compiled).
|
||||
|
||||
## PluginManager.php
|
||||
|
||||
Plugin system in `cms/core/class/PluginManager.php`:
|
||||
Plugin system in `cms/core/plugin/PluginManager.php`:
|
||||
|
||||
```php
|
||||
$pluginManager = new PluginManager();
|
||||
$pluginManager->loadPlugins($enabledPlugins);
|
||||
$pluginManager = new PluginManager($pluginsPath, $enabledPlugins);
|
||||
$pluginManager->getSidebarContent($allowedPlugins);
|
||||
$pluginManager->getPluginCssUrls();
|
||||
$pluginManager->executeHook($name, $params);
|
||||
```
|
||||
$pluginManager->getAdminMenuItems();
|
||||
$pluginManager->handleAdminRoute($route);
|
||||
$pluginManager->getPluginType($pluginName);
|
||||
```
|
||||
|
||||
Responsibilities:
|
||||
- Loading plugins from `plugins/` folders (only enabled plugins)
|
||||
- Plugin file: `<PluginName>.php` (NOT `plugin.php`)
|
||||
- Hooks and filters system (`doAction`, `applyFilters`)
|
||||
- Collecting sidebar content from content plugins (`getSidebarContent`)
|
||||
- Collecting plugin CSS URLs (`getPluginCssUrls`)
|
||||
- **Admin menu items** from system plugins (`getAdminMenuItems`)
|
||||
- **Admin routes** handled via system plugins (`handleAdminRoute`)
|
||||
- Determining the **plugin type** (`getPluginType` — `content` or `system`)
|
||||
- `isPluginViewable` — system plugins do not appear in the sidebar
|
||||
|
||||
## AdminAuth.php
|
||||
|
||||
Authentication and RBAC in `admin/src/AdminAuth.php`:
|
||||
|
||||
```php
|
||||
$auth = new AdminAuth($appConfig);
|
||||
$auth->login($username, $password);
|
||||
$auth->logout();
|
||||
$auth->hasPermission($route);
|
||||
$auth->verifyCsrf($token);
|
||||
```
|
||||
|
||||
Constants:
|
||||
- `ROLE_PERMISSIONS` — Mapping of role → allowed route prefixes. `admin` has wildcard `*`.
|
||||
- `ROLE_LABELS` — Human-readable labels per role.
|
||||
|
||||
Roles:
|
||||
|
||||
| Role | Label | Permissions |
|
||||
|------|-------|-------------|
|
||||
| `admin` | Admin | Everything (`*`) |
|
||||
| `content-manager` | Content Manager | Content management, guide |
|
||||
| `bi-manager` | BI Manager | Statistics, logs, guide |
|
||||
| `site-admin` | Site Admin | Theme, plugins, statistics, logs, update, guide |
|
||||
|
||||
Responsibilities:
|
||||
- Session-based authentication
|
||||
- bcrypt password hashing
|
||||
- CSRF tokens (`verifyCsrf`)
|
||||
- Brute-force lockout (login attempts tracking)
|
||||
- RBAC via `hasPermission($route)` — checks the route against `ROLE_PERMISSIONS`
|
||||
|
||||
## CMSAPI.php
|
||||
|
||||
Plugin API in `cms/core/plugin/CMSAPI.php`:
|
||||
|
||||
```php
|
||||
$api = PluginManager::getAPI();
|
||||
$config = $api->getConfig();
|
||||
$page = $api->getPage($path);
|
||||
$content = $api->getContent();
|
||||
```
|
||||
|
||||
Provides read-only access for plugins to CMS data (config, pages, content).
|
||||
@@ -1,43 +1,144 @@
|
||||
# Plugin Development
|
||||
|
||||
## Plugin types
|
||||
|
||||
CodePress has two kinds of plugins, determined by the `type` field in `plugin.json`:
|
||||
|
||||
- **Content plugins** (`type: "content"`) — Appear in the sidebar and in the plugin selection on content-edit pages. Provide sidebar content via `getSidebarContent()`.
|
||||
- **System plugins** (`type: "system"`) — Are loaded by PluginManager but do NOT appear in the sidebar. Provide functionality via admin menu, routes and the CMSAPI.
|
||||
|
||||
When no `type` field is present, `content` is assumed.
|
||||
|
||||
## Plugin structure
|
||||
|
||||
```
|
||||
plugins/MyPlugin/
|
||||
├── plugin.json # Plugin metadata
|
||||
├── plugin.php # Plugin code
|
||||
└── config.json # Optional configuration
|
||||
├── MyPlugin.php # Plugin code (NOT plugin.php)
|
||||
├── plugin.json # Metadata with type field
|
||||
├── config.json # Optional configuration
|
||||
└── assets/
|
||||
├── scss/myplugin.scss # SCSS source (optional)
|
||||
└── css/myplugin.css # CSS (manually maintained)
|
||||
```
|
||||
|
||||
Plugin files are named `<PluginName>.php` (e.g. `Navigation.php`, `HTMLBlock.php`). `PluginManager` loads `$pluginDir . '/' . $pluginName . '.php'`.
|
||||
|
||||
## plugin.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Plugin",
|
||||
"version": "1.0.0",
|
||||
"author": "Your Name",
|
||||
"description": "Description"
|
||||
"name": "My Plugin",
|
||||
"version": "1.0.0",
|
||||
"author": "Your Name",
|
||||
"description": "Description",
|
||||
"type": "content"
|
||||
}
|
||||
```
|
||||
|
||||
## plugin.php example
|
||||
- `name` — Display name
|
||||
- `type` — `"content"` or `"system"` (default: `content`)
|
||||
|
||||
## Content plugin example
|
||||
|
||||
```php
|
||||
<?php
|
||||
/**
|
||||
* Plugin: MyPlugin
|
||||
* Plugin: MyPlugin (content)
|
||||
*/
|
||||
class MyPlugin
|
||||
{
|
||||
public function getConfig(): array
|
||||
{
|
||||
return [
|
||||
'title' => 'My Plugin',
|
||||
'type' => 'content',
|
||||
];
|
||||
}
|
||||
|
||||
echo '<div class="my-plugin">Hello World</div>';
|
||||
public function getSidebarContent(): string
|
||||
{
|
||||
return '<p>Hello World</p>';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## System plugin example
|
||||
|
||||
```php
|
||||
<?php
|
||||
/**
|
||||
* Plugin: MySystem (system)
|
||||
*/
|
||||
class MySystem
|
||||
{
|
||||
public function getConfig(): array
|
||||
{
|
||||
return [
|
||||
'title' => 'My System',
|
||||
'type' => 'system',
|
||||
];
|
||||
}
|
||||
|
||||
public function getAdminMenu(): array
|
||||
{
|
||||
return [
|
||||
['label' => 'My System', 'route' => 'my-system', 'icon' => 'bi-gear'],
|
||||
];
|
||||
}
|
||||
|
||||
public function getAdminRoutes(): array
|
||||
{
|
||||
return ['my-system'];
|
||||
}
|
||||
|
||||
public function handleAdminRoute(string $route): void
|
||||
{
|
||||
echo '<h1>My System page</h1>';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
System plugins are shown in the admin sidebar via `PluginManager::getAdminMenuItems()` and handled via `PluginManager::handleAdminRoute()`.
|
||||
|
||||
## Using CMSAPI
|
||||
|
||||
```php
|
||||
<?php
|
||||
require_once '../../cms/core/class/PluginManager.php';
|
||||
|
||||
$api = PluginManager::getAPI();
|
||||
$config = $api->getConfig();
|
||||
$content = $api->getContent();
|
||||
```
|
||||
$page = $api->getPage($path);
|
||||
```
|
||||
|
||||
`setAPI()` is called automatically by `PluginManager` if the plugin has the method.
|
||||
|
||||
## Plugin CSS
|
||||
|
||||
- Plugin CSS in `assets/css/` is manually maintained (SCSS compilation for plugins is not yet automatic)
|
||||
- Plugin CSS is automatically loaded after theme CSS (in `base.twig`), so themes can override plugin styling
|
||||
- Plugin assets are served via `cms/router.php` at URL `/plugins/<Name>/assets/...`
|
||||
- Implement `getCssUrl()` in the plugin class to return the CSS URL
|
||||
|
||||
```php
|
||||
public function getCssUrl(): string
|
||||
{
|
||||
return '/plugins/MyPlugin/assets/css/myplugin.css';
|
||||
}
|
||||
```
|
||||
|
||||
## Hooks and filters
|
||||
|
||||
PluginManager auto-registers these methods as hooks/filters:
|
||||
|
||||
- **Hooks**: `onPageLoad`, `onBeforeRender`, `onAfterRender`, `onSearch`, `onMenuBuild`
|
||||
- **Filters**: `onContentFilter`, `onTitleFilter`, `onMenuFilter`
|
||||
|
||||
```php
|
||||
public function onPageLoad($page) { /* ... */ }
|
||||
public function onContentFilter($content) { return $content; }
|
||||
```
|
||||
|
||||
## Essential plugins
|
||||
|
||||
Essential plugins are defined in `getProtectedPlugins()` in `public/admin.php`. Current essential plugin: **Navigation**.
|
||||
|
||||
These plugins cannot be deactivated, edited or deleted. Always add the `isProtectedPlugin()` check to new plugin handlers.
|
||||
@@ -2,18 +2,60 @@
|
||||
|
||||
## Frontend routing
|
||||
|
||||
Via `cms/router.php` for PHP dev server:
|
||||
Frontend routing goes through `cms/router.php` (PHP dev server) or `.htaccess` (Apache). Both provide clean URLs.
|
||||
|
||||
```php
|
||||
// Clean URLs: /nl/page
|
||||
// Query: ?page=page&lang=nl
|
||||
### PHP dev server
|
||||
|
||||
Start the server with:
|
||||
|
||||
```bash
|
||||
php -S localhost:8080 cms/router.php
|
||||
```
|
||||
|
||||
`cms/router.php` serves:
|
||||
- Clean URLs: `/nl/page` → `public/index.php?page=page&lang=nl`
|
||||
- `themes/` assets
|
||||
- `admin/assets/` assets
|
||||
- `plugins/` assets
|
||||
|
||||
### Apache (live server)
|
||||
|
||||
`public/.htaccess` rewrites URLs to `public/index.php`. Asset URLs (`/themes/`, `/admin/assets/`, `/plugins/`) are forwarded to `public/asset.php`.
|
||||
|
||||
`public/asset.php` serves files from the correct folders with the correct MIME type:
|
||||
- `/themes/<name>/assets/...` → `themes/<name>/assets/...`
|
||||
- `/admin/assets/...` → `admin/theme/default/assets/...`
|
||||
- `/plugins/<name>/assets/...` → `plugins/<name>/assets/...`
|
||||
|
||||
## Admin routing
|
||||
|
||||
Via `public/admin.php`:
|
||||
Admin routing goes through `public/admin.php` with clean URLs:
|
||||
|
||||
```
|
||||
/admin/dashboard → ?route=dashboard
|
||||
/admin/content → ?route=content
|
||||
/admin/plugins → ?route=plugins
|
||||
```
|
||||
|
||||
`cms/router.php` or `.htaccess` converts `/admin/<route>` to `?route=<route>`.
|
||||
|
||||
### Route access control (RBAC)
|
||||
|
||||
Each route is checked via `AdminAuth::hasPermission($route)`:
|
||||
- The `admin` role has wildcard `*` access
|
||||
- Other roles have an explicit list of allowed routes in `ROLE_PERMISSIONS`
|
||||
- Unauthorized routes return a **403 error**
|
||||
|
||||
## Plugin admin routing
|
||||
|
||||
System plugins can register admin routes. These are handled by `PluginManager::handleAdminRoute($route)`:
|
||||
|
||||
1. The system plugin registers routes via `getAdminRoutes()`
|
||||
2. `PluginManager::getAdminMenuItems()` collects admin menu items via `getAdminMenu()`
|
||||
3. On an admin request `PluginManager::handleAdminRoute($route)` finds a plugin that handles the route
|
||||
4. The plugin method `handleAdminRoute($route)` renders the page content
|
||||
|
||||
```php
|
||||
// Routes: /admin/dashboard, /admin/content, etc.
|
||||
// Query parameter: ?route=dashboard
|
||||
// PluginManager calls this for /admin/my-system
|
||||
$plugin->handleAdminRoute('my-system');
|
||||
```
|
||||
Reference in New Issue
Block a user