README

Note: This library is under active development, some of the listed features are still experimental and subject to change. Large parts of the documentation are missing.

Bootstrapping

Use Duon\Cms\App for regular CMS applications. It creates the config, core app, and CMS plugin internally, installs the default error handler, adds CMS routes, and registers the catchall route when you call run().

use Duon\Cms\App;
use Duon\Cms\Locales;

$app = App::create(dirname(__DIR__), [
    'app.name' => 'mycms',
    'session.enabled' => true,
]);

$locales = new Locales();
$locales->add('en', title: 'English', pgDict: 'english');
$app->load($locales);

$app->section('Content')->collection(\App\Cms\Collection\Pages::class);
$app->node(\App\Cms\Node\HomePage::class);

$app->run();

The CMS app exposes the common CMS configuration API (section(), collection(), node(), renderer(), icons()) and the common core app API (load(), middleware(), get(), post(), routes(), run()). Use core() or plugin() only when you need the lower-level APIs directly.

Defining content types

Content types (nodes) are plain PHP classes annotated with attributes. There is no base class to extend. Dependencies are autowired from the Registry via duon/wire.

use Duon\Cms\Field\Text;
use Duon\Cms\Field\Grid;
use Duon\Cms\Field\Image;
use Duon\Cms\Cms;
use Duon\Cms\Schema\Label;
use Duon\Cms\Schema\Required;
use Duon\Cms\Schema\Route;
use Duon\Cms\Schema\Translate;
use Duon\Cms\Node\Contract\Title;
use Duon\Core\Request;

#[Label('Department'), Route('/{title}')]
final class Department implements Title
{
    public function __construct(
        protected readonly Request $request,
        protected readonly Cms $cms,
    ) {}

    #[Label('Title'), Required, Translate]
    public Text $title;

    #[Label('Content'), Translate]
    public Grid $content;

    #[Label('Image')]
    public Image $clipart;

    public function title(): string
    {
        return $this->title?->value()->unwrap() ?? '';
    }
}

Derived behavior

Metadata attributes

Hierarchy lists in panel

• Set showChildren to true on a collection to switch its list endpoint to hierarchy mode.
• Root requests (GET /panel/api/collection/{collection}) return nodes with no parent.
• Child requests (GET /panel/api/collection/{collection}?parent=<uid>) return direct children for that parent uid.
• Row payload includes hasChildren, childBlueprints, and parent.
• Child create options are derived from #[Children(...)] declarations.

Behavioral interfaces

Rendering by uid

Render a node by uid from templates with the neutral cms API:

<?= $cms->render('some-node-uid') ?>

Boiler rendering

duon/cms bundles the Boiler renderer under the existing Duon\Cms\Boiler namespace and registers it as the default view renderer. You do not need to require duon/cms-boiler separately or register a renderer for the common case.

By default, views are loaded from {path.root}{path.views}. path.root is the project root passed to App::create(). path.views defaults to /views and can be overridden in CMS config:

use Duon\Cms\App;

$app = App::create(dirname(__DIR__), [
    'path.views' => '/views',
]);

To replace the default renderer or pass custom Boiler arguments, register a view renderer before the app boots:

use Duon\Cms\App;
use Duon\Cms\Boiler\Renderer;

$app = App::create(dirname(__DIR__), [
    'app.name' => 'mycms',
]);
$app->renderer('view', Renderer::class)->args(
    dirs: __DIR__ . '/custom-views',
    defaults: ['siteName' => 'My Site'],
);

Duon\Cms\App installs the bundled error handler by default. Error pages use a dedicated Boiler renderer, so replacing the CMS view renderer does not affect error rendering. Project templates named http-error.php and http-server-error.php in {path.root}{path.views} override the built-in fallback templates. Set error.enabled to false if you want to install custom PSR-15 error middleware yourself.

For advanced integrations, the bundled error integration remains available as Duon\Cms\Boiler\Error\Handler. Pass a Duon\Cms\Config, core factory, and logger when you create it manually.

