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 run() 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);

$app->run();

See application setup for environment loading, console commands, panel installation, plugins, and users; content models covers nodes, routes, queries, and rendering.

Requirements

• PHP ^8.5 and Composer 2. Required extensions are declared in composer.json; run composer check-platform-reqs after installation.
• PostgreSQL with btree_gist, btree_gin, and unaccent. CI uses PostgreSQL 17. The migration role needs permission to create the required extensions, or an administrator must provision them.
• 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.

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.

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, Svelte 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.