cosray / cms
Cosray content management system and framework
Requires
- php: ^8.5
- ext-curl: *
- ext-dom: *
- ext-gd: *
- ext-intl: *
- ext-pgsql: *
- ext-sodium: *
- ext-xml: *
- celemas/boiler: ^0.4.0
- celemas/core: ^0.4.0
- celemas/quma: ^0.2.0
- celemas/session: ^0.2.0
- celemas/sire: ^0.4.0
- gumlet/php-image-resize: 2.0.*
- hidehalo/nanoid-php: ^2
- psr/log: ^3.0
- vlucas/phpdotenv: ^5.6
Requires (Dev)
- celemas/dev: ^4.2
- filp/whoops: ^2.15
- laminas/laminas-diactoros: ^3
Suggests
- filp/whoops: Enables pretty debug error pages in debug mode.
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 18:22:21 UTC
README
Cosray is a PHP content management framework with code-first content models, PostgreSQL-backed storage, and an admin panel for editors.
[!WARNING] Cosray has not had its first public release. Its API, data model, and panel design are still changing. These documents explain the current implementation, not a stability promise or a fixed product roadmap.
Starting an application
Cosray\App creates the configuration and CMS bootstrap, installs the default error handler, and registers the CMS catchall route when serve() is called. Application-defined node and collection classes are registered before that call:
use Cosray\App; use Cosray\Locales; $app = App::create(dirname(__DIR__), [ 'app.name' => 'mycms', ]); $locales = new Locales(); $locales->add('en', title: 'English', pgDict: 'english'); $app->load($locales); $app->section('Content')->collection(\App\Cms\Collection\Pages::class); $app->node(\App\Cms\Node\HomePage::class); return $app->serve();
serve() handles the current request, or many requests as a FrankenPHP worker. See application setup for environment loading, serving requests and worker mode, console commands, panel installation, plugins, and users; content models covers nodes, routes, queries, and rendering.
Requirements
- PHP
^8.5and Composer 2. Required extensions are declared in composer.json; runcomposer check-platform-reqsafter installation. - PostgreSQL 17 or newer with the contrib extensions
btree_gist,btree_gin,unaccent, andpg_trgm. Structured field sorting uses PostgreSQL 17's SQL/JSON scalar extraction. CI uses PostgreSQL 17. - A web server routing requests to the public PHP entrypoint while serving existing public files directly.
- Node.js and pnpm for building the panel, with versions declared in panel/package.json. The transitional legacy richtext migration also needs Node.js, but ordinary CMS requests do not.
Database setup
Create a login role and an empty database it owns, as a role with CREATEROLE and CREATEDB:
CREATE ROLE example LOGIN PASSWORD 'example'; CREATE DATABASE example OWNER example;
Or with the PostgreSQL command-line tools:
createuser --login --pwprompt example createdb --owner=example example
Point DATABASE_URL at it, such as pgsql:host=localhost;dbname=example;user=example;password=example, then install Cosray's schema and apply all updates, including the site's own migrations:
php run db:migrations --namespace=install --apply php run db:migrations --apply
The install namespace creates the extensions, the cms schema, the tables, and the migrations table, and records the updates it already includes. Afterwards, deployments run only the second command.
The role needs no superuser rights: PostgreSQL marks the required extensions as trusted, so the owner of a database may create them in it, provided the server has the contrib extensions installed. Where the role does not own the database, or a hosting provider restricts extensions, an administrator creates them beforehand, and the install uses them as they are.
A site that needs an extension that is not trusted, such as PostGIS, has a superuser create it before running the migrations. As the role then does not own the extension, leave it out of dumps the role restores, as in pg_dump --exclude-extension=postgis (PostgreSQL 17 or newer).
Documentation
Read the topic relevant to the task rather than loading every reference. When documentation and implementation disagree, inspect the source and tests before relying on the documented behavior. A current limitation is not a prohibition on exploring a different design.
These links describe a source checkout. Distribution archives omit development documentation and tests; for an installed package, consult the repository at the source reference recorded in its Composer lock file, not necessarily the latest branch.
| Topic | Reference |
|---|---|
| Configuration, console, plugins, users, panel integration | Application setup |
| Nodes, embedded fields, routes, queries, menus, working copies | Content models |
| Assets, image sizes, imports, reference indexes | Media |
| Field descriptors, form transport, custom elements | Editor controls |
| Block types, translation, storage, frontend rendering | Blocks |
| Richtext storage and validation | Richtext format |
| Search selection, queries, safe snippets, deployment | Full-text search |
| Headless delivery and integrations over JSON | API |
| Background jobs, retries, cron | Job queue |
| Mail transports, templates, delivery | |
| Refusing writes during updates | Maintenance mode |
| Site tests with PHPUnit | Testing |
| CSS conventions and the live styleguide | Panel styles |
| Components and controller methods for plugin pages | Panel kit |
| Current shortcuts and keyboard considerations | Panel keyboard |
| PHP tests and isolated database setup | Testing |
| Panel development and tests | Panel |
| Shared PHP/TypeScript behavior fixtures | Contract fixtures |
There is no rolling changelog before the first public release. Git history and tags retain development history; migration requirements belong with the affected feature.
Source map
- src/App.php, src/Bootstrap.php: application integration.
- src/Config/Defaults.php, src/Config.php: settings and typed access.
- src/Node/, src/Field/, src/Value/: schema, persistence, and template-facing values.
- src/Routes.php, src/Controller/: HTTP endpoints and access checks.
- panel/views/, panel/src/, panel/styles/: Boiler SSR views, htmx behaviors, custom elements, and CSS.
- db/migrations/, db/sql/: schema evolution and named queries.
- tests/, panel/tests/: executable examples and regression coverage.
License
Cosray is licensed under MIT. Bundled third-party files retain their respective licenses; see REUSE.toml.