Settings

App::create() creates Config from the root path and settings array and exposes it as $app->config. Config loads .env from the root path with Dotenv::safeLoad() and merges built-in defaults with the settings array. Use requireEnv() when an application wants to fail fast for required environment variables.

Prefer building the settings array upfront and passing it once to App::create() or new Config(...). Config is immutable after construction, and values such as path.prefix, path.panel, and error.enabled are consumed while the app boots. The immutable shape also lets typed config objects lazily normalize, validate, and cache values safely across long-running worker processes. Use native booleans and integers in PHP settings; environment values are cast by the built-in defaults.

use Duon\Cms\App;

$root = dirname(__DIR__);
$settings = [
    'app.name' => 'mycms',
    'path.public' => "{$root}/public",
    'path.panel' => '/cms',
    'db.dsn' => env('DATABASE_URL'),
    'db.sql' => ["{$root}/db/sql"],
    'panel.theme' => "{$root}/theme",
];

$app = App::create($root, $settings);
$app->config->requireEnv(['DATABASE_URL', 'APP_SECRET']);

Use $config->with(...) sparingly when you need a changed standalone config copy, for example in tests or small derived configurations. Avoid long with() chains for full application config files; keep the complete settings array easy to scan instead.

Read built-in settings through typed config objects or by key. The built-in objects are app, path, panel, error, icons, db, session, media, upload, and password. Their properties convert list-style settings such as panel.theme; invalid broad types fail when the relevant property is read.

$name = $app->config->app->name;
$panel = $app->config->panel->path;
$theme = $app->config->panel->theme;
$session = $app->config->session->options;

$nameByKey = $app->config->get('app.name');
$debug = $app->config->debug();
$env = $app->config->env();

Common built-in settings:

[
    'app.name' => env('APP_NAME', 'duoncms'),
    'app.debug' => env('APP_DEBUG', false),
    'app.env' => env('APP_ENV', ''),
    'app.secret' => env('APP_SECRET', null),

    'path.root' => $root,
    'path.public' => $root . '/public',
    'path.prefix' => '',
    'path.assets' => '/assets',
    'path.cache' => '/cache',
    'path.views' => '/views',
    'path.panel' => '/cms',
    'path.api' => null,

    'panel.theme' => [],
    'panel.logo' => '/images/logo.png',

    'db.dsn' => env('DATABASE_URL', null),
    'db.sql' => [],
    'db.migrations' => [],
    'db.print' => false,
    'db.options' => [],

    'session.enabled' => env('SITE_SESSION_ENABLED', false),
    'session.options' => [
        'cookie_httponly' => true,
        'cookie_secure' => env('SESSION_COOKIE_SECURE', true),
        'cookie_lifetime' => (int) env('SESSION_COOKIE_LIFETIME', 0),
        'gc_maxlifetime' => (int) env('SESSION_IDLE_TIMEOUT', 3600),
        'cache_expire' => 3600,
    ],
    'session.handler' => null,

    'error.enabled' => true,
    'error.renderer' => null,
    'error.views' => null,
    'error.whoops' => true,
]

Admin panel theming

You can style the admin panel through panel.theme in your CMS config. Set it to a single stylesheet path (string) or multiple stylesheet paths (string[]). The panel links those CSS files and reads theme overrides from --theme-* variables that mirror the built-in token names, such as --theme-color-*, --theme-space-*, --theme-radius-*, --theme-font-*, and --theme-sidebar-width.

return [
	'panel.theme' => [
		'/assets/cms/theme/base.css',
		'/assets/cms/theme/brand.css',
	],
];

Test database:

echo "duoncms" | createuser --pwprompt --createdb duoncms
createdb --owner duoncms duoncms

System Requirements:

apt install php8.5 php8.5-pgsql php8.5-gd php8.5-xml php8.5-intl php8.5-curl

For development

apt install php8.5 php8.5-xdebug

macOS/homebrew:

brew install php php-intl

License

This project is licensed under the MIT license.