itk / cms
Symfony bundle that adds a CMS to a site: pages built from sections, collections, menus, settings, media library, SEO, redirects, form requests, users and roles, a JSON API and a Vue admin.
Requires
- php: >=8.3
- ext-ctype: *
- ext-dom: *
- ext-gd: *
- ext-json: *
- ext-mbstring: *
- ext-pdo_pgsql: *
- ext-sodium: *
- doctrine/collections: ^2.2 || ^3.1
- doctrine/dbal: ^4.2
- doctrine/doctrine-bundle: ^2.13 || ^3.0
- doctrine/doctrine-migrations-bundle: ^3.3 || ^4.0
- doctrine/migrations: ^3.8
- doctrine/orm: ^3.2
- doctrine/persistence: ^3.3.1 || ^4.0
- psr/cache: ^2.0 || ^3.0
- psr/clock: ^1.0
- psr/container: ^1.1 || ^2.0
- psr/log: ^1.1 || ^2.0 || ^3.0
- symfony/cache-contracts: ^3.5
- symfony/config: ^7.4 || ^8.0
- symfony/console: ^7.4 || ^8.0
- symfony/dependency-injection: ^7.4 || ^8.0
- symfony/doctrine-bridge: ^7.4 || ^8.0
- symfony/doctrine-messenger: ^7.4 || ^8.0
- symfony/event-dispatcher: ^7.4 || ^8.0
- symfony/event-dispatcher-contracts: ^3.5
- symfony/framework-bundle: ^7.4 || ^8.0
- symfony/http-client-contracts: ^3.5
- symfony/http-foundation: ^7.4 || ^8.0
- symfony/http-kernel: ^7.4 || ^8.0
- symfony/lock: ^7.4 || ^8.0
- symfony/mailer: ^7.4 || ^8.0
- symfony/messenger: ^7.4 || ^8.0
- symfony/mime: ^7.4 || ^8.0
- symfony/password-hasher: ^7.4 || ^8.0
- symfony/process: ^7.4 || ^8.0
- symfony/rate-limiter: ^7.4 || ^8.0
- symfony/routing: ^7.4 || ^8.0
- symfony/security-bundle: ^7.4 || ^8.0
- symfony/security-core: ^7.4 || ^8.0
- symfony/security-csrf: ^7.4 || ^8.0
- symfony/security-http: ^7.4 || ^8.0
- symfony/service-contracts: ^3.5
- symfony/translation: ^7.4 || ^8.0
- symfony/translation-contracts: ^3.5
- symfony/twig-bundle: ^7.4 || ^8.0
- symfony/uid: ^7.4 || ^8.0
- symfony/var-exporter: ^7.4 || ^8.0
- symfony/yaml: ^7.4 || ^8.0
- twig/twig: ^3.10
Requires (Dev)
- max-messenger-bot/max-bot-api-php: ^0.3
- monolog/monolog: ^3.5
- php-cs-fixer/shim: ^3.58
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^12.5 || ^13.0
- symfony/browser-kit: ^7.4 || ^8.0
- symfony/clock: ^7.4 || ^8.0
- symfony/css-selector: ^7.4 || ^8.0
- symfony/dom-crawler: ^7.4 || ^8.0
- symfony/error-handler: ^7.4 || ^8.0
- symfony/filesystem: ^7.4 || ^8.0
- symfony/finder: ^7.4 || ^8.0
- symfony/http-client: ^7.4 || ^8.0
- symfony/notifier: ^7.4 || ^8.0
- symfony/options-resolver: ^7.4 || ^8.0
- symfony/property-access: ^7.4 || ^8.0
- symfony/property-info: ^7.4 || ^8.0
- symfony/stopwatch: ^7.4 || ^8.0
- symfony/string: ^7.4 || ^8.0
- symfony/telegram-notifier: ^7.4 || ^8.0
- symfony/twig-bridge: ^7.4 || ^8.0
- symfony/type-info: ^7.4 || ^8.0
- symfony/var-dumper: ^7.4 || ^8.0
Suggests
- ext-exif: Turns JPEG pictures upright by their EXIF orientation when resized
- monolog/monolog: Hides the Telegram bot token from logs and gives the audit of the MCP server its own channel
- symfony/http-client: Needed by the Telegram bridge and by the check for a new version of the CMS (itk_cms.update_source)
- symfony/notifier: Telegram notifications of new requests (with symfony/telegram-notifier and framework.notifier.chatter_transports); the site works without them
- symfony/telegram-notifier: Telegram bridge of the Notifier, see symfony/notifier
- yuri-kovalev/max-bot-symfony-bundle: MAX notifications of new requests (the bundle configures the MAX Bot API client); the site works without it
Provides
None
Conflicts
- monolog/monolog: <3.5
Replaces
None
This package is not auto-updated.
Last update: 2026-11-15 19:18:07 UTC
README
English | Русский
ITK CMS (itk/cms)
itk/cms is a Symfony bundle that adds a content management system to a site. It provides pages built from sections, page templates, collections, menus, settings, a media library, SEO, redirects, form requests with notifications to Telegram, MAX and e-mail, users and roles, a JSON API, a Vue admin panel and an MCP server for AI assistants.
A site describes its structure in PHP (the config/itk/schema.php file or resource classes) and renders it with its own Twig templates. The bundle knows nothing about a specific site. The built admin panel ships inside the package, so the site does not need Node.
Version 0.2.0, MIT license. Source code: github.com/it-koval/cms.
Contents
- Requirements
- Installation
- Core concepts
- Building the site
- Fields
- Resource classes
- Admin panel
- SEO
- Requests and notifications
- Knowledge base
- Performance
- MCP: AI assistants
- Site status and itk:doctor
- Console commands
- Configuration reference
- Extensions and generators
- Docker
- AI agent in the site project
- Public API and compatibility
- Developing and testing the bundle
- Other documents
Requirements
| What | Version |
|---|---|
| PHP | 8.3 or newer. Extensions ctype, dom, gd with WebP, json, mbstring, pdo_pgsql, sodium. Optional: exif (rotates JPEG by EXIF) and intl (Cyrillic domains in the page cache) |
| Symfony | 7.4 or 8 (Symfony 8 requires PHP 8.4) |
| Doctrine | ORM 3, DBAL 4 |
| PostgreSQL | 16 or newer with the pgvector extension 0.8 or newer |
| Node | 22 or newer, only for the optional critical CSS. The admin panel ships prebuilt. Building it from source uses Node 24 (see CONTRIBUTING.md) |
Composer requires only PHP 8.3. The Site status screen warns when the PHP patch version is below the version with known CVE fixes.
pgvector is mandatory. A core migration runs CREATE EXTENSION IF NOT EXISTS vector and stops with an explanation if the extension is missing or older than 0.8. The pgvector/pgvector:pg17 image includes the extension. On another server, install it by following the pgvector instructions.
Only PostgreSQL is supported. MySQL, MariaDB and SQLite are not supported. On another database, and on PostgreSQL older than 16, the core migration stops and creates nothing. Create the database with UTF8 encoding and a UTF-8 locale. Case-insensitive search relies on lower(), which folds Cyrillic correctly only in such a locale.
Installation
Quick start
The commands below install the bundle into a new Symfony 7.4 project. You need PHP with the extensions from Requirements, Composer, and PostgreSQL with pgvector.
-
Create the project and install the package:
composer create-project symfony/skeleton:"7.4.*" mysite cd mysite composer config extra.symfony.docker false composer require itk/cms
Symfony Flex adds the bundle to
config/bundles.phpand installs the required dependencies: Doctrine, Messenger, Mailer, Security, Twig. Theextra.symfony.docker falseline stops Flex from adding its own Docker files. The package ships a ready Docker kit, see Docker. -
Set the database and the secret in
.env.local:DATABASE_URL="postgresql://user:password@127.0.0.1:5432/mysite?serverVersion=17&charset=utf8" APP_SECRET=a-long-random-string
-
Import the routes in
config/routes/itk.yaml:itk_admin: resource: '@ItkCmsBundle/config/routes/admin.php' itk_site: resource: '@ItkCmsBundle/config/routes/site.php'
-
Replace
config/packages/security.yamlwith the file from Security. -
Set the content language in
config/packages/itk_cms.yaml. The default isru. The admin language is a separate option (see Admin language).itk_cms: main_locale: en
-
Create the tables and the first administrator. Run the migrations first, then
itk:install. The command asks for a password.php bin/console doctrine:database:create php bin/console doctrine:migrations:migrate -n php bin/console itk:install --email=you@example.com --site-name="My site" --domain=example.com php bin/console assets:install -
Start the server and the queue worker:
symfony server:start php bin/console messenger:consume async critical_css knowledge_base
Without the worker, e-mails and messenger messages are not sent. The built-in PHP server (
php -S) does not pass a URL with a file extension toindex.phpwhen the file does not exist. Image copies at/uploads/media/_v/…webpthen return 404 until the worker creates them. To let such URLs reach PHP, runphp -S 127.0.0.1:8000 -t public router.phpwith this file in the site root:<?php // router.php: an existing file is served as is, everything else goes to index.php $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH); if (is_string($path) && is_file(__DIR__ . '/public' . $path)) { return false; } $_SERVER['SCRIPT_NAME'] = '/index.php'; require __DIR__ . '/public/index.php';
-
Open
/admin/loginand sign in.itk:installcreates the home page as a draft, so/returns 404 until it is published (Pages → Home → Publish). Check the installation withphp bin/console itk:doctor.
Next, describe the site structure in config/itk/schema.php (see Site schema) and put the templates in templates/. The itk:make:* commands create class and template stubs (see Code generators).
Installing into an existing project
composer require itk/cms installs the required packages. The rest is optional:
| Package | Purpose |
|---|---|
symfony/notifier, symfony/telegram-notifier, symfony/http-client |
Requests to Telegram |
yuri-kovalev/max-bot-symfony-bundle |
Requests to MAX |
symfony/http-client |
Update checks, IndexNow, Yandex Webmaster, knowledge base |
monolog/monolog 3.5 or newer |
Hides the bot token from the log and gives the MCP log its own channel |
In a project without Symfony Flex, add Itk\Cms\ItkCmsBundle::class => ['all' => true] to config/bundles.php. FrameworkBundle, TwigBundle, SecurityBundle, DoctrineBundle and DoctrineMigrationsBundle must be there too.
Import the routes as in the quick start. site.php declares the public routes: POST /request/{form}, /sitemap.xml, /robots.txt, /llms.txt, the IndexNow key file, image copies, POST /mcp, /healthz, and the page route with priority -1000. Any site route therefore wins over the page route.
Security (security.yaml)
security: password_hashers: Itk\Cms\Entity\User: auto providers: itk_users: id: Itk\Cms\Security\AdminUserProvider firewalls: dev: pattern: ^/(_profiler(/|$)|(_wdt|assets|build)/) security: false itk_mcp: pattern: ^/mcp$ stateless: true provider: itk_users user_checker: Itk\Cms\Security\UserChecker custom_authenticators: - Itk\Cms\Mcp\ApiTokenAuthenticator itk_admin: pattern: ^/admin(/|$) provider: itk_users user_checker: Itk\Cms\Security\UserChecker form_login: login_path: itk_admin_login check_path: itk_admin_login enable_csrf: true default_target_path: itk_admin_app login_throttling: max_attempts: 5 interval: '15 minutes' logout: path: itk_admin_logout target: itk_admin_login enable_csrf: true access_control: - { path: ^/mcp$, roles: ROLE_ITK_USER } - { path: '^/admin/(login|forgot-password|reset-password)(/|$)', roles: PUBLIC_ACCESS } - { path: '^/admin(/|$)', roles: ROLE_ITK_USER }
- The
itk_mcpfirewall is mandatory. Without it, an enabled MCP server returns 500 with the codemcp_firewall_not_configured, anditk:doctorand Site status warn about it in advance. (/|$)at the end of the pattern keeps other paths such as/administratorout of the rule.login_throttlinglimits password guessing.enable_csrfon logout stops another page from signing the administrator out.- If the admin panel is not at
/admin, change^/adminin the firewallpatternand in bothaccess_controllines. The bundle does not change this file. Without these rules the admin sign-in does not open, and collection actions (POST {admin}/api/resources/{collection}/actions/{action}) run without a sign-in check. Example: withitk_cms.admin_path: /cpwrite^/cp; when the routes are imported withprefix: /cpwrite^/cp/admin. - In production,
APP_SECRETmust be unique and non-empty. The admin CSRF token, the encryption of secrets (two-step sign-in secrets, bot tokens, SMTP password, Yandex Webmaster token), the IndexNow key and the URL hashes in requests depend on it. Flex puts an emptyAPP_SECRET=line in.envand a working development value in.env.dev. With an empty secret,/adminreturns 500 with the textAPP_SECRET is empty, anditk:installprints a warning. - Behind a proxy or CDN, set
framework.trusted_proxies. Otherwise all visitors appear to come from one address for the form and sign-in limits. - In production, set
framework.trusted_hostsor theitk_cms.public_urloption. Links in e-mails and the page cache depend on them.
Messenger queue
The bundle routes its messages to three transports:
| Transport | Messages |
|---|---|
async |
Request\SendRequestNotification (a request to Telegram or MAX), Mail\SendMail and Security\RequestPasswordLink (e-mails), Media\GenerateImageVariants (image copies), IndexNow\Model\PingIndexNow |
critical_css |
CriticalCss\Model\GenerateCriticalCss |
knowledge_base |
KnowledgeBase\Model\SyncKnowledge |
If the site does not declare these transports, the bundle adds them on doctrine://default (the messenger_messages table in the same database), plus the failed transport with failure_transport: failed. The bundle leaves alone a transport the site declared itself, and its failure_transport. A production site usually sets retries:
framework: messenger: failure_transport: failed transports: async: dsn: '%env(MESSENGER_TRANSPORT_DSN)%' retry_strategy: { max_retries: 5, delay: 60000, multiplier: 5, max_delay: 36000000 } failed: 'doctrine://default?queue_name=failed&auto_setup=0'
Do not use sync:// instead of async. The Forgot your password? e-mail would then be built inside the request, and the response time would reveal whether the address exists.
Run the worker under supervisor or systemd: php bin/console messenger:consume async critical_css knowledge_base. The site and the admin panel work without the worker. Requests are saved, pages are served, and the route creates an image copy on the first request. Only e-mails and messenger messages are not sent. They wait in messenger_messages, and Site status shows how many there are. On hosting without background processes, run the worker from cron once a minute:
* * * * * cd /path/to/site && php bin/console messenger:consume async critical_css knowledge_base --time-limit=55 --memory-limit=128M
Configuration, migrations and first run
- Configure the bundle in
config/packages/itk_cms.yaml. All options are optional. The full list is in Configuration reference. - Run
php bin/console doctrine:migrations:migrate. The bundle registers its own migrations,Itk\Cms\Migrations. - Run
php bin/console itk:install --email=you@example.com --site-name="My site" --domain=example.com. The command is safe to run again. It creates the built-in roles, the menu areas from the schema, the default settings, the queue table (for transports that can set themselves up, such asdoctrine://), the home page and the first administrator. The command asks for the password. You can also pass it with--passwordor theITK_ADMIN_PASSWORDvariable.--namesets the administrator's name,--no-homeskips the home page. - Run
php bin/console assets:install. The admin files become available at/bundles/itkcms/admin/. Flex does this oncomposer installandcomposer update. - Run
doctrine:schema:validateanddoctrine:migrations:diffonly afteritk:install.itk:installcreates themessenger_messagestable. Before that step,validatereports a mismatch, anddiffwrites the creation of that table into the site's migration.
Site migrations
Bundle migrations (Itk\Cms\Migrations) and site migrations run in the order of the date in the class name (Version20261030120000 means 2026-10-30 12:00:00). For equal dates, namespaces run in alphabetical order. The bundle sets this order with its own version comparator in doctrine_migrations.services. A comparator set by the site replaces it.
config/packages/doctrine_migrations.yaml sets the namespace of the site migrations. In a new project it is App\Migrations in src/Migrations/. Older projects use DoctrineMigrations in migrations/.
-
The bundle adds its migrations path after the site paths. So
doctrine:migrations:diffand:generatewithout--namespacewrite a new migration into the site directory, not intovendor. A site with several paths picks one with--namespace. The site does not set its own path forItk\Cms\Migrations. -
Name a site migration that touches bundle data with the current date (as
diffdoes). It then runs after the bundle migrations that came before it. -
A migration that touches bundle tables must not fail on an empty database. Check the table with a direct query:
$this->skipIf(null === $this->connection->fetchOne("SELECT to_regclass('itk_setting')"), 'itk_setting is not created yet');
$schema->hasTable()does not work here. With the filter from the next item, it always returnsfalse. -
Hide the
itk_*tables from the site'sdoctrine:migrations:diff. Otherwise any difference between the bundle version and the database ends up in a site migration. Only bundle migrations change bundle tables.# config/packages/doctrine.yaml doctrine: dbal: schema_filter: '~^(?!itk_)~'
If the site has its own tables with the
itk_prefix, refine the expression. The filter applies only todiff.doctrine:schema:updateanddoctrine:schema:validatestill see theitk_*tables. If you cannot replacehasTable()withto_regclassin the site migrations, leaveschema_filterempty and filter at generation time:doctrine:migrations:diff --filter-expression='~^(?!itk_)~'.
Core concepts
Site schema
The site structure is described by config/itk/schema.php (the schema_file option changes the path) or by resource classes (see Resource classes). Both end up in one schema.
use Itk\Cms\Schema\Field; use Itk\Cms\Schema\SchemaBuilder; use Itk\Cms\Schema\SectionType; return static function (SchemaBuilder $s): void { $s->design(headlineMarks: ['gradient']); $s->menuArea('header', 'Header menu', depth: 2); $s->layout(top: ['header'], bottom: ['footer']); $s->section('hero', 'Hero')->group(SectionType::FIRST_SCREEN)->short('Hero')->tone('dark')->silhouette('hero')->about('Top of the page')->fields( Field::headline('headline', 'Headline')->max(48)->required(), Field::description('description', 'Description')->max(90), Field::link('buttonLink', 'Where the button leads'), Field::image('image', 'Photo on the right'), ); $s->template('catalog', 'Catalog')->single()->topLevel()->sections('all')->listing(of: ['product'], label: 'Products'); $s->template('product', 'Product')->parents('catalog')->leaf()->shortcut('Products')->card(image: 'img', title: 'title', text: 'desc')->fields(/* … */); $s->collection('ambassadors', 'Ambassadors')->view('cards')->sortable()->titleField('name')->fields(/* … */); $s->settings('contacts', 'Contacts')->fields(Field::text('phone', 'Phone')->required()); $s->form('call', 'Call request')->fields(Field::text('phone', 'Phone')->required())->telegram('Request #{id}: {phone}'); };
| Call | What it describes |
|---|---|
design(headlineMarks: [...]) |
Styling that the site design supports (marks in headlines) |
menuArea(key, title, depth:) |
A menu area. depth: 2 allows an item and one level of children |
layout(top:, bottom:) |
Menu areas in the layout. By default header is at the top and the rest at the bottom |
section(key, title) |
A section type: group(), short(), tone(), silhouette(), about(), h1(), template(), fields() |
template(key, title) |
A page template: single(), root(), topLevel(), parents(), anyParent(), leaf(), sections(), listing(), shortcut(), card(), h1(), areas(), about(), fields() |
collection(key, title) |
A collection of records, see Collections |
settings(key, title) |
A settings group, see Settings |
form(key, title) |
A site form, see Receiving requests |
withoutBlog() |
A site without a blog |
Schema validation. Schema::validate() returns a list of errors in the admin language. It finds a repeated field key (in a section, a template, a collection with its tabs, a form, a repeater), a repeated settings key in two groups, an invalid key, parents() and listing(of:) with a template that does not exist, a form without fields, titleField() pointing to a field that does not exist, the reserved field key version in a collection, and a menu area declared twice. A key consists of Latin letters, digits, _ and -, and starts with a letter or a digit. In debug, the schema is validated on load, and an error throws an exception with the whole list. In prod, there is no check on each request.
php bin/console itk:schema:lint shows the same errors and checks the Twig templates. A section without sections/<key>.html.twig (or its own template()) is an error. A page template without pages/<key>.html.twig gives a warning: the default template renders such pages. The exit code is 1 on an error. Warnings do not change it.
Pages, templates and sections
A page consists of the fields of its template and a list of sections. The template sets where the page can stand in the tree and which fields it has. A section is a page block with its own fields and its own Twig template, templates/sections/<key>.html.twig.
Core templates: home, default, blog, blog_category, blog_article. A site changes a core template by calling $s->template('blog_article') again. $s->withoutBlog() at the start of schema.php, or the itk_cms.blog: false option, removes the three blog templates and the Blog articles link in the admin menu. itk:schema:lint reports an error for a template that refers to the removed blog in parents() or listing(of:).
The H1 heading. The first visible section of the SectionType::FIRST_SCREEN group gets the is_h1 variable in its template. The H1 of that section is the field from ->h1('field') or the first headline field. A group is the literal string passed to group(), and the admin panel shows it as written. Use SectionType::FIRST_SCREEN for the first-screen group. The admin panel shows this group and the default group in the interface language. A page template with ->h1('field') owns the H1 itself. Only that field gets the Page heading (H1) label. If the H1 field has the headline type, the page title equals its first line as plain text.
Content in one language. For now, site content is kept in one language, main_locale. The admin language is set separately (see Admin language).
Collections
A collection is a list of records with fields: reviews, tours, staff. Records are published the same way as pages. Collection options:
| Method | What it does |
|---|---|
fields(...), tab(key, label, ...fields) |
Fields and tabs of the record form |
titleField(), thumbField(), subField(), toggleField() |
The title field, thumbnail, second line and toggle in the list |
view('table'|'cards'), views([...]) |
The list view, see List views |
sortable() |
The list order is set by hand, and the site uses the same order |
defaultSort([...]), perPage(int) |
The default sort and the list page size (50) |
filters(...), actions(...), metrics(...) |
Filters, actions and metrics |
tree() |
Records nest inside each other |
singleton('main') |
A collection of one record with this id |
view('matrix'), matrix([...]) |
A table editor for one record: colFields, rowKinds, rowLabel |
singular(), newLabel(), icon(), describe(), emptyState() |
Labels and the icon in the admin panel |
menu(...), visibleWhen(fn) |
The place in the admin menu and visibility, see Admin menu |
Menus
menuArea() declares menu areas. Items are edited in Settings → Menus (the set:menus permission). An item leads to a page or to a URL. Items are dragged by the handle on the left, and the area depth limits nesting. In a template, menu('header') outputs the menu. Only published pages appear in the menu.
Settings
A settings group is a form in Settings with its own fields. Settings keys are shared by all groups. Built-in groups:
| Group | Fields |
|---|---|
site (Site) |
siteName, domain (the site address), company fields for schema.org: organizationType, organizationName, organizationAddress, phone, email, organizationLogo, organizationLinks, schemaOrgOff |
analytics (Analytics and webmaster tools) |
yandexMetrikaId, yandexMetrikaWebvisor, googleAnalyticsId, yandexVerification, googleVerification, indexNow |
A site extends a built-in group with $s->settings('site')->fields(...). A site field with the key of a built-in field replaces the core field, whichever group the site declares it in.
Site code reads settings with the Itk\Cms\Settings\Settings service. The value comes in the field's type:
$settings->get('phone'); // toggle → bool, number → int|float, text/select → string, image/link/repeater → array $settings->string('phone', 'none'); $settings->int('seats', 10); $settings->bool('maintenance'); $settings->array('socials'); $settings->media('logo'); // {src, alt} or null $settings->get('siteName', locale: 'en'); // for fields with translatable() $settings->all(); // all settings of the language
The call's default is used when the setting is not in the schema or is empty. false and 0 count as real values. Until the setting is saved, the field's default() is read. The settings() Twig function uses the same service. canSee() restrictions do not apply to this service.
Media library and images
Originals are stored at {upload_url}/Y/m/name.jpg (by default /uploads/media). Resized copies sit next to them: {upload_url}/_v/w{width}/Y/m/name.webp and .avif.
- After an image is uploaded, the worker creates WebP and, if GD supports
imageavif, AVIF for each width. Without a queue, theitk_image_variantroute creates the copy on the first request and puts the file at the public path. After that the web server serves it. For this to work, the web server passes a request for a missing file toindex.php(try_files $uri /index.php$is_args$args). - Only widths from
itk_cms.images.widthsare allowed. Any other URL returns 404. The original is looked up only insideupload_dir. - An image is never enlarged. Proportions and transparency are kept, and the EXIF rotation of JPEG is applied.
- JPG, PNG, non-animated WebP and AVIF are converted. GIF, SVG, PDF, animated WebP and originals larger than
images.max_pixels(50 megapixels) are served as is. - In
articleanddescriptionfields,<img src="/uploads/…">tags get on output thesrcof the 960 copy, asrcsetup to 1920,sizes,loading="lazy"anddecoding="async". The database keeps the original HTML. php bin/console itk:media:warm [--width=640 --width=1280]creates copies of all images in advance, for example after an import.
Crops and focal point. A media library file has a focal point and saved crops for aspect ratios (Media library → file → Crop and focal point). A crop URL is {upload_url}/_v/w{width}-r{A}x{B}/Y/m/name.webp, and media_url(image, 960, '16:9') returns it. Without a saved crop, the largest frame of that ratio around the focal point is used. Allowed ratios are those in images.ratios and those for which the file has a saved crop. Write the ratio unreduced (16x9, not 32x18), otherwise you get 404. The browser caches a crop for a day, not a year, because the crop can be redrawn.
Folders. Folders nest up to 6 levels, and a name is unique among siblings. A folder with content can be deleted only by moving the content to another folder or to the top level. API (the media area): GET|POST media-folders, PATCH|DELETE media-folders/{id} (?moveTo=<id>|root), GET media?folder=<id>|none, PATCH media/{id} {folderId}, POST media/move {ids, folderId}.
Building the site
Twig templates
The site puts its templates in templates/:
layout.html.twigis the layout. It declares{% block content %}.{% block title %}is convenient for<title>.pages/<template>.html.twigrenders a page of its template. Without it,pages/default.html.twigis used.sections/<section>.html.twigrenders a section. Variables:section,page,is_h1.
A page template has access to page (id, parentId, template, locale, title, url, seo, fields, sections, h1Id) and site (the settings, plus name, domain, locale).
Twig functions
| Function | What it does |
|---|---|
render_sections(page) |
Renders the visible sections through sections/<type>.html.twig |
itk_field(section|page, 'key') |
The field value. headline and formatted text come as safe HTML, text as escaped text, everything else as data. In preview, wraps the value in markup for highlighting |
itk_field_attrs(section|page, 'key') |
Preview attributes for non-text fields |
itk_section_attrs(section), itk_section_class(section) |
Attributes of the section root and the chg class for a changed section, in preview only |
itk_is_preview() |
true while the admin panel shows a draft |
menu('header') |
The area items: label, kind, url, active, open, children |
settings('phone'), settings('phone', 'none'), settings() |
Settings |
page_url(link) |
A safe URL from a Link field value, a page or a page id |
listing(page) |
The published pages or records that the page collects. Each row has parentId |
itk_pages({...}), itk_page(id), itk_collection(key, {...}) |
Public data reading, see the section below |
media_url(image[, width[, ratio]]) |
The image URL, its WebP copy of the nearest allowed width not smaller than the given one, or a crop of the ratio |
media_srcset(image[, maxWidth[, ratio]]) |
A srcset value up to the original or up to the first copy that covers maxWidth. Empty for GIF, SVG and external URLs |
media_width(image) |
The width of the original in pixels, or null |
media_ratio(width, height) |
The ratio key of a slot in the layout: media_ratio(700, 250) returns '14:5' |
itk_img(image, {...}) |
A ready <img> with srcset, sizes, alt, loading="lazy", decoding="async". Wrapped in <picture> when AVIF is supported |
itk_seo({...}) |
Meta tags of the current URL, see SEO rules for URLs |
itk_cache(300), itk_cache(false) |
The lifetime of the entry in the page cache, see Page cache |
itk_stylesheets({nonce: x}) |
The site stylesheets, see Critical CSS |
itk_t('area.key', {...}), itk_locale() |
Text and language of the admin interface. For your own sign-in pages and e-mails |
itk_admin_font() |
The @font-face rules of the admin font for your own sign-in pages |
itk_img options: sizes, class, width, height, loading, alt, ratio, src_width (the width of src, by default width, otherwise 960), max_width (the widest image in device pixels, by default 2 × width), attrs (an array of attributes or itk_field_attrs(...)). sizes defaults to (max-width: {width}px) 100vw, {width}px.
A ratio that is in neither images.ratios nor the file's crops does not break the page. The whole image is used, and a warning goes to the log. To make an image fit the shape of its slot, write media_url(img, 700, media_ratio(700, 250)).
Public data reading
itk_pages, itk_page and itk_collection read only published content, and read it the same way for everyone. A guest and a signed-in administrator see the same thing. Each call makes one query. Site code reads the same data with Itk\Cms\Content\ContentReader.
{% for c in itk_pages({template: 'blog_category'}) %}<a href="{{ c.url }}">{{ c.title }}</a>{% endfor %}
{% for a in itk_pages({template: 'blog_article', parent: category.id, sort: '-fields.date', limit: 6}) %}…{% endfor %}
{{ itk_page(article.parentId).title }}
{% for t in itk_collection('tours', {where: {state: 'open', seats: {from: 5}, level: ['easy', 'mid']}, sort: '-start', limit: 10, offset: 20}) %}…{% endfor %}
itk_pagesreturns rows{id, parentId, template, locale, title, url, seo, fields, position, publishedAt}. Parameters:template(a key or a list),parent(a page id, direct children only; an empty value is an error),limit,sort.sortacceptsposition(the default),createdAt,publishedAt,title,urlandfields.<key>. A-sign means descending order. Write several keys as a list or comma-separated. A numeric field sorts as a number. Rows have no sections.listing()returns those.itk_page(id)returns the same kind of row, ornull. All pages of the language are read in one query per visitor request, so a loop withitk_page(a.parentId)does not run a query for each article.itk_collection(key)returns records in order. Parameters:where({field: value}; a list means any of the values,trueandfalsefor a toggle,{from, to}for a number or a date such as2026-11-30),sort(position,createdAtor a field),limit,offset. A record comes as{id, ...fields}.- An invalid parameter, field or template throws
\InvalidArgumentExceptionwith a list of what is allowed.
Strict mode
The itk_cms.strict option (equal to kernel.debug by default) makes template errors loud. An exception is then thrown for an unknown key in itk_field (with a hint listing the allowed keys), an unknown key inside a repeater, a section type that is not in the schema, a section without a template, and an invalid call of itk_pages or itk_collection. With strict: false, the page renders, and one warning per error per request goes to the log. A path into a value without subfields (image.src) is not an error. The admin preview never throws: a section without a template shows as a grey frame.
Safe URLs
page_url() returns only a safe URL: a site path (/blog, but not //host), a page URL by id, http(s)://, mailto:, tel: and #anchor. A URL with another scheme (javascript:, data:) becomes an empty string. The Link field is checked by the same rule on save. The rule is the same for pages, records, settings and menu items.
The Itk\Cms\Support\Url class gives these checks to site code: safeLocalPath(), isLocalPath(), cleanPageRef(), cleanLinkUrl(), safeHref(). Url::safeLocalPath($path) returns a path that is safe to put in Location or href. It keeps exactly one / at the start, reads \ as /, and removes tabs and line breaks. Pass through it any part of a URL from the request that goes into a redirect:
return new RedirectResponse(Url::safeLocalPath($request->getPathInfo()) . '?' . $query, 301);
Fields
A field is an object from Itk\Cms\Field\ with chained methods. The label comes first and the key second: Text::make('Title', 'title'). Every field that holds data needs a key. Only Note has no key. In schema.php, the short form Itk\Cms\Schema\Field creates the same field with the key first: Field::text('title', 'Title'). It returns the same object.
Field types
| Class | Field:: |
What it is | Value |
|---|---|---|---|
Text, Textarea |
text, textarea |
A line, multi-line text | string |
Headline |
headline |
A headline | safe HTML |
Description |
description |
Formatted paragraphs | safe HTML |
Article |
article |
Article text: subheadings, quote, divider, photo, simple table | safe HTML |
Number |
number |
A number. ->grouped() shows thousands separators |
number |
Toggle |
toggle |
A toggle | bool |
Select |
select |
One option: ->options(['open' => 'Open']) |
string |
Date, DateTime |
date, dateTime |
2026-11-30, 2026-11-30T18:00 |
string |
Image |
image |
An image | {src, alt} |
Photos |
photos |
A list of photos. An item is a URL string or {src, alt}. In a template, write {{ p.src ?? p }} |
list |
Link |
link |
A link to a page or a URL | {kind, page, url} |
Repeater |
repeater |
A list of items: ->fields(...) |
list, each item has _id |
Relation |
relation |
A link to a collection record: ->to('destinations'), ->multiple() |
id or list of ids |
Note |
note |
A hint for the editor, not data: ->text(), ->linkTo() |
none |
A table in Article contains <thead>, <tbody>, <tr>, <th>, <td>. A cell allows text, links, <strong>, <em> and <br>. The only allowed attributes are numeric colspan and rowspan.
Field methods
All methods return the field, and you can call them in any order.
| Method | What it does |
|---|---|
required(), max(int), rows(int) |
Required, length, height of the input |
hint(string) |
Help text under the field. Alias: help() |
default($v) |
The value for a new record. Alias: initial() |
pattern($regex, $message) |
Server-side check of a site form value |
inputType(string) |
The HTML input type, for example email |
translatable() |
The setting is stored separately for each language |
readonly() |
The editor sees the value but cannot change it. The server ignores the editor's value. Code and hooks can write it |
canSee('set:users' | 'col:tours:edit' | fn (Viewer $v): bool) |
Who can see the field. For everyone else, the server leaves the field out of the schema, records and history, and does not accept its value |
raw() |
Multi-line text is output as raw HTML with scripts. Only a person with the permission to manage users can add or change the value. Nobody can do it through MCP |
half() |
The field takes half a form row. Two neighboring fields with half() stand side by side |
section('Heading') |
A form section heading before the field |
sortable(), searchable(), filterable(?FilterKind) |
Sorting, search and filter in the collection list |
showOnIndex() (column()), hideOnIndex(), hideOnForm(), hideOnDetail(), width(int) |
List column, form, detail view, column width in pixels |
variant() |
A Select field becomes the section style option of the section |
noun(), addLabel() |
The noun for a repeater item and the label of the add button |
readonly() and canSee() apply to collection records, template fields, section fields (top level) and settings. In settings, values of a group for which the person lacks the View level of the set:<group> permission are not returned either.
Repeater row
Repeater::make('Variants', 'variants') ->noun('variant') ->itemTitle('{bike} · {yearFrom}–{yearTo}', '{title}') ->itemSummary('{sku} · {price}') ->duplicable() ->fields( Relation::make('Bike', 'bike')->to('bikes')->section('Fitment'), Number::make('Year from', 'yearFrom')->half(), Number::make('Year to', 'yearTo')->half(), Text::make('Title', 'title'), Photos::make('Photos', 'photos'), );
itemTitle()sets the title of a collapsed row, anditemSummary()sets the line under it.{key}inserts the subfield value as a person reads it:Relationas the record title,Selectas the option label,Toggleas the field label when it is on,Imageas the image description,Numberwithgrouped()with thousands separators.Link,Photosand a nestedRepeatergive an empty value.- Text between two values is printed only if both values are present. Text before the first value and after the last value is printed only if a value is next to it. Brackets around an optional value are not supported.
0counts as a value, an empty string does not. - The next arguments of
itemTitle()are fallback templates. The first one that gives non-empty text wins. If all are empty, the row is named bynoun()with a number. - In history, a
Relationin the title is empty, because history is written without queries to other collections. duplicable()adds a Duplicate button. The copy appears under the original and gets new_idvalues.- With
itemTitle()oritemSummary(), the row thumbnail comes from the firstImagefield, or, without one, from the first photo of the firstPhotosfield.
Custom field type
A custom field type extends Itk\Cms\Field\AbstractField. The wireType() method returns a type that the admin panel understands. An extension registers the admin component for it (see Extensions). itk:make:field creates a stub.
Resource classes
Resource classes are the second way to describe a site: one PHP class per collection, template, section or settings group. The site puts them in src/Itk/{Collection,Template,Section,Settings}/, and they are picked up automatically through the itk.resource tag if services.yaml loads src/. You can inject services into the constructor.
namespace App\Itk\Collection; use Itk\Cms\Attribute\{Group, Icon, Order}; use Itk\Cms\Field\{Date, Number, Select, Text}; use Itk\Cms\Resource\{CollectionResource, Metric}; #[Group('Catalog', icon: 'box', order: 20)] #[Order(10)] #[Icon('map')] final class ToursCollection extends CollectionResource { public function key(): string { return 'tours'; } public function title(): string { return 'Tours'; } public function fields(): iterable { yield Text::make('Title', 'title')->required()->searchable()->sortable(); yield Date::make('Start', 'start')->sortable()->filterable(); yield Number::make('Seats', 'seats')->sortable()->filterable(); yield Select::make('Status', 'state')->options(['open' => 'Open for booking', 'full' => 'Sold out'])->filterable(); } public function defaultSort(): array { return ['start' => 'asc']; } public function metrics(): iterable { yield Metric::count('Total'); yield Metric::sum('Seats', 'seats'); } }
| Class | Required | Optional |
|---|---|---|
CollectionResource |
key(), title(), fields() |
singular(), newLabel(), icon(), description(), emptyState(), views(), titleField(), thumbField(), subField(), toggleField(), filters(), actions(), metrics(), tree(), sortable(), defaultSort(), perPage(), canSee(Viewer), hooks |
TemplateResource |
key(), title(), fields() |
about(), parents(), topLevel(), single(), root(), leaf(), sections(), listing(), h1(), shortcut(), card(), areas(), configure(Template $t), hooks |
SectionResource |
key(), title(), fields() |
group(), template() (by default sections/<key>.html.twig), short(), tone(), silhouette(), about(), h1() |
SettingsResource |
key(), title(), fields() |
description() |
A class with the key of a core template (blog_article) changes that template. If the class has no fields, the core fields stay. Any other key declared twice (in schema.php and in a class, or in two classes) is an error. Do not inject Schema, PageService or CollectionService into a resource: the schema is built from resources, and you get a dependency cycle. To work with data in hooks, use events and Context.
Hooks and events
Each operation on a collection record or a page goes like this: first a Symfony event, then a method of the resource class. For a page, the resource is the class of its template, and kind is page. For a record, the resource is the collection class, and kind is item.
| Moment | Event (Itk\Cms\Event\) |
Class method |
|---|---|---|
| First read of the section in a request | onLoad(Context) |
|
| Create | RecordCreating, RecordCreated |
beforeCreating(array $data, Context): array, afterCreated(Record, Context) |
| Update, including autosave | RecordUpdating, RecordUpdated |
beforeUpdating(Record, array $data, Context): array, afterUpdated(Record, Context) |
| Delete | RecordDeleting, RecordDeleted |
beforeDeleting(Record, Context), afterDeleted(Record, Context) |
| Publish | RecordPublishing, RecordPublished |
beforePublishing(Record, Context), afterPublished(Record, Context) |
| Unpublish | RecordUnpublishing, RecordUnpublished |
beforeUnpublishing(Record, Context), afterUnpublished(Record, Context) |
| Page template change | PageTemplateChanged (from is the old template, resourceKey the new one) |
|
| Several records at once | MassAction (action: delete, publish, unpublish; phase: before, after) |
beforeMassDeleting, afterMassDeleted, beforeMassPublishing, afterMassPublished, beforeMassUnpublishing, afterMassUnpublished (array $records, Context) |
- An event has
resourceKey,kind,record(nullinRecordCreating),dataandviewer. You can changedatainRecordCreatingandRecordUpdating, and the changed data is saved. Recordis{id, kind, resourceKey, locale, fields, status, meta}with aget($key)method. For a page,fieldsholds the template fields, andmetaholdstitle,url,parentId,template.Contextholdsviewer,locale,kind,resourceKey.Vieweris either a person with permissions (can('col:tours', 'publish'),allows('set:users'),user(),role()) or the system (console, import, queue:isSystem(), everything is allowed).- Any
before…can throwItk\Cms\Content\ContentException. The change is cancelled, and the editor sees the exception text.after…runs after the save, and an exception in it rolls nothing back. - A mass operation first calls the shared
beforeonce. Then each record goes through its ownbefore…and the database write, all in one transaction. Theafter…of each record and the sharedafterMass…run after the transaction, and only if it did not roll back. - The core removes
readonly()fields and fields hidden bycanSee()from the person's data before the events. Values added by a hook are saved. - Page data in
beforeCreatingandbeforeUpdatingis nested:{title, url, seo, parentId, template, sections, fields: {...}}. An update brings only the changing keys. An unknown top-level key is ignored. - A move in the tree goes through
beforeUpdatingwith the data{parentId}. A hook can cancel the move with an exception, but cannot change it. Discard edits does not call the update hooks. - Returning an unpublished page to the site calls
RecordPublishedandafterPublishedwithoutbefore….
// CollectionResource: flat data public function beforeCreating(array $data, Context $ctx): array { $data['slug'] = Slug::slugify((string) ($data['title'] ?? '')); return $data; } // TemplateResource: template fields inside 'fields' public function beforeCreating(array $data, Context $ctx): array { $data['fields']['slug'] = Slug::slugify((string) ($data['title'] ?? '')); return $data; }
Actions
An action is a button over collection records. A class declares actions in actions(), and schema.php in ->actions(...).
Action::make('Duplicate', 'duplicate')->row()->bulk()->icon('copy') ->modal('How many copies?', Number::make('Copies', 'times')->required()) ->handle(static function (ActionContext $c): ActionResult { // $c->records() are the selected records, $c->input() the dialog values, $c->viewer() return ActionResult::message('Done')->reload(); });
| Method | What it does |
|---|---|
row(), bulk(), top(), form() |
Where the button is: the row menu, the checked records, above the list, the record page. Several are allowed. The default is row() |
icon(), danger(), confirm('Question') |
Icon, dangerous action, question before running |
modal($title, ...$fields) |
A dialog with fields. The values are validated by the fields |
canSee(string|callable) |
Who can see the button |
requires('publish') |
The collection permission needed to run it. The default is Edit |
permission() |
A separate action:<collection>:<action> row in the role matrix. By default only the administrator has it |
handle(callable) |
The handler |
Result: ActionResult::message('…')->reload(), ::redirect('/pages/42') (an admin path or http(s)://), ::download('/path/file.csv', 'name.csv', delete: true), ::download(StreamedResponse), ::error('…').
Every collection except single-record collections gets the built-in actions publish-selected, unpublish-selected and delete-selected. They go through the mass hooks. Your own action with the same key replaces the built-in one.
API: POST {admin}/api/resources/{collection}/actions/{action} with the body {ids?: [], input?: {}, locale?} returns {ok, message?, reload?, redirect?, download?}. An action without the top() placement needs ids, at most 500. An action error returns 422 {ok: false, error, message}. An action file is served once, to the person who ran the action, at GET {admin}/api/downloads/{token} within 5 minutes.
Filters, sorting and metrics
A filter is a field with filterable(). The filter kind is picked from the field or set explicitly: FilterKind::Text, Select, Multi, Toggle, DateRange, NumberRange, Relation. The resource's filters() replaces the set of fields with filterable(). Every collection has the status filter (draft, published).
GET {admin}/api/collections/tours?q=altai&filter[state]=open&filter[start][from]=2026-11-01&filter[seats][from]=5
&filter[level]=mid,hard&sort=-start,title&page=2&perPage=50
→ { items, total, page, perPage, facets: { state: { open: 4, full: 3 } }, metrics: [{ label, kind, value }] }
- The response with
itemsandtotalcomes when the request haspage,perPage,sort,filterorenvelope=1. Without them, the response is a plain list of rows. sorttakes comma-separated keys, and-means descending. You can sort by fields withsortable(), and bystatus,updatedAt,createdAt,position. Withoutsort,defaultSort()applies, otherwise the manual order.qsearches the fields withsearchable(), or, without them, the title and the second line. A field hidden bycanSee()can be neither filtered nor sorted (422).perPagedefaults to 50, at most 200.facetscounts records by the values of theSelect,Multi,Toggleandstatusfilters across the whole collection.- Metrics (
Metric::count('Total'),Metric::count('Published', filter: ['status' => 'published']),Metric::sum('Seats', 'seats')) are computed over the whole collection, not over the current filter. - The server remembers filters and the list view per person:
GET|PUT|DELETE {admin}/api/prefs/{key}. The key is up to 100 characters of letters, digits and. _ : -, and the value is up to 16 KB of JSON.
List views
The resource's views() or ->views([...]) lists the views a person switches between. The first view is the default.
public function views(): array { return [ 'table', 'cards', 'calendar' => ['start' => 'dateStart', 'end' => 'dateEnd', 'title' => 'city'], 'kanban' => ['field' => 'state', 'columns' => ['open' => 'Open', 'full' => 'Sold out']], ]; }
- Calendar.
startis aDateorDateTimefield and is required.endis optional.titlesets the label, by default the record title. A click on a day creates a record with that date. Dragging and Alt + arrows shift both dates. - Board.
fieldis aSelectfield, and the columns are its values orcolumns. Moving a card changes the field value. Records with an unnamed value go to the No value column. - Shifting dates and moving cards on the board are ordinary record updates: field permissions, hooks, events and history all apply. A hook can cancel the move with an exception.
- The calendar, the board and the tree show all records without paging, up to 2000.
- An invalid view definition (a calendar without
start, a field that does not exist, a board not on aSelect) throwsInvalidArgumentExceptionwhen the schema is built.
Tree
Records of a collection with tree() nest inside each other. The list gets the Structure view (the default first view) with drag and drop and keys: Alt + ↑ and ↓ move a record, Alt + → nests it into the sibling above, Alt + ← moves it up a level.
PUT {admin}/api/collections/{col}/tree [{ "id": "…", "parentId": "…"|null, "position": 0 }, …] → { ok, moved }
PUT {admin}/api/pages/tree the same for pages
positionis the place among the records of the same parent, starting from zero. The named nodes move, and the siblings under the affected parents are renumbered.- You cannot nest a node into itself or into its own branch (422), name a node twice, or point to an unknown node or parent. Everything runs in one transaction.
- A record whose parent changed goes through an update with hooks. A record with
parentIdis created with an ordinaryPOST collections/{col}. Deleting a record lifts its children into its place. The Edit permission oncol:<key>is required. - For pages, the template rules apply (
parents(),single,leaf, the home page always at the top), plus the Edit permission on the template of each page being moved. In the admin panel: Pages → Edit structure.
Admin menu
The server builds the left column of the admin panel: GET {admin}/api/schema returns nav, with only what the person can access. Built-in items: Today (0), Pages (10) with quick links for templates with shortcut(), Requests (20), Media library (30), the Settings group (900). A collection class appears in the menu automatically.
| Class attribute | What it does |
|---|---|
#[Group('Catalog', icon: 'box', order: 20)] |
The menu group. Without the attribute, the Collections group with order 50 |
#[Order(10)] |
The item's place in the group |
#[Icon('map')] |
The item icon |
#[CanSee('col:tours:edit')] |
Who sees the item, in addition to the View permission |
#[HideFromMenu] |
The section works, but has no menu item |
In schema.php: $s->collection('tours')->menu(group: 'Catalog', order: 10, icon: 'map', hidden: false, canSee: 'col:tours', groupIcon: 'box', groupOrder: 20). The class's canSee(Viewer) hides the collection completely, from the schema and from the API.
Admin panel
Address, sign-in and API
The admin panel is at /admin. The itk_cms.admin_path option sets another path (one or more segments, with / at the start and no / at the end, for example /cp). You can also set prefix on the route import. The admin panel is then at prefix + admin_path. After changing the path, update security.yaml (see Security).
The bundle recognizes the admin panel by the route names itk_admin_* and itk_api_*, not by the URL string. So API CSRF, security headers, two-step sign-in and JSON errors work at any path. The paths below are given for /admin.
| Path | What it is |
|---|---|
/admin (itk_admin_app) |
The admin shell. Files come from /bundles/itkcms/admin/ by the Vite manifest. Client settings are in window.ITK_ADMIN |
/admin/login (itk_admin_login), /admin/logout (itk_admin_logout) |
Sign-in (form_login, fields _username, _password, _csrf_token) and sign-out |
/admin/login/otp |
The second sign-in step |
/admin/forgot-password, /admin/reset-password/{token} |
Forgot your password? and a new password from the e-mailed link |
/admin/preview/{id}?locale= (itk_admin_preview) |
A page draft rendered with the real site templates |
/admin/api/* |
The admin JSON API |
- Every API call that changes data carries the
X-CSRF-Tokenheader with the value fromwindow.ITK_ADMIN.csrf. - An API error comes as
{ "error": "…", "details"?: … }with code 401, 403, 404, 409 or 422. Theerrortext is in the person's language and can change. Integrations rely on the HTTP code and ondetails.code:conflict,csrf,no_translation,link_gone,password_locked,mail_not_configured,mail_failed,mail_queue,mail_test_limit,no_public_url,2fa_code,2fa_enrol,2fa_locked. A form field error is indetails.<field>. - The server checks permissions on every call.
- All admin responses get
X-Frame-Options: SAMEORIGIN,Content-Security-Policy: frame-ancestors 'self',X-Content-Type-Options: nosniffandReferrer-Policy: same-origin. A header set by the controller is not overwritten.
The Itk\Cms\Admin\AdminPath service tells where the admin panel is (base(), to('/api/me')), taking the import prefix into account. Links in e-mails are built through it.
Roles and permissions
A permission is a pair of an area and an action. Actions: view (View), edit (Edit), publish (Publish), delete (Delete). publish and delete include edit, and edit includes view. The role matrix in Settings → Users and roles → Roles is built from the schema areas and picks up new rows automatically.
| Area | What it grants |
|---|---|
pages |
Pages. A role can be limited to a list of templates |
col:<key> |
A collection |
requests |
Requests (view, edit) |
media |
The media library (view, edit, delete) |
set:<group> |
A settings group, including set:site and set:analytics |
set:menus, set:redirects, set:seo |
Menus, redirects, SEO rules, robots.txt and llms.txt |
set:notifications, set:mail, set:bots |
Notification recipients, mail server, bot tokens |
set:theme, set:languages, set:users, set:mcp |
Admin appearance, languages, users and roles, AI assistants |
templates |
Viewing templates |
dev |
The For developers section: Site status |
action:<collection>:<action> |
Running an action with permission() |
Built-in roles:
| Role | Permissions |
|---|---|
admin (Administrator) |
All areas |
editor (Editor) |
Pages and collections in full, the media library in full, viewing requests |
author (Author) |
Viewing and editing pages of article templates (templates with card(date: …)), viewing and editing the media library |
requests (Requests) |
Viewing and editing requests |
Symfony gives every signed-in person the ROLE_ITK_USER role. In code, Itk\Cms\Security\Access and PermissionVoter (the itk attribute) check permissions.
Passwords
- Your own password. My profile → Change password: the current password, a new one of at least 10 characters, and a repeat.
POST {admin}/api/me/password {current, password, repeat?}. More than five attempts in 15 minutes return 429 (itk_password_change). Open sessions on other devices end. - Invitation and reset by an administrator (
POST users,POST users/{id}/reset-password). When mail is configured, the person gets a link: an invitation lives 7 days, a reset 24 hours. Theemailed: trueresponse comes after the queue accepts the e-mail. Without mail, the server returns a one-time password once, in thepasswordfield, and the admin panel shows it with a Copy button. You cannot reset your own password with this call (403). - Forgot your password. The response is the same whether the address exists or not. The page only queues a message. The worker looks up the person and sends the e-mail, so the address cannot be found out from the response time either. The link lives one hour and works once. The database stores only its sha256. Limits: 10 requests per hour from a visitor address, 3 e-mails per hour to one e-mail address, 10 invalid links in 15 minutes (
itk_password_reset_ip,itk_password_reset_email,itk_password_reset_guess). Without mail, the page suggests contacting the administrator. - All unused links of a person expire when the person's password is set in any way, their e-mail changes, or they are blocked.
- Console.
php bin/console itk:user:password name@example.comasks for the password with hidden input.--password=…leaves the password in the shell history.
Links in e-mails are built from the trusted site address (Mail\PublicUrl) in this order: the itk_cms.public_url option; the request address, if framework.trusted_hosts is set; the Site address setting (domain, https:// by default); the request address as is, only in debug. The raw Host header is not used in production. Without a trusted address no link is created: Forgot your password? writes an error to the log, and invitation and reset return a one-time password. In production, set public_url or trusted_hosts, because anyone with the set:site permission can change the Site address setting.
Two-step sign-in
The second step is a one-time code from an app (TOTP per RFC 6238: SHA-1, 6 digits, 30 seconds). Google Authenticator, 1Password, Authy and others work. You do not need to change security.yaml.
- Turning it on. My profile → Two-step sign-in: a QR code and a key for manual entry, confirmation with the first code, 10 recovery codes. The codes are shown once, and each works once. Turning it off and getting new recovery codes require the password.
- Sign-in. After the password,
/admin/login/otpopens. Until the code is entered, only this page and sign-out work in the admin panel. - Mandatory for a role. The Require two-step sign-in checkbox in Settings → Users and roles → Roles (
Role::require2fa). A person with such a role and no factor sees only the setup dialog. Everything else returns 403 withdetails.code = '2fa_enrol'. That person cannot turn the factor off (409). - Attempts. Five wrong codes in a row lock the factor for 15 minutes (429,
details.code = '2fa_locked'). A code works once, with a window of ±1 step. - Storage. The secret is encrypted with
sodium_crypto_secretboxusing a key fromAPP_SECRET. Recovery codes are stored as HMAC-SHA256. - Changing
APP_SECRETmakes the secrets and recovery codes unreadable. People with the factor turned on cannot sign in until their factor is reset. - Reset. An administrator clicks Settings → Users and roles → Users → Reset two-step sign-in (
POST users/{id}/reset-2fa, the Edit level ofset:users, not for yourself). If nobody can sign in:php bin/console itk:user:reset-2fa name@example.com. - API.
GET 2fa,POST 2fa/setup,POST 2fa/enable {code},POST 2fa/recovery-codes {password},POST 2fa/disable {password}. These act only on yourself and need no special permissions.
History and trash
Every saved edit of a page, a record, a settings group and a menu is written to itk_revision: who, when, what changed, and the whole version. The core services write it in the same transaction as the edit. Edits from the console, imports and the queue are signed System. Edits through MCP are signed with the key name.
- Autosaves by one person with a gap of less than 10 minutes merge into one entry. An edit without changes leaves no entry.
- Actions:
create,edit,publish,unpublish,revert,delete,restore. - The
history.keep(entries per object and language, 100) andhistory.days(365) options set the depth.php bin/console itk:history:prune [--keep=N] [--days=N] [--dry-run]deletes the rest. The core has no schedule, so put the command in cron once a day. - Restoring a version (
POST history/revision/{id}/restore) makes that version the draft. The tree position and the template do not change, and nothing changes on the site until publication. Fields hidden bycanSee()orreadonly()stay as they are. - Trash. A deleted page or record is kept whole in history.
GET history/trashreturns deleted items. Restoring creates the object again with the same id, as a draft. If the parent is gone, the object goes to the top level. If the URL is taken, the response is 409. - API.
GET history/{page|item|settings|menu}/{id}?locale=&limit=&offset=,GET history/revision/{id},POST history/revision/{id}/restore,GET history/trash?kind=&key=. - The change description is written in the language of the person who made the edit and is not translated.
Concurrent edits
A page and a collection record return a version field, a hash of the draft. The admin autosave sends it as baseVersion. If the draft changed in the meantime (another person, an assistant through MCP, a move in the tree), the server writes nothing and returns 409 with details.code: "conflict" and details.current (version, by, at, via, viaName). The editor stops autosave and asks: Show the new version or Keep my edits.
A request without baseVersion is not checked: MCP tools, the console, site code, PATCH and publication work by the "last write wins" rule. MCP tools that change a page or a record run one at a time per object under a PostgreSQL advisory lock.
A collection record response always carries the service keys id, locale, translated, status, updatedAt, awaiting, returned, changed, changes and version. Do not give collection fields these names. itk:schema:lint and itk:doctor report the version key as an error.
Admin appearance
The developer sets the colors and the logo in the configuration. An administrator changes the colors in Settings → Admin panel appearance (the set:theme permission).
itk_cms: admin: theme: brand: '#0B5D80' # main color: left column, primary buttons, links accent: '#C8217A' # accent: unsaved-change marks, counters radius: 6 # corner radius of buttons and inputs, px, from 0 to 16 logo: /build/logo.svg # logo in the left column and on the sign-in page; null means the ITK CMS logo name: My Studio # name next to the logo, up to 40 characters; null means "ITK CMS"
- A palette from 50 to 950 in OKLCH is built from the color. A color on which neither white nor dark text is readable (contrast below 4.5:1) cannot be saved (422).
- The saved appearance is stored in the
adminThemesetting. Reset returns the developer's configuration. - Variables for plugin styles:
--brand,--brand-ink,--brand-text,--brand-50…--brand-950,--accent,--accent-ink,--accent-text,--accent-50…--accent-950,--r,--r-lg. - API:
GET admin-theme,POST admin-theme/preview,PUT admin-theme,DELETE admin-theme.
Admin language
The admin panel, its e-mails, the console and API messages are translated into English (en), Russian (ru) and Kazakh (kk). This is the interface language. It is not tied to the content language.
itk_cms: main_locale: en # content language, ru by default admin_locale: en # default admin language, en by default admin_locales: [en, ru, kk] # what a person chooses from; admin_locale must be in the list
Each person chooses a language in My profile (PUT {admin}/api/me/locale). An empty choice means admin_locale.
| Where | Language |
|---|---|
| The admin panel, its API, MCP | The person's language, otherwise admin_locale |
| Sign-in and password recovery pages | admin_locale |
| An e-mail to a specific person | That person's language |
| Request e-mails, Telegram and MAX messages | admin_locale |
| Console and worker | admin_locale |
| Site form responses | main_locale if it is in admin_locales, otherwise admin_locale |
| The preview canvas | The content language. The panel above a section is in the person's language |
The bundle turns on framework.translator and appends en to the end of fallbacks. In the console, the translator works in admin_locale. If site code calls trans() there, pass the language explicitly.
Your own wording. Server texts are in translations/itk_<area>.<language>.yaml. The areas are content, http, i18n, model, ops, preview. To change a phrase, put a file with the same name in the site's translations/ and list only the changed keys in it. This file does not change the texts of the Vue part of the admin panel. A plugin changes those with window.ITK.i18n.add('ru', {...}).
In PHP, Itk\Cms\I18n\I18n::t('area.key', ['name' => $x]) returns interface text. The count parameter and forms separated by | in the Symfony order set the plural. A key that is not in the catalog is returned as is, and a warning goes to the log. Twig has itk_t() and itk_locale().
A site does not register new interface languages. A language is added to the bundle itself. The steps are in CONTRIBUTING.md.
SEO
SEO rules for URLs
A URL rule sets the title, description, indexing (robots), canonical URL and social image for any site URL: a CMS page or a route of the site itself. Rules are edited in Settings → SEO → Address rules (the set:seo area). A rule wins over the page's own SEO, but changes only the fields it fills.
- A rule's address is a path with an optional query string (
/catalog,/catalog?page=2). A rule with parameters matches if the request has the same parameters. Extra parameters do not get in the way. match: exactapplies only to this URL.match: prefixapplies to the URL and everything inside it, by whole segments:/blogcovers/blog/a, but not/blogger.- Among matching rules, the most specific one wins: more parameters,
exactbeforeprefix, a longer path, a rule in the request's language, a newer rule. - A tag value comes from the rule, then from the page SEO, then from the page title (only
title), then from theitk_seo()argument. RelativecanonicalandogImagebecome full URLs. Rules do not apply on an error page.
The layout outputs the tags with itk_seo(). It works in any template and returns {title, description, robots, canonical, ogImage, rule}:
{% set seo = itk_seo({title: 'My site', robots: 'index,follow'}) %}
<title>{{ seo.title }}</title>
{% if seo.canonical != '' %}<link rel="canonical" href="{{ seo.canonical }}">{% endif %}
API: GET seo-rules?q=&locale=, POST seo-rules, PATCH|DELETE seo-rules/{id}. GET seo-rules/check?path=&locale= shows what answers the URL (a site route, a redirect, a CMS page or 404), which rules match, and where each tag comes from.
sitemap.xml
The core serves GET /sitemap.xml from the published pages. The site does not need to write a sitemap.
- The sitemap includes published pages, each with
<loc>and<lastmod>. Pages with indexing turned off (in the page SEO or by a URL rule) are left out. Collection records are not included. - URLs are built from the Site address setting (
domain), not from theHostheader. Without a scheme,https://is used. Until the address is set,/sitemap.xmlreturns 404. - The sitemap is cached for an hour. The cache is cleared when a page is published, unpublished, changed or deleted, and when a URL rule changes.
- A site's own
public/sitemap.xmlfile wins, because the web server serves it before PHP.
robots.txt and llms.txt
The core serves GET /robots.txt and GET /llms.txt (a site description for AI services in the llmstxt.org format). The text is edited in Settings → SEO → robots.txt and llms.txt (the set:seo area), and the edits go into history.
- The response comes from the first of these that exists: a file in the site's
public/, a custom text from the admin panel, the standard text. - The standard
robots.txtopens the site and closes the admin path,/request/and/mcp. It adds theSitemap:line when the Site address is set. - The standard
llms.txtis built from published pages by the same rules as the sitemap:# Site name,> SEO description of the home page, then## Pagesand a- [Title](url): descriptionline for each page. - A custom text is up to 64 KB. An empty field, the Back to the standard text button, and a text equal to the standard one all return the standard text.
- You cannot create a page with the URL
/robots.txtor/llms.txt. - The AI search line on Site status warns if
robots.txtcloses at least one AI bot: OAI-SearchBot, Claude-SearchBot, PerplexityBot, Googlebot, Bingbot, YandexBot, YandexAdditional, YandexAdditionalBot, ChatGPT-User, Claude-User, Perplexity-User, GPTBot, ClaudeBot, Google-Extended. - API:
GET {admin}/api/seo-filesreturns{robots: {text, default, custom, file}, llms: {...}}.PUT {admin}/api/seo-files {robots?, llms?}, wherenullor''returns the standard text.
schema.org markup
The core puts a <script type="application/ld+json"> block into every published page before </head>. You do not need to change the templates. The block's @graph contains:
WebSite: the URL, the name (siteName), the language.OrganizationorLocalBusiness: the name, the site URL, the logo, phone, e-mail, address (PostalAddress), social links (sameAs).BreadcrumbList: the chain of the page's published parents.BlogPostingfor a blog article: the headline, the date from the Date field or the publication date, the cover, the description, the author and the publisher.
The company data is in the Site group (see Settings). organizationLinks holds one http(s) link per line. schemaOrgOff turns the markup off.
- Without a Site address there is no block.
- The core does not repeat a type that the site already outputs in its own
application/ld+jsonblock.OrganizationandLocalBusinesscount as one type. - The preview has no block.
A listener of the Itk\Cms\Event\SchemaOrgGraph event adds your own types. The event has page (id, template, locale, title, url, fields), base, and the methods add(), remove(), nodes().
#[AsEventListener] final class ProductMarkup { public function __invoke(SchemaOrgGraph $graph): void { if ('product' !== $graph->page['template']) { return; } $graph->add([ '@type' => 'Product', 'name' => $graph->page['title'], 'offers' => ['@type' => 'Offer', 'price' => $graph->page['fields']['price'] ?? null, 'priceCurrency' => 'USD'], ]); } }
Analytics and verification codes
The owner enters counter IDs and verification codes in Settings → Analytics and webmaster tools (the set:analytics area, by default only the administrator has it). The core puts them on the pages.
| Field | Format |
|---|---|
Yandex Metrika: counter ID (yandexMetrikaId) |
4 to 12 digits |
Webvisor (yandexMetrikaWebvisor) |
A toggle. Works when a counter is set |
Google Analytics 4 (googleAnalyticsId) |
G-XXXXXXXXXX |
Yandex Webmaster, Google Search Console (yandexVerification, googleVerification) |
The code from the meta tag, or the whole meta tag. Latin letters, digits, - and _, 8 to 120 characters |
- Meta tags and scripts go before the first
</head>, and the Metrika<noscript>after<body>. - The tags go into CMS pages and pages of site controllers: the main request, status 200 or 404,
text/html, an ordinaryResponse. The preview, the admin panel, the API, MCP, the profiler, 304, redirects, streamed and compressed responses are not changed. - The core does not add a counter or a meta tag that is already in the HTML with the same ID or code.
- An invalid value is not output to the site. Site status shows it marked as warning.
- Cookie consent stays the site's job: the counters load right away. If the law requires consent, leave these fields empty and add the counters with your own code. A strict site CSP must allow
mc.yandex.ruandgoogletagmanager.com. The core does not mark the inline scripts with anonce.
Yandex Webmaster
The owner pastes a Yandex OAuth token once on the Today screen. After that, the screen shows whether ownership is verified, the site quality index (IKS), the number of pages in search, and popular queries.
Token. The server administrator registers an app at oauth.yandex.ru: the "Web services" platform, Redirect URI https://oauth.yandex.ru/verification_code, the webmaster:hostinfo and webmaster:verify permissions. The app ID goes into the ITK_YANDEX_CLIENT_ID variable (the yandex_webmaster.client_id option). Today then shows a link to get the token. Without the ID, the owner brings the token on their own. The token lives 6 months and is not renewed.
Connection. The core checks the token and finds the site with the Site address among the owner's sites, or adds it. The core puts the verification code on the pages as a yandex-verification meta tag and asks Yandex to check it. When ownership is verified, the core adds /sitemap.xml once. An address without a public host (localhost, an IP, .test and other special-use zones) cannot be connected.
- The summary is stored in the
cache.appcache and is refreshed when Today opens, if it is older than 6 hours. - The state (
stateinGET yandex-webmaster):not_connected,no_address,no_http_client,token_invalid,verifying,verification_failed,ready.tokenExpiresSooncomes 14 days before the token expires. - The token is stored encrypted with a key from
APP_SECRETand never appears in API responses, the log or the settings export. AfterAPP_SECRETchanges, enter the token again. - API (the
set:analyticsarea):GET yandex-webmaster(View),POST yandex-webmaster/connect {token}(Edit; 422 for an invalid token or address, 502 if Yandex does not respond),POST yandex-webmaster/refresh(View),DELETE yandex-webmaster(Edit; the site stays in Webmaster).
IndexNow
The IndexNow: tell search engines toggle (indexNow) is in the Analytics and webmaster tools group. When it is on, the core tells Yandex and Bing about a changed page URL using the IndexNow protocol: publication, a new URL (both the old and the new one are sent), unpublication, deletion, restoration.
- The URLs of pages from the sitemap are sent. Collection records are not sent.
- The worker collects up to 100 URLs and sends them in one request. The full URL is built from the Site address at the moment of sending.
- Responses
200and202count as success.429,5xxand a dropped connection are retried by theretry_strategyof theasynctransport. Other4xxgo straight to the failure transport. - The key is computed from the site address and
APP_SECRET, and nothing is stored. The key fileGET /{key}.txtresponds while the toggle is on. - Nothing is sent while the Site address is empty or not public, or without
symfony/http-client. - The
indexnow.endpointoption sets the receiver URL (by defaulthttps://yandex.com/indexnow). IndexNow search engines pass the notifications to each other. Google does not support IndexNow.
Requests and notifications
Receiving requests
A form is described in the schema: $s->form('call', 'Call request')->fields(...)->telegram('Request #{id}: {phone}'). The telegram() template sets the text of the Telegram and MAX message.
The site sends the form to POST /request/{form}. The hidden itk_hp field (a trap for bots) must be empty. The response is {"success": true} or {"success": false, "message": "…", "errors": {...}}. The limit is 10 requests in 15 minutes from one address (framework.rate_limiter.itk_request_form, the site can override it).
The request is saved and appears in the Requests section (the requests area). Then the request.new notification goes to the channels: the admin bell, Telegram, MAX and e-mail. A request has its own status for each messenger (channels). The overall delivery status is failed if the request did not reach at least one messenger, otherwise sent if it reached at least one. A messenger that is not connected leaves the status at pending, which is not a failure. To retry undelivered requests, use the button in the admin panel or php bin/console itk:requests:resend. The request JSON also has sendable: the messengers that never got the request and can take it now (connected, on, with a chat for the form). The request drawer shows Send to MAX or Send to Telegram for each of them and calls POST requests/{id}/resend {channel}.
The Requests screen has a Board view with the columns New, In progress and Closed.
Telegram
Telegram is optional. Without it, the request is saved, and the Telegram line on Site status says Telegram is not connected.
-
Install the packages:
composer require symfony/notifier symfony/telegram-notifier symfony/http-client. -
Set the bot token in Settings → Bots (see the section below). A token from the admin panel takes effect immediately. A fallback is set on the server:
framework: notifier: chatter_transports: telegram: '%env(TELEGRAM_DSN)%' # telegram://BOT_TOKEN@default
null://nulland an unset variable mean "not connected". -
Set the chats in Settings → Notifications (
tgRoutes). Theitk_cms.telegram.chat_idsoption sets fallback chats.
If Telegram is connected but a form has no chat, requests are saved without sending, and Site status warns about it. The itk_cms.telegram.enabled: false option turns sending off. Only a message that a connected Telegram refused counts as a failure. Such a request is marked as not delivered and is retried by retry_strategy.
MAX
MAX (max.ru) works alongside Telegram and independently of it.
-
Install the bundle:
composer require yuri-kovalev/max-bot-symfony-bundle. -
Set the token in Settings → Bots. The server fallback token:
# config/packages/max_bot.yaml max_bot: access_token: '%env(MAX_BOT_ACCESS_TOKEN)%' retry_attempts: [] # Messenger does the retries
-
Add the bot to a chat.
php bin/console max-bot:chatsshows the chat ID. Enter it in Settings → Notifications → MAX (maxRoutes, comma-separated integers; a group has a negative number).itk_cms.max.chat_idssets fallback chats.
The MAX switch (maxOn) and the itk_cms.max.enabled: false option work the same way as for Telegram. The Test button sends a test message. A MAX failure does not change the Telegram status, and the other way round.
Recipients are stored in the tgOn, tgRoutes, maxOn, maxRoutes and mailRoutes settings (the set:notifications area). GET settings returns them together with the flags tgFallback, maxFallback (a chat is set in the configuration), maxReady and mailReady. POST settings/telegram-test and POST settings/max-test {form?, chatId?} send a test message.
Bots
In Settings → Bots (the set:bots area, by default only the administrator has it) you set the Telegram and MAX tokens without editing files or restarting. A token from the admin panel wins over the server token. Without either, the messenger is not connected.
- The tokens are stored encrypted with a key from
APP_SECRETin thetelegramBotandmaxBotsettings. Do not declare schema fields with these keys. The tokens never appear inGET settings, history, the export or MCP. AfterAPP_SECRETchanges, the token from the admin panel counts as unset. GET {admin}/api/settings/botsreturns, fortelegramandmax, the fieldstokenSet,source(admin,serverornull),readyandproblem.PUT {admin}/api/settings/bots {telegram?: {token?, clear?}, max?: {token?, clear?}}. An emptytokenkeeps the old one, andclear: trueremoves the admin token. A Telegram token must match^\d{5,20}:[A-Za-z0-9_-]{30,}$. A MAX token has no spaces and is up to 512 characters. The token is never returned.
@BotFather issues the Telegram token. The MAX partner platform business.max.ru or dev.max.ru issues the MAX token.
The site sends e-mails: "set a password" links and e-mails about new requests. E-mails go through the async queue, so a worker is needed.
The mail server is chosen at the moment of sending:
- Settings → Mail is turned on and contains a server and a sender address.
- Otherwise, the
MAILER_DSNvariable, if it holds a real transport.null://nullmeans mail is not configured. - Otherwise, mail is not configured: e-mails are not sent, Forgot your password? suggests contacting the administrator, and invitation and reset show a one-time password.
The sender address comes from Settings → Mail. With only MAILER_DSN and no sender address, noreply@<site domain> is used.
The Mail settings (the set:mail area, by default only the administrator has it). Fields: enabled, host, port, encryption (none, ssl, starttls), username, password, fromAddress, fromName.
- The password is stored encrypted with a key from
APP_SECRETand is never returned. The response contains onlypasswordSet. An emptypasswordkeeps the old one, andclearPassword: trueerases it. - If
hostorusernamechanges, the new password must come in the same request, otherwise 422. This way the old password cannot be sent to another server. GET {admin}/api/settings/mailreturns the fields,passwordSet,configured,source(settings,env,none),problemandlast(the result of the last sending).PUT {admin}/api/settings/mailsaves the settings.POST {admin}/api/settings/mail-test {to?}sends a test e-mail right away, without the queue. The server's refusal reason comes in the response (502). At most 10 e-mails per hour per person (429).sslusessmtps://,starttlsrequires TLS, andnoneturns it off. The SMTP dialog is not logged.
Errors. An e-mail that was not sent after all retries stays in the failure transport, and a mail.failed notification comes to the bell. An e-mail with a "set a password" link is stored there whole, link included. Clean the failure transport (messenger:failed:remove) and do not give outsiders access to it.
Request e-mails. Settings → Notifications → Emails about new requests (mailRoutes, the set:notifications area): comma-separated addresses for all forms and a separate list for each form, up to 10 addresses. Each address gets an e-mail with the form fields and a link to the request.
E-mail templates. @ItkCms/email/layout.html.twig and the pairs reset_password, invite, request, test (.html.twig and .txt.twig). The site overrides any file with its own file in templates/email/, for example templates/email/layout.html.twig. Inside, you can extend the bundle template: {% extends '@ItkCms/email/reset_password.html.twig' %}.
Admin notifications and custom channels
Itk\Cms\Notification\NotifierInterface::notify() sends messages to the people who run the site. The core and site code call it.
$notifier->notify(new Notification( type: 'order.paid', title: 'Order #15 paid', body: '3,200 USD', link: '/collections/orders', // an admin route or a full http(s) URL level: Notification::WARNING, // INFO, WARNING, ERROR audience: 'col:orders', // null for everyone signed in; a permission ('requests', 'col:tours:edit'); 'role:editor' payload: ['orderId' => 15], // data for the channels, no secrets key: 'order.paid:15', // one notification per key ));
- Channels implement
NotificationChannelInterface(name(),supports(),send()), and theitk.notification_channeltag is added automatically. A class that is not a service is listed inRegistry::notificationChannels(). A channel error goes to the log and does not affect the others. DatabaseChannelstores the notification for the bell. A person sees the notifications that match their permissions and role and were sent after they registered.php bin/console itk:notifications:prune [--days=90] [--dry-run]deletes old ones. Put it in cron.TelegramChannel,MaxChannel,EmailChanneldeliver onlyrequest.new.- Core events:
request.new(a new request, for therequestspermission),telegram.failedandmax.failed(a request did not get through),mail.failed(an e-mail was not sent). A failure notification is removed when delivery succeeds. - Delivery outcome comes as the Symfony event
Itk\Cms\Event\RequestDelivery { request, delivered, error, cancelled, channel }.channelistelegramormax. - Language.
new Notification(title: …)stores ready text.Notification::translated(type: …, titleKey: 'area.key', titleParams: [...])stores a key, and each reader sees the title in their own language. - API.
GET notifications?unread=1&limit=&offset=,POST notifications/read { ids } | { all: true }. Each person reads only their own.
Knowledge base
The knowledge base is a pgvector table with the text of published pages and records, split into chunks with OpenAI embeddings. The KnowledgeBase\KnowledgeSearch service searches by meaning. The worker updates the index after publication and unpublication, and deletion removes the rows on its own. It is off by default.
What leaves the site. The published site text is sent to the OpenAI API. This is only what any visitor sees, but the site owner decides whether to send it. Drafts, hidden sections, raw() fields, fields with canSee() and pages with noindex are not sent.
How to turn it on. You need the symfony/http-client package and an OpenAI key.
-
Run
composer require symfony/http-client. Put the key in.env.local:OPENAI_API_KEY=sk-.... -
Turn on the option:
itk_cms: knowledge_base: enabled: true
-
Fill the index:
php bin/console itk:knowledge-base:sync --now. The command prints the number of texts sent and tokens spent. -
Start the worker for the
knowledge_basetransport. -
Test the search:
php bin/console itk:knowledge-base:search "how to return an item".
Add itk:knowledge-base:sync to the deploy script. The command queues only what went stale after the deploy (schema, configuration, model).
What is indexed. Pages from the sitemap (published, without noindex) and published collection records, except exclude_templates and exclude_collections. From each version, the text a visitor sees is taken: the title, the SEO description, the template fields, the visible sections in order. Text, Textarea, Headline, Description and Article give text. Select gives "label: option", Image and Photos give alt, and each Repeater row gives a separate block. Number, Toggle, Date, Link, Relation, Note, and variant(), raw() and canSee() fields are not indexed.
Chunks. The blocks of one section are combined into chunks of about 1200 characters, at most 2000. A chunk does not cross a section boundary, so a hit has an exact sectionId. The page title and the block heading are sent to the embedder before the chunk text.
Updates. An embedding is built only for text that is not yet in the index. The worker collects up to 32 messages into one API request. An unpublished page disappears from the results right away. A draft autosave triggers nothing. The index catches up with a publication within a minute, because the Doctrine transport polls the queues every check_delayed_interval (60 seconds). A separate messenger:consume knowledge_base worker is faster.
Changing the model. After model changes, the search finds nothing until itk:knowledge-base:sync --now rebuilds the index. Site status shows how many documents are left in the old model.
Searching from code.
$result = $knowledge->search($request->query->getString('q'), new SearchOptions(limit: 20)); foreach ($result->bySource() as $hit) { // $hit->source->title, $hit->source->url, $hit->text }
SearchOptions:locale,limit(1 to 50, 8 by default),templatesandcollections(nullfor all,[]for none),minScore.SearchResult::$hitsis a list ofHitin descendingscoreorder.bySource()keeps the best hit per page or record.Hit:score,text,heading,source(kind,id,locale,resourceKey,title,url),sectionId,sectionType,field.- A disabled knowledge base or an API failure throws
KnowledgeBaseUnavailable. An unknown template or collection throws\InvalidArgumentException.
Commands. itk:knowledge-base:sync queues missing, stale and extra documents. --now does it in-process and exits with code 1 on failure. --dry-run prints the counters and an estimated cost. --source=page:<id>[:<locale>] or item:<id>[:<locale>] limits it to one source. itk:knowledge-base:search "<query>" [--locale=] [--limit=8] [--template=] [--collection=] prints the hits as a table.
Failures. 429, a server error and a network drop are retried after 10, 30, 90, 270 and 810 seconds, and then the message goes to the failure transport. An invalid key, an unknown model and a missing symfony/http-client go straight to the failure transport. After you fix the cause, messenger:failed:retry brings them back.
A site can replace the embedder with its own implementation of KnowledgeBase\Embedding\Embedder with 1536-dimensional vectors.
Performance
Headers and 304 responses
- Security headers. The public routes of the bundle (pages,
sitemap.xml,robots.txt,llms.txt, image copies,POST /request/{form},/healthz) getX-Content-Type-Options: nosniffandReferrer-Policy: strict-origin-when-cross-origin. Thesecurity_headers: falseoption turns them off. The site sets headers for its own controllers itself. - ETag and 304. A visitor without a session and without
AuthorizationgetsETag,Last-ModifiedandCache-Control: no-cache, privatefor a page. If the visitor sends the sameETaginIf-None-Match, a 304 response comes without rendering. - The tag depends on everything the page can show: the page itself, the published pages and their order, settings, menus, published records, image crops, SEO rules, the query string, the container build and the current UTC date. Drafts do not affect the tag. So a page that depends on the time of day updates at least once a day. If pages must update more often, turn off
conditional_responses. - The tag needs one query with sums over the tables, including all collection records. On 30,000 records this takes about 0.1 seconds. The same query builds the page cache key. For a site with very large collections, turn off both
conditional_responsesandpage_cache.enabled. - Debug mode sends no tag. In production, run
cache:clearafter you deploy new templates. Otherwise visitors with a cached page get 304 with the old markup.
Page cache
The rendered HTML of a published page is cached, and a repeat view is served without rendering. Edits are visible to visitors right away: the entry key is built from the same fingerprint as the ETag, and any edit gives a new key.
- Key. The scheme, the host, the base path and the content fingerprint. Cookies,
User-Agent,Accept-Languageand other headers are not part of the key. - What is stored. Only a
200response toGETwithoutSet-Cookie, if no session was started. 404, redirects, the preview,sitemap.xml,robots.txt,llms.txtand forms are not stored.HEADuses the entry made byGET. - Requests that bypass the cache: when the option is off and in debug, with
Authorizationor a session, with a method other thanGETandHEAD, with a query string, with aForwardedorX-Forwarded-Prefixheader, with a URL spelling that differs from the page URL (/ABOUT,//about), and to a host or port that is not trusted (not inframework.trusted_hosts, or, without trusted hosts, not the host and port of the site address). This way an outsider cannot fill the disk with entries or replace a page for everyone. - Your host. A host is cached if
framework.trusted_hostsis set or the host matches the Site address. The port must be the default port or the port from the Site address. Otherwise the cache does not work. A site behind a proxy setstrusted_proxies. X-ITK-Cache. Every page response carriesHIT,MISSorBYPASS. You can check the cache withcurl -I. A 304 reportsHIT.- What the fingerprint does not see. Data in the site's own tables and the time within a day. For those there is the entry lifetime
page_cache.ttl(3600 seconds) and theitk_cache()function.{% do itk_cache(300) %}keeps the rendering for at most 300 seconds, and{% do itk_cache(false) %}does not keep it at all. Among several calls,falsewins, otherwise the smaller number. A template whose output depends on a cookie,User-AgentorAccept-Languagemust call{% do itk_cache(false) %}.itk_cache()does not affect 304. - Manual clearing.
PageCache::clear()from site code (returnsfalseif the pool failed), theitk:cache:clearcommand, and the Clear the page cache button on Site status (POST {admin}/api/health/page-cache/clear, the Edit level of thedevarea). Only the page cache pool is cleared. - Storage. The
itk_cms.page_cachepool on thecache.appadapter. On one server these are files invar/cache/<env>/pools. For several servers, give the pool a shared adapter inframework.cache.pools. Expired entries are deleted at most once every 10 minutes. Putbin/console cache:pool:prunein cron.
Critical CSS
The rules the first screen needs go straight into <head>, and the full stylesheet loads without blocking rendering. crittr extracts the rules in the worker after each publication. It is off by default.
How to turn it on. You need Node 22 or newer and Chrome or Chromium on the server.
-
In the project root, run
npm install crittr. Puppeteer downloads Chrome for the user who ran the command. To use the system Chrome, set thechromeoption. -
Turn on the option and list the stylesheets:
itk_cms: critical_css: enabled: true stylesheets: ['/css/site.css']
-
In the layout, replace
<link rel="stylesheet" href="/css/site.css">with{{ itk_stylesheets() }}. -
Test one page:
php bin/console itk:critical-css:generate --page=<id> --now. The command prints the reason for each failure. -
Start the worker for the
critical_csstransport. -
Queue the remaining pages:
php bin/console itk:critical-css:generate(--allfor all published pages).
What the visitor gets. On a page with ready critical CSS, itk_stylesheets() prints:
<style>…</style> <link rel="stylesheet" href="/css/site.css?v=3f9a1c2e" media="print" onload="this.media='all'"> <noscript><link rel="stylesheet" href="/css/site.css?v=3f9a1c2e"></noscript>
In all other cases (turned off, not ready yet, failed, preview, a site controller, an error page), the function prints an ordinary link. ?v= changes together with the stylesheet. While the option is off, there is no ?v=.
<style>holds the union of the rules of all windows fromviewports, with the cascade preserved. If the windows cannot be reconciled, one<style media="…">per width range is output.- Critical CSS goes stale when the page is published again, when the container is rebuilt and when the stylesheets change. The stale CSS is shown while the worker builds a new one. The first view asks the worker to recompute the page. After you deploy new CSS, you do not need to do anything.
itk:critical-css:generatein the deploy script only speeds up the recomputation. - Settings, menus and collection records do not affect critical CSS. If a menu changed the first screen, run
itk:critical-css:generate --all. - A page that crittr failed on is not recomputed automatically again.
itk:critical-css:generate, a new publication or new CSS retries it. - A result larger than
max_kbcounts as a failure. If the CSS has!importantor@layer, the worker writes a warning, because crittr loses them. - The generator does not work with the
synctransport.
CSP. <style> requires style-src 'unsafe-inline' or a nonce. {{ itk_stylesheets({nonce: nonce}) }} puts the nonce on each <style> and on the link. A nonce does not cover the onload attribute. For it, allow the handler hash: script-src 'unsafe-hashes' 'sha256-MhtPZXr7+LpJUY5qtMutB+qWfQtMaPccfe7QXtCcEYc='. Without this, the full stylesheet stays at media="print".
In Docker, the image is built with Node and Chromium with the CRITICAL_CSS=1 argument (see Critical CSS in Docker).
MCP: AI assistants
ITK CMS works as a Model Context Protocol server. Claude, Cursor, VS Code and other clients read the site and prepare edits in drafts. The assistant acts on behalf of the staff member who issued the key and never gets more than that person's permissions. Every call goes through the same permissions, field rules, hooks and history as the admin API.
Turning it on and keys
-
The switch. Settings → AI assistants (the
set:mcparea, by default only the administrator has it). While MCP is off,/mcpreturns 404,itk:mcpdoes not start, and keys are not created. This screen shows the server address, connection examples and the list of all staff keys with a Revoke button. -
The key. My profile → My keys for AI assistants: a name, scopes and a lifetime (30 or 90 days, a year, no expiry; 90 days by default). The key looks like
itk_plus 43 characters and is shown once. The database stores its sha256. A person has at most 20 active keys and 10 new ones per hour. A key can be created only from a session that passed two-step sign-in, if it is turned on. -
Scopes. A scope narrows the person's permissions. A tool needs both the key's scope and the person's permission.
Scope What it grants Default readView pages, records, the media library, menus, settings, SEO, history yes writeCreate and change drafts, upload files no publishPublish and unpublish (requires the Publish permission) no requestsRead and handle requests, including customer phone numbers no requestscannot be combined withwriteandpublishin one key. Visitors write requests, and a key that reads them and changes pages could carry out someone else's instruction from a request. The server answers such a key with 422. If you need both scopes, you need two keys. -
What stops a key. Revocation, expiry, blocking of the owner, the switch turned off, a role that now requires two-step sign-in. A new owner password does not stop the keys. Permissions are taken at the moment of the call. The key is checked on every message, so revocation also stops an assistant that is already running.
Connecting
HTTP: each call is a POST /mcp with the Authorization: Bearer itk_… header. The response is application/json, without sessions or an event stream.
# Claude Code claude mcp add --transport http mysite https://example.com/mcp --header "Authorization: Bearer itk_…"
// Claude Desktop, claude_desktop_config.json (requires Node.js; mcp-remote connects the app to the site) { "mcpServers": { "mysite": { "command": "npx", "args": ["-y", "mcp-remote", "https://example.com/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer itk_…" } } } }
// Cursor: ~/.cursor/mcp.json or .cursor/mcp.json in the project; the key is in an environment variable { "mcpServers": { "mysite": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ${env:ITK_MCP_TOKEN}" } } } }
// VS Code (GitHub Copilot, agent mode): .vscode/mcp.json; the key is kept in secure storage { "servers": { "mysite": { "type": "http", "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ${input:itk-key}" } } }, "inputs": [ { "type": "promptString", "id": "itk-key", "description": "ITK CMS key", "password": true } ] }
claude.ai. In Customize → Connectors, add your own connector with the address https://example.com/mcp, the authentication method "No authentication", and an Authorization header with the value Bearer itk_… in the "Request headers" section. Request headers are not available to every organization. One key serves all users of the connector, and it cannot be changed after saving. The site must be reachable from the internet over HTTPS.
stdio: the assistant starts itk:mcp itself. Pass the key in the ITK_MCP_TOKEN variable, not with --token, because other users of the machine can see arguments in the process list.
{ "mcpServers": { "mysite": { "command": "php", "args": ["/var/www/site/bin/console", "itk:mcp"], "env": { "ITK_MCP_TOKEN": "itk_…" } } } }
// in Docker
{ "mcpServers": { "mysite": { "command": "docker",
"args": ["compose", "--project-directory", "/path/to/site", "exec", "-T", "-e", "ITK_MCP_TOKEN", "php", "bin/console", "itk:mcp"],
"env": { "ITK_MCP_TOKEN": "itk_…" } } } }
The server supports protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. The server does not support the 2026-07-28 revision without the initialize handshake: it answers an unknown MCP-Protocol-Version header with 400. OAuth authorization is not offered.
Tools
| Scope | Tools |
|---|---|
read |
site_schema, pages_list, page_get, collection_list, collection_item_get, media_search, media_get, menus_get, settings_get, seo_rules_list, history_list |
write |
page_create, page_update, page_section_add, page_section_update, page_section_move, page_section_remove, collection_item_create, collection_item_update, media_upload |
publish |
page_publish, page_unpublish, collection_item_publish |
requests |
requests_list, request_get, request_update |
site_schemawithout arguments gives an overview, and withkindandkeythe full description of one section. Theitk://schemaresource returns the same.settings_getdoes not return passwords, tokens, the mail server, chats or notification addresses.media_uploadaccepts a base64 file of up to 5 MB. The server does not download files by URL.page_unpublishleaves the page as a draft. The home page cannot be unpublished.- Through MCP you cannot delete pages, records, files or rules, change users, roles, keys, settings or redirects, or restore versions.
- Nobody changes
raw()fields through MCP, not even an administrator. Removing or moving a section or a list item with such a field is allowed. - The assistant can put only a file from the media library into an image field.
- An error that the model can fix comes as a result with
isError: trueand a text. Protocol errors come as JSON-RPC codes. - Tools that replace values, publish or unpublish carry the
destructiveHint: truehint. - The assistant's edits go into history marked as made through an AI assistant, with the key name.
Protection
- A request with an
Originheader is accepted only if it is the site address, an address frommcp.allowed_origins, or localhost in debug. Everyone else gets 403. Assistant programs do not sendOrigin. This is not CORS: the server answersOPTIONSwith 405. - The limit is 120 calls per minute per key (
itk_mcp_token), and each message in a batch counts as a call. 20 invalid keys in 15 minutes from one address give 429 (itk_mcp_failed_auth). The limits useframework.lock. On several servers, set a shared lock store. - The request body is at most
mcp.max_body_mb(8 MB). Formedia_upload, raise the web server'sclient_max_body_sizeand PHP'spost_max_size. - The
Authorizationheader must reach PHP. On Apache, addSetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1. - The core owns the
/mcpURL, and you cannot create a page with that URL. - Visitor texts from requests reach the model inside an
<untrusted-data>…</untrusted-data>frame. The frame is a hint to the model, not a protection. The protection is the separate keys for requests and edits, and the ban on writingraw(). - Give a key the minimum scopes and lifetime. A key is equal to a password within its permissions: keep it in a password manager, and revoke it if it leaks.
Log
The itk_mcp Monolog channel gets each tool call and resource read as an info line, and each refusal as a warning line: a sign-in refusal (missing, invalid, revoked, expired, blocked, two_factor, too_many_wrong_keys), an unknown tool, invalid arguments, a limit. Arguments, responses and the key are never written. The fingers_crossed handler drops these lines if the request has no error. Give the channel its own handler:
# config/packages/monolog.yaml when@prod: monolog: handlers: main: type: fingers_crossed action_level: error handler: nested channels: ["!itk_mcp"] mcp_audit: type: stream path: php://stderr level: info channels: [itk_mcp] formatter: monolog.formatter.json
Custom tool
final class ToursCountTool extends AbstractMcpTool { public function __construct(private readonly TourRepository $tours) {} public function name(): string { return 'tours_count'; } public function description(): string { return 'Count tours by state.'; } public function inputSchema(): array { return self::schema(['state' => self::string('draft or published', 20)], ['state']); } public function requiredScope(): string { return McpScopes::READ; } public function annotations(): array { return ['readOnly' => true, 'destructive' => false, 'idempotent' => true]; } public function call(array $args, McpContext $context): array { $context->require('col:tours', 'view'); return ['count' => $this->tours->countByState((string) $args['state'])]; } }
- A service with
McpToolInterfaceis picked up automatically (theitk.mcp_tooltag). A class without constructor arguments can be listed in an extension:$registry->mcpTools(ToursCountTool::class). - Write the description for the model in English.
requiredScope()returnsREAD,WRITE,PUBLISHorREQUESTS. annotations()is required and must contain the booleansreadOnlyanddestructive. There is no default.- The tool set is checked on the first build. Two classes with one name, an unknown scope or incomplete
annotations()throwMcpToolListErrorwith the class names. The client getsInternal error, and the text goes to theitk_mcpchannel. - Arguments are validated against
inputSchema()before the call:type,enum,required,properties,additionalProperties,items,minimum,maximum,minLength,maxLength,minItems,maxItems. - If the input needs fixing, throw
McpToolExceptionwith a clear text. A tool that not everyone can use implementsMcpConditionalTool::isAvailableTo(). - A tool that writes calls the core services (
PageService,CollectionService), not the database. Permissions, hooks and history then work automatically.
Site status and itk:doctor
The Site status screen
For developers → Site status ({admin}#/health) is the screen for the person who looks after the site. The dev area: View opens the screen, and Edit allows retrying and deleting failed jobs, sending requests again and clearing the page cache. By default only the administrator has this area.
- Background jobs. How many messages wait in each queue, and up to 50 latest failed ones from the failure transport: the job, the reason, the number of attempts. Try again returns the message to its queue, and Delete removes it. A transport that could not be built is shown with the reason.
- Undelivered requests. The latest 20 undelivered requests, without names and phone numbers. Send again sends the request to the messenger it did not reach.
- Schedule. Symfony Scheduler tasks (
#[AsSchedule]) and the time of the next run, if there are any. - Disk. Free space for
upload_dirandvar/. Less than 2 GB gives a warning, less than 512 MB gives an error. - Versions. PHP, Symfony and
itk/cms. The update check works when theupdate_sourceoption is set. It accepts a URL that returns{"version": "…"}, GitHubreleases/latest, or Packagist metadata, for examplehttps://repo.packagist.org/p2/itk/cms.json. The response is cached for 12 hours. - Core checks. Database, PHP,
APP_SECRET, upload folder, mail, Telegram, MAX, MCP firewall, analytics, Yandex Webmaster, IndexNow, AI search (AI bots closed inrobots.txt), critical CSS, knowledge base. Each check showsok, Not connected, warning or error. Not connected (off) is a yellow chip for a module that is switched off or not set up, for example Yandex Webmaster, Telegram or IndexNow. It is not a problem: the overall status of the screen and the exit code ofitk:doctor --cido not change. - API (the
devarea):GET health,POST health/messenger/{id}/retry|delete,POST health/requests/{id}/resend {channel?},POST health/updates/refresh,POST health/page-cache/clear.
Custom checks. A class implements Itk\Cms\Health\HealthCheckInterface: name() and check(): HealthResult (HealthResult::ok|off|warn|fail('text')). Return off when the module is switched off or not connected: it ranks like ok and does not turn the report into a warning. In a folder that the site container scans, the class is picked up automatically (the itk.health_check tag). From a package, list it in Registry::healthChecks(). A check must be fast. An exception shows as an error line and does not break the screen.
itk:doctor
php bin/console itk:doctor checks the site in one pass. The command suits deploys and CI.
| Group | What it checks |
|---|---|
| Environment | PHP extensions, WebP, AVIF, APP_SECRET, permissions on upload_dir, database |
| Site | Trusted site address, applied migrations, published home page, firewalls of the admin panel and /mcp, queue and worker (messages older than 5 minutes), built admin panel |
| Site status | Everything the Site status screen shows |
| Schema | The same as itk:schema:lint |
Each line is ok, off, warning or ERROR. off marks a module that is not connected and is only counted in the total. With --ci, the command exits with code 1 if there is at least one error.
/healthz
GET /healthz is an open URL for a load balancer: {"status":"ok"} (200) or {"status":"fail"} (503). It checks that the database responds and that a file can be written to upload_dir. You cannot create a page with the URL /healthz.
Console commands
| Command | What it does |
|---|---|
itk:install |
Prepares the site: roles, menu areas, default settings, the queue table, the home page, the first administrator. Options --email, --password, --name, --site-name, --domain, --no-home |
itk:doctor [--ci] |
Checks the site |
itk:schema:lint |
Checks the schema and the Twig templates |
itk:user:password <email> [--password=] |
Sets a password |
itk:user:reset-2fa <email> |
Resets two-step sign-in |
itk:requests:resend |
Queues all undelivered requests |
itk:media:warm [--width=] |
Creates copies of the media library images |
itk:cache:clear |
Clears the page cache |
itk:critical-css:generate |
Queues pages without ready critical CSS. --all for all pages, --page=<id>, --locale=, --dry-run, --now in this process with a failure report |
itk:knowledge-base:sync |
Updates the knowledge base. --now, --dry-run, --source= |
itk:knowledge-base:search <query> |
Searches the knowledge base. --locale, --limit, --template, --collection |
itk:history:prune |
Deletes old history. --keep, --days, --dry-run |
itk:notifications:prune |
Deletes old notifications. --days (90), --dry-run |
itk:mcp |
The MCP server over stdio. The key is in ITK_MCP_TOKEN |
itk:make:template, itk:make:section, itk:make:collection, itk:make:settings, itk:make:field, itk:make:plugin |
Code generators, see Code generators |
Cron usually runs itk:history:prune, itk:notifications:prune and cache:pool:prune once a day.
Configuration reference
All options are set in config/packages/itk_cms.yaml and are optional.
| Option | Default | What it does |
|---|---|---|
schema_file |
%kernel.project_dir%/config/itk/schema.php |
The site schema file |
main_locale |
ru |
The content language |
admin_locale |
en |
The default admin language. Must be in admin_locales |
admin_locales |
[en, ru, kk] |
The languages a person chooses from |
admin_path |
/admin |
The admin path. The format is checked at startup |
public_url |
null |
The site address for links in e-mails, for example https://example.com. %env(PUBLIC_URL)% works |
strict |
null (as kernel.debug) |
Strict template mode |
blog |
true |
false removes the blog templates |
security_headers |
true |
Security headers on public routes |
conditional_responses |
true |
ETag, Last-Modified and 304 for pages |
page_cache.enabled |
true |
The page cache |
page_cache.ttl |
3600 |
The entry lifetime in seconds, at least 1 |
upload_dir |
%kernel.project_dir%/public/uploads/media |
The media library folder |
upload_url |
/uploads/media |
The URL of the media library folder |
max_upload_mb |
20 |
The media library file size limit |
images.widths |
[320, 640, 960, 1280, 1920, 2560] |
Copy widths |
images.quality |
82 |
WebP quality |
images.avif_quality |
60 |
AVIF quality |
images.max_pixels |
50000000 |
An original larger than this is not converted |
images.ratios |
['16:9', '4:3', '1:1', '3:4'] |
Crop ratios |
history.keep |
100 |
History entries per object and language |
history.days |
365 |
The age of history entries |
admin.theme.brand, admin.theme.accent |
#0B5D80, #C8217A |
Admin colors |
admin.theme.radius |
6 |
Corner radius, from 0 to 16 px |
admin.theme.logo, admin.theme.name |
null |
The logo and the name in the admin panel |
critical_css.enabled |
false |
Critical CSS |
critical_css.stylesheets |
[] |
Public paths of the stylesheets in cascade order. At least one is needed when it is on |
critical_css.viewports |
390×844 (phone), 1366×900 |
Windows {width, height, mobile} |
critical_css.keep_selectors, critical_css.remove_selectors |
[] |
Selectors that crittr always keeps or drops |
critical_css.node |
node |
The Node program |
critical_css.chrome |
null |
The path to Chrome. null means PUPPETEER_EXECUTABLE_PATH or the Chrome from puppeteer |
critical_css.timeout |
60 |
Seconds per page in one window, at least 10 |
critical_css.max_kb |
75 |
The critical CSS limit in KB |
knowledge_base.enabled |
false |
The knowledge base |
knowledge_base.model |
text-embedding-3-small |
A text-embedding-3-* model, 1536-dimensional vectors |
knowledge_base.base_url |
https://api.openai.com/v1 |
An OpenAI-compatible API |
knowledge_base.timeout |
30 |
Seconds per request, at least 5 |
knowledge_base.exclude_templates, knowledge_base.exclude_collections |
[] |
What is not indexed |
indexnow.endpoint |
https://yandex.com/indexnow |
The IndexNow receiver |
yandex_webmaster.client_id |
%env(string:default::ITK_YANDEX_CLIENT_ID)% |
The Yandex OAuth app ID |
yandex_webmaster.api_base |
https://api.webmaster.yandex.net/v4 |
The Webmaster API URL |
mcp.allowed_origins |
[] |
Allowed Origin values for /mcp |
mcp.max_body_mb |
8 |
The /mcp request body limit, from 1 to 64 |
telegram.enabled |
true |
Sending requests to Telegram |
telegram.chat_ids |
'' |
Comma-separated fallback chats. %env(...)% works |
max.enabled |
true |
Sending requests to MAX |
max.chat_ids |
'' |
Fallback MAX chats, comma-separated integers |
update_source |
null |
The URL for checking for a new version |
The bundle sets the limits in framework.rate_limiter, and the site can override them under the same names:
| Limiter | Value |
|---|---|
itk_request_form |
10 requests in 15 minutes per address |
itk_password_change |
5 attempts in 15 minutes per person |
itk_password_reset_ip, itk_password_reset_email, itk_password_reset_guess |
10 per hour per address, 3 per hour per e-mail, 10 invalid links in 15 minutes |
itk_mail_test |
10 test e-mails per hour per person |
itk_mcp_token, itk_mcp_failed_auth, itk_mcp_token_create |
120 calls per minute per key, 20 invalid keys in 15 minutes per address, 10 new keys per hour |
Extensions and generators
Extensions
A package or the site itself connects to the core with a class that implements ItkExtensionInterface. The itk.extension tag is added automatically.
final class ToursExtension implements ItkExtensionInterface { public function register(Registry $r): void { $r->resources(ToursCollection::class, TourTemplate::class) // also sections(), templates(), collections(), settings() ->twigPaths(__DIR__ . '/../templates', 'Tours') // {% include '@Tours/block.html.twig' %} ->menu(NavItem::make('Reports', '/x/reports')->group('Analytics', icon: 'chart', order: 60)->icon('chart')->canSee('col:tours')) ->adminAssets(js: ['/bundles/tours/admin.js'], css: ['/bundles/tours/admin.css']) ->notificationChannels(SmsChannel::class) ->healthChecks(DiskCheck::class) ->mcpTools(ToursCountTool::class); } }
Registryis called once per request. Classes come from the container if they are there, otherwise they are created without arguments.twigPaths()adds folders to Twig, including for the console andlint:twig.NavItemis an admin menu item that is not a collection.tois a route of the admin client. The default group is Plugins (order800).adminAssets()loads scripts as<script type="module">and styles after the main admin code. It accepts/…andhttp(s)://…URLs. A plugin callswindow.ITK.registerPlugin({ fields, panels, actions, previews })and getswindow.ITK.vue,http,toast,confirm,i18n,ui(includingSortableTreeandKanbanBoard). Details are in admin/src/README.md.
Code generators
The commands create a ready class in the site and, where needed, a Twig or JS stub. The classes go into src/Itk/… and are picked up automatically. In production, run cache:clear after you generate a class.
| Command | Creates |
|---|---|
itk:make:template <key> [title] |
src/Itk/Template/<Key>Template.php and templates/pages/<key>.html.twig |
itk:make:section <key> [title] [--group=] |
src/Itk/Section/<Key>Section.php and templates/sections/<key>.html.twig. Without --group, it writes ->group('Тексты и картинки'), the default group, which the admin panel shows in the interface language |
itk:make:collection <key> [title] [--group=] [--icon=] |
src/Itk/Collection/<Key>Collection.php |
itk:make:settings <key> [title] |
src/Itk/Settings/<Key>Settings.php |
itk:make:field <type> [title] |
src/Itk/Field/<Type>Field.php and the admin component public/itk/fields/<type>.js |
itk:make:plugin <key> [title] |
src/Itk/Plugin/<Key>Extension.php and the admin screen public/itk/plugins/<key>/admin.js |
- Without a key or a title, the command asks for them. With
-n, the key is required. - An existing class is not overwritten without
--force(exit code 1). Existing Twig and JS stubs are replaced only with--force. --dry-runshows the files and the class without writing them.--dir=src/Other/Folderchanges the class folder withinautoload.psr-4.- A key taken by another class of the same kind or by
schema.phpis not accepted. - An extension loads the field script:
$registry->adminAssets(js: ['/itk/fields/rating.js']).
Collection from a description or a table
php bin/console itk:make:collection --from=form.json
php bin/console itk:make:collection --from=table:table_name [--import] [--publish] [--map=…]
The JSON description: {"key": "tours", "title": "Tours", "singular": "tour", "icon": "map", "fields": [{"key": "city", "label": "City", "type": "text", "required": true, "max": 80}], "rows": [{"id": 1, "city": "Perm"}]}. Types: text, textarea, description, headline, article, number, toggle, select (with "options"), date, datetime, image, photos, link. rows are needed only for --import. Add a repeater or a relation to the class by hand.
From a PostgreSQL table, the columns become fields. Write a table in another schema as table:schema.table. --connection=name sets another Doctrine connection.
| Column | Field |
|---|---|
character varying, character |
Text (a length up to 1000 becomes max) |
text, json, jsonb |
Textarea |
smallint, integer, bigint, numeric, real, double precision |
Number |
boolean |
Toggle |
date |
Date |
timestamp |
DateTime |
time |
Text |
an enum type (CREATE TYPE … AS ENUM) |
Select |
- Other types are skipped with an explanation.
NOT NULLwithout a default givesrequired(). The label comes from the column comment or the name. The primary key does not become a field. --map=column:field[:type],…renames a column or changes its type.column:-skips the column.--strip-prefix=old_drops the start of the table name when the key is chosen.--id=columnsets the row key if there is no primary key or it is composite.--importmoves the rows into records as drafts, with the usual checks and hooks. A repeat run updates its own records instead of creating new ones.--publishpublishes the records right away. A row without a required field stays a draft and goes into the report.
Docker
The package ships a ready Docker kit in vendor/itk/cms/docker. You copy it into the site and then edit it as your own files.
| File | Contents |
|---|---|
compose.yaml |
The services php (php-fpm), nginx, worker, database (PostgreSQL 17 with pgvector) and mailer (Mailpit). Ports are open only on 127.0.0.1 |
Dockerfile |
The stages php_base, php_dev, php_prod, PHP extensions, Composer, health check |
Dockerfile.dockerignore |
What stays out of the image: .git, vendor, node_modules, var, public/uploads, public/bundles, .env.local, .env.*.local, .env.local.php, the secrets decryption key, compose.override.yaml |
nginx/default.conf |
Static files, caching of build files, headers, passing to index.php |
php/conf.d/10-app.ini, php/php-fpm.d/zz-app.conf |
PHP and php-fpm settings |
php/docker-entrypoint.sh |
On php start: composer install, assets:install, waiting for the database, migrations, itk:install |
Build arguments: PHP_VERSION (8.4 by default), CRITICAL_CSS (0 or 1), UID and GID (the www-data user gets your IDs).
First run
The host needs only Docker.
-
Create the site and install the package with the Composer image.
--ignore-platform-reqsis needed because the Composer image lacks the PHP extensions the bundle requires. Thephpcontainer has them.docker run --rm --user "$(id -u):$(id -g)" -v "$PWD":/app -w /app composer:2 create-project symfony/skeleton:"7.4.*" mysite cd mysite docker run --rm --user "$(id -u):$(id -g)" -v "$PWD":/app -w /app composer:2 \ sh -c 'composer config extra.symfony.docker false && composer require itk/cms --ignore-platform-reqs --no-scripts'
-
Copy the kit to the site root:
cp -R vendor/itk/cms/docker docker mv docker/compose.yaml compose.yaml
-
Do steps 3 to 5 of the quick start (
config/routes/itk.yaml,security.yaml,itk_cms.yaml) and putAPP_SECRETin.env.local.compose.yamlsetsDATABASE_URL. -
Set variables if needed. Compose reads them from the shell environment and from the
.envnext tocompose.yaml. That is the site's.env, which is in git, so write only safe values into it.Variable Default What it does HTTP_PORT,DB_PORT,MAILPIT_PORT8080,5433,8025Ports on the host DB_NAMEappThe database name DOCKER_APP_ENVdevAPP_ENVin the containersCOMPOSE_PROJECT_NAMEthe directory name The project name. Each site has its own PHP_VERSION8.4The PHP version CRITICAL_CSS01adds Node 22 and Chromium to the imageADMIN_EMAIL,ADMIN_PASSWORDempty If both are set, the administrator is created at start SITE_NAME,SITE_DOMAINempty The name and domain for itk:installUID,GID1000The container user. On Linux, set your own values in .env(id -u,id -g)Do not write the administrator password into
.env: it would end up in git and in thephp_prodimage. Pass it once from the shell, or create the administrator in step 6. -
Start:
docker compose up -d --build docker compose logs -f php # wait for the "ready to handle connections" lineTo turn off migrations and
itk:installat start, setAUTO_MIGRATE: "0"in theenvironmentof thephpservice. -
Create the administrator if you did not set
ADMIN_EMAILandADMIN_PASSWORD:docker compose exec php bin/console itk:install --email=you@example.com --site-name="My site" --domain=example.com
The site opens at http://localhost:8080, and the admin panel at http://localhost:8080/admin/login. Publish the home page in the admin panel.
If it does not start.
- The
[entrypoint] ... failedlines indocker compose logs phpname the step where the container stopped. - On the first start,
nginxandworkerwait untilphpfinishescomposer install. Wait and rundocker compose up -dagain. - A port is taken: set other
HTTP_PORT,DB_PORT,MAILPIT_PORTvalues. docker compose down -vdeletes the volumes, including thepostgres_datadatabase.
Mail and worker
Mailpit collects all e-mails: http://localhost:8025. The containers set MAILER_DSN=smtp://mailer:1025 and MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0.
The worker service is built from the same image and runs messenger:consume async critical_css knowledge_base --time-limit=3600 --memory-limit=256M. After an hour it exits, and restart: unless-stopped starts it again. The worker keeps code in memory: after you edit PHP, configuration or templates, run docker compose restart worker. If the site declared its own transports, change command.
Critical CSS in Docker
Node, crittr and Chrome must be in the same image as PHP: php-fpm runs the check, and the worker computes the pages.
-
Build the image with Node and Chromium:
echo 'CRITICAL_CSS=1' >> .env docker compose up -d --build
The image sets
PUPPETEER_SKIP_DOWNLOAD=1andPUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium, so you do not need to set thechromeoption. -
Install crittr inside the container:
docker compose exec php npm install 'crittr@^5'. Addnode_modulesto.gitignore, and commitpackage.jsonandpackage-lock.json. Forphp_prod, crittr must be independencies. -
Turn on the option and
itk_stylesheets()(see Critical CSS), then rundocker compose exec php bin/console cache:clearanddocker compose restart worker. -
Test one page:
docker compose exec php bin/console itk:critical-css:generate --page=<id> --now.
Production build
docker build -f docker/Dockerfile --target php_prod --build-arg CRITICAL_CSS=1 -t mysite:1.0 .
- The
php_prodstage installs dependencies without dev packages (composer install --no-dev, plusnpm ci --omit=devwithCRITICAL_CSS=1) and turns onphp.ini-production. - Pass
APP_SECRET,DATABASE_URLandMAILER_DSNthrough the container environment. The.envfrom git goes into the image, so keep only default values in it. - The image has no admin files (
public/bundles). The entrypoint puts them in place at start. Give nginx a shared volume, or runassets:install publicin your own build stage. - Migrations and
itk:installrun on eachphpstart. With several replicas, setAUTO_MIGRATE=0and run the migrations as a separate job. - The worker starts from the same image with
SKIP_ENTRYPOINT=1and the worker command. - The kit's
compose.yamlis meant for development. The site describes its production orchestration itself.
Updating the kit
The kit belongs to the site, and composer update does not change it. After a package update, compare the files and carry over the changes you need:
docker compose exec php composer update itk/cms diff -r -x compose.yaml vendor/itk/cms/docker docker && diff vendor/itk/cms/docker/compose.yaml compose.yaml docker compose up -d --build
AI agent in the site project
The rules for an AI agent that builds a site on ITK CMS ship in the package: SITE-AGENTS.md (in a site, vendor/itk/cms/SITE-AGENTS.md). The main rule: when the core lacks a feature that other sites would also use, the agent proposes it as a pull request to it-koval/cms instead of modifying a copy of the core inside the site.
Agents read instructions from the project root, so reference the file in the site's instructions:
- Claude Code, a line in
CLAUDE.md:@vendor/itk/cms/SITE-AGENTS.md. - Codex, Cursor and other agents that read
AGENTS.md, a line inAGENTS.md:Before you start, read vendor/itk/cms/SITE-AGENTS.md: these are the ITK CMS core rules, and they are mandatory.
Public API and compatibility
UPGRADE.md lists the public API and the upgrade rules between versions. Classes marked @internal in the docblock can change in any version, and PHPStan and IDEs warn when you use them. A site reads pages and collections through ContentReader and the Twig functions, not through repositories.
Developing and testing the bundle
The it-koval/cms monorepo holds the bundle (packages/cms) and the admin panel sources (admin/). CONTRIBUTING.md explains how to set up the environment, run the tests, build the admin panel and add an interface language.
Other documents
- CHANGELOG.md: changes by version.
- UPGRADE.md: upgrading between versions and the boundary of the public API.
- CONTRIBUTING.md: how to contribute.
- SECURITY.md: how to report a vulnerability.
- SITE-AGENTS.md: rules for an AI agent in the site project.
- admin/src/README.md: how the admin panel works and plugins.