From 3140936220f927b95b1a2a1a33231ab8d5271d75 Mon Sep 17 00:00:00 2001 From: Artur Kyryliuk Date: Wed, 25 Feb 2026 17:51:29 +0100 Subject: [PATCH] [REF] Add project description files for agents and bots. --- AGENTS.md | 222 +++++++++++++++++++++++++++++++++++++++++++++++++ publiccode.yml | 134 +++++++++++++++++++++++++++++ 2 files changed, 356 insertions(+) create mode 100644 AGENTS.md create mode 100644 publiccode.yml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..2a5b8dba01 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,222 @@ +# Evolution CMS — Agent Guide + +Evolution CMS is a community-maintained fork of MODX Evolution, rebuilt on Laravel 12 components. +It is a PHP CMS and application framework with a tree-based document/resource model, +a template variable (TV) system, plugins, snippets, chunks, and a modular extras ecosystem. + +**PHP requirement:** >= 8.3 (8.4 recommended) · **License:** GPL-3.0-or-later + +--- + +## Repository Layout + +``` +/ ← web root (Apache/Nginx document root) +├── index.php ← front-end entry point +├── manager/ ← admin panel entry point (manager/index.php) +├── assets/ ← public uploads, cache, plugins, snippets, templates +│ ├── cache/ ← compiled template/TV cache (git-ignored) +│ ├── files/ ← user-uploaded files +│ ├── images/ ← user-uploaded images +│ ├── plugins/ ← installed plugin JS/CSS assets +│ └── templates/ ← front-end HTML templates +├── themes/ ← manager UI themes (default: demo) +├── views/ ← Blade layouts for the manager UI +├── core/ ← CMS core (NOT web-accessible; block in nginx/Apache) +│ ├── artisan ← CLI entry point: php core/artisan +│ ├── bootstrap.php ← application bootstrap +│ ├── composer.json ← core dependencies (Laravel 12, Pest, etc.) +│ ├── config/ ← Laravel-style config files +│ ├── custom/ ← LOCAL OVERRIDES — copy examples here, never edit originals +│ │ ├── composer.json.example → custom/composer.json (add extra packages) +│ │ ├── define.php.example → custom/define.php (constants override) +│ │ ├── routes.php.example → custom/routes.php (add Laravel routes) +│ │ └── config/ → override any core config key per-subdirectory +│ ├── database/ +│ │ ├── migrations/ ← Eloquent migrations (single consolidated migration) +│ │ └── seeders/ +│ ├── functions/ ← autoloaded global helpers (helper.php, nodes.php, etc.) +│ ├── lang/ ← locale files (en, ru, de, fr, …) +│ ├── modifiers/ ← output modifier include files (mdf_*.inc.php) +│ ├── src/ ← PSR-4 namespace EvolutionCMS\ +│ │ ├── Console/ ← Artisan commands +│ │ ├── Controllers/ ← manager action controllers +│ │ ├── Extensions/ ← Router, Collection extensions +│ │ ├── Facades/ +│ │ ├── Legacy/ ← legacy shim classes (Cache, ManagerApi, Modifiers…) +│ │ ├── Middleware/ +│ │ ├── Models/ ← Eloquent models (SiteContent, SiteTemplate, SitePlugin…) +│ │ ├── Providers/ ← ~30 Laravel service providers +│ │ ├── Services/ ← thin service layer (AuthServices, ConfigService…) +│ │ └── Support/ +│ ├── storage/ ← Laravel storage (logs, cache, compiled views) +│ └── tests/ ← Pest test suite +│ ├── Feature/ ← feature/integration tests +│ └── Unit/ ← unit tests (Console/, CoreTest.php) +├── composer.json ← root composer (thin; delegates to core/) +├── phpstan.neon ← static analysis config (level 0, excludes Legacy/) +└── publiccode.yml ← structured information about version and project +``` + +--- + +## Commit Message Convention + +All commits in this project use a bracketed prefix: + +``` +[ADD] New feature or file +[FIX] Bug fix +[REF] Refactor / code quality improvement +[UPD] Dependency or content update +[DEL] Removal of code or files +``` + +Examples from the log: +- `[FIX] Fix confusing dropdown showing rich text editor when editor is disabled` +- `[REF] Deprecation warnings for store installer.` +- `[ADD] Add command to list the code marked as deprecated` + +Always use one of these prefixes. Write short, imperative present-tense descriptions. + +--- + +## Branching + +- **`3.5.x`** — main stable branch; open PRs against this branch +- Feature/fix branches are named descriptively: `fix-rich-text-selection-when-editor-disabled` +- Do not push directly to `3.5.x`; always open a PR + +--- + +## Running the Test Suite + +Tests use [Pest](https://pestphp.com/) and live in `core/tests/`. + +```bash +# From the core/ directory: +composer test + +# Or directly: +cd core && vendor/bin/pest +``` + +PHPUnit sources cover: `factory/`, `functions/`, `includes/`, `modifiers/`, `src/`. + +The SQLite test database is `core/database/evo-test.sqlite`. + +--- + +## Static Analysis + +```bash +# From the repository root: +composer analyze +# Equivalent: php -d xdebug.mode=off vendor/bin/phpstan --memory-limit=512M + +# Scope: core/src/ (Legacy/ is excluded) +# Level: 0 (introductory — PRs should not increase error count) +``` + +--- + +## Artisan CLI + +The CMS uses a subset of Laravel's Artisan. The entry point is `core/artisan`. + +```bash +php core/artisan list # list all commands +php core/artisan cache:clear-full # clear all caches +php core/artisan site:update # run pending migrations / updates +php core/artisan package:extras # manage extras/packages +php core/artisan deprecated:list # list deprecated code by semver +php core/artisan translations:sync # sync translation files +php core/artisan doc:list # list content documents +php core/artisan route:list # list registered routes +php core/artisan tpl:list # list registered templates +php core/artisan tv:list # list registered TVs +``` + +--- + +## Customisation Points (core/custom/) + +`core/custom/` is the sanctioned location for all site-specific overrides. Core files must **never** be edited directly. + +| File to create | Copy from | Purpose | +|---|---|---| +| `core/custom/define.php` | `define.php.example` | Override CMS constants (paths, session config, etc.) | +| `core/custom/routes.php` | `routes.php.example` | Register Laravel routes; use `Route::fallbackToParser()` to preserve CMS routing | +| `core/custom/composer.json` | `composer.json.example` | Add extra Composer packages (namespace: `EvolutionCMS\Custom\`) | +| `core/custom/config/cms/settings.php` | `config/cms/settings.php.example` | Override CMS settings | +| `core/custom/config/app/providers.php` | — | Register additional service providers | +| `core/custom/config/database/connections/` | — | Add database connections | + +The merge-plugin in `core/composer.json` automatically includes `core/custom/composer.json`. + +--- + +## Key Namespaces and Extension Points + +| Namespace | Location | Purpose | +|---|---|---| +| `EvolutionCMS\` | `core/src/` | Core CMS classes | +| `EvolutionCMS\Custom\` | `core/custom/src/` | Project-specific extensions | +| `EvolutionCMS\Models\` | `core/src/Models/` | Eloquent models | +| `Database\Seeders\` | `core/database/seeders/` | Database seeders | +| `Tests\` | `core/tests/` | Test classes | + +### Important Models + +- `SiteContent` — resources/documents (the page tree) +- `SiteTemplate` — templates +- `SitePlugin` — plugins (event-driven PHP) +- `SiteSnippet` — snippets (callable PHP fragments) +- `SiteHtmlsnippet` — chunks (reusable HTML) +- `SiteTmplvar` / `SiteTmplvarContentvalues` — template variables (TVs) +- `User` / `UserAttribute` — manager users +- `Category` — categorisation for all element types + +### Service Providers + +There are ~30 service providers in `core/src/Providers/`. Notable ones: + +- `RoutingServiceProvider` — registers the CMS front-end parser as a route fallback +- `TemplateProcessorServiceProvider` — registers the template tag parser +- `ManagerThemeServiceProvider` — manager UI +- `TracyServiceProvider` — Tracy debug bar integration +- `ModifiersServiceProvider` — output modifiers + +--- + +## CMS Concepts for Agents + +- **Resources/Documents** — tree-based pages; each has a template, TVs, and content +- **Chunks** — reusable HTML fragments called with `{{ChunkName}}` +- **Snippets** — PHP code blocks called with `[[SnippetName? ¶m=`value-one`; ¶m2=`value-two`]]` +- **Plugins** — PHP code triggered by system events (OnPageNotFound, OnLoadWebDocument, etc.) +- **Template Variables (TVs)** — custom fields attached to templates `[*tvName*]` +- **Output Modifiers** — pipe-chained filters on tag output: `[*field*:modifier]` +- **Templates** — whole page HTML with chunks, snippets, TVs +--- + +## Dependencies of Note + +- **Laravel 12** components (illuminate/*) — container, ORM, routing, events, cache, queue +- **Pest 4** — test framework +- **Tracy 2** — debug/profiling bar +- **doctrine/dbal 4** — schema inspection for migrations +- **evolutioncms-services/document-manager** and **user-manager** — official service packages +- **phpmailer/phpmailer 7** — mail sending +- **guzzlehttp/guzzle 7** — HTTP client + +--- + +## What to Avoid + +- **Do not edit files in `core/src/Legacy/`** unless fixing a specific legacy bug. This code is excluded from static analysis and is being gradually deprecated. +- **Do not commit to `3.5.x` directly.** Open a PR. +- **Do not modify `core/config/`** for site-specific settings — use `core/custom/config/` instead. +- **Do not add files to `assets/cache/`** — it is auto-generated and git-ignored. +- **Do not use `$modx`** — it is deprecated. Use `EvolutionCMS()` or the `evo()` helper. +- **PHPStan error count must not increase.** Run `composer analyze` before submitting a PR. \ No newline at end of file diff --git a/publiccode.yml b/publiccode.yml new file mode 100644 index 0000000000..bfc35c999f --- /dev/null +++ b/publiccode.yml @@ -0,0 +1,134 @@ +publiccodeYmlVersion: "0.5.0" + +name: Evolution CMS + +url: "https://github.com/evolution-cms/evolution" +landingURL: "https://evo.im/" + +platforms: + - web + +categories: + - content-management + - website-builder + +developmentStatus: stable +softwareType: standalone/web + +softwareVersion: "3.5.4" +releaseDate: "2026-02-20" + +isBasedOn: + - "https://github.com/modxcms/evolution" + +organisation: + name: "Evolution CMS Community" + uri: "https://evo.im/" + +intendedAudience: + scope: + - culture + - education + - environment + - government + - local-authorities + - society + - sport + - tourism + - transportation + - welfare + +description: + en: + shortDescription: "Open-source PHP content management system and web application framework." + longDescription: | + Evolution CMS is an open-source content management system and web application framework written in PHP. + + The project originates from MODX Evolution (2004) and has been continuously developed by an international community. + The 3.5 series is based on Laravel 12 and PHP 8.3+. + + The system provides flexible content modeling, granular permissions, and multi-site architecture. + It supports multilingual websites and is suitable for public sector portals, intranets, and institutional websites. + + Evolution CMS is distributed under the GPL-3.0-or-later license. + + features: + - "Flexible content modeling" + - "Granular permission system" + - "Multi-site architecture" + - "Multi-language support" + - "SEO-friendly URLs" + - "Extensible via plugins and extensions" + - "Docker deployment support" + + uk: + shortDescription: "Open-source система керування контентом на PHP." + longDescription: | + Evolution CMS — це система керування контентом з відкритим кодом, написана на PHP. + + Проєкт розвивається міжнародною спільнотою та базується на Laravel 12 і PHP 8.3+. + +legal: + license: "GPL-3.0-or-later" + mainCopyrightOwner: "Evolution CMS Community" + +maintenance: + type: community + contacts: + - name: "Dmytro Lukianenko" + affiliation: "Maintainer" + email: "dmi3yy@gmail.com" + - name: "Serhii Korneliuk" + affiliation: "Maintainer" + email: "info@seigerit.com" + - name: "Artur Kyryliuk" + affiliation: "Core Team" + email: "mail@artur.work" + +localisation: + localisationReady: true + availableLanguages: + - uk + - en + - az + - be + - bg + - cs + - da + - de + - es + - fa + - fi + - fr + - he + - it + - ja + - nl + - nn + - pl + - pt + - sv + - zh + +dependsOn: + open: + - name: "PHP" + versionMin: "8.3" + optional: false + - name: "Laravel" + versionMin: "12.0" + optional: true + - name: "MySQL" + versionMin: "8.0" + optional: true + - name: "MariaDB" + versionMin: "10.6" + optional: true + - name: "PostgreSQL" + versionMin: "12.0" + optional: true + - name: "SQLite" + versionMin: "3.35.0" + optional: true + +roadmap: "https://github.com/evolution-cms/evolution/issues"