Vladyslav

Posted on Jun 1

Designing a deterministic PHP 8.4+ framework before the first stable release

#php #architecture #opensource #showdev

This is my first post on DEV, so I want to keep it honest and technical rather than promotional.

I am building Coretsia in the open, and at this stage I am mostly interested in review: unclear documentation, mismatches between code and docs, weak architectural explanations, and places where the project is harder to understand than it should be.

The reason I care about this is simple: most framework problems do not appear on day one. They appear later, when conventions start drifting, documentation stops matching the code, generated files become noisy, and nobody is fully sure which rule is actually canonical.

Why build another PHP framework?

Not because PHP lacks frameworks.

PHP already has mature, battle-tested frameworks and ecosystems. Laravel, Symfony, Yii, Spiral, Mezzio, CodeIgniter, and many internal company frameworks already cover a wide range of use cases. So Coretsia is not being built from the idea that the PHP ecosystem is empty.

The experiment behind Coretsia is different:

Can a PHP framework be designed around deterministic tooling, strict boundaries, and source-of-truth-driven architecture from the beginning?

That question is what I am trying to explore. This does not mean that existing frameworks do not care about architecture, tooling, or boundaries. Many of them do. The question is narrower: what happens if those constraints are treated as the starting point of the framework rather than something added later by teams, conventions, or internal platform layers?

Where Coretsia is actually different

The difference is not that Coretsia wants to have routing, dependency injection, middleware, console commands, configuration, or packages. Those are expected parts of a modern PHP framework.

The difference is in what the framework treats as foundation-level concerns.

Coretsia starts from constraints that are often added later in projects, especially after an application has already grown:

deterministic tooling;
repository and package boundary laws;
source-of-truth documents for framework invariants;
generated artifacts that should not drift randomly;
explicit separation between runtime code, tooling, and experiments;
progressive framework modes instead of one fixed application shape.

In many projects, these concerns appear later as internal platform rules, team conventions, CI scripts, architecture documents, or custom tooling. Coretsia tries to make them part of the framework model from the beginning. That does not make Coretsia more mature than existing frameworks.

It makes the experiment different.

Coretsia is still early. It is not production-stable. It is not something I am presenting as a replacement for existing frameworks today.

I am sharing it now because this is the phase where feedback is most valuable: before the first stable release, before the public API is locked, and before the documentation structure becomes too hard to change.

What Coretsia is trying to be

Coretsia is an early-stage PHP 8.4+ framework project. Its source currently lives in a monorepo because package boundaries, tooling, documentation, generated artifacts, and release rules are part of the design.

The main ideas are:

deterministic tooling;
strict package and architectural boundaries;
explicit contracts;
source-of-truth-driven documentation;
reproducible generated artifacts;
progressive application modes instead of one fixed application shape.

The goal is not just to assemble another routing layer, container, middleware stack, or CLI around familiar PHP application patterns. The goal is to build a framework where the structure of the project is not accidental.

In many long-lived PHP applications, the problem is not that the first version was hard to build. The problem is that the system grows, and after some time nobody is fully sure where the real rule lives.

Is it in code? In documentation? In a config file? In a generated artifact? In a convention that exists only in someone’s head?

Coretsia tries to make those boundaries explicit.

Deterministic tooling as a framework constraint

One of the core ideas behind Coretsia is determinism. For this project, determinism does not mean “everything in runtime is magically predictable”. It means that framework tooling should avoid hidden, unstable, or environment-dependent behavior where possible.

Generated files should not randomly change between runs. Ordering should be stable, configuration shapes should be explicit, tooling should be able to detect drift, and architecture checks should be repeatable.

A simple example: if a tool generates an artifact from package metadata, the result should not change just because the filesystem returns files in a different order, or because the same input was processed on another machine. If the input did not change, the generated output should not create noise in Git.

This matters because a framework is not only runtime code. It is also everything around the runtime:

package layout;
code generation;
config merging;
dependency boundaries;
documentation rules;
release rails;
CI checks;
local development commands.

If those things are unstable, the framework may still work, but the development experience slowly becomes harder to trust.

Coretsia treats tooling and architecture rules as part of the framework, not as an afterthought.

Strict boundaries

Another important part of the experiment is package boundaries. Coretsia is organized as a monorepo, but the monorepo is not meant to become an unstructured folder of packages.

Packages are expected to have clear ownership and clear rules. The project uses layered package paths and Composer package names. It also has rules for what tooling code may or may not import.

For example, development spikes and prototypes are intentionally separated from runtime packages. The goal is to make experimental tooling useful without allowing it to leak into the production runtime model.

That boundary is important to me. I want prototypes to exist. I want experiments to be possible. But I do not want temporary implementation experiments to silently become framework architecture.

Source of Truth documents

Coretsia also uses SSoT documents — Single Source of Truth documents — for important framework invariants. This may sound formal, but the motivation is practical.

In Coretsia, these are not meant to be decorative documents. For example, packaging rules can define how a package path maps to a package id, Composer name, namespace, publishable unit, and release line. A dependency table can define allowed compile-time edges in a parse-friendly format, so tooling can check that the repository still follows the documented rule.

In framework development, some rules should not be scattered across README files, tests, comments, and implementation details.

For example:

config root ownership;
artifact shapes;
middleware taxonomy;
observability label rules;
module manifest rules;
package structure rules;
runtime boundaries.

When these rules are important enough, they should have a canonical place. The code should follow them, the documentation should link to them, and tests or tooling should enforce them where possible.

That is the direction Coretsia is moving toward.

Progressive application modes

Another idea in Coretsia is that an application should not need to start with the full enterprise shape from day one.

The roadmap is structured around progressive modes:

Micro;
Express;
Hybrid;
Enterprise.

The intent is not to create marketing names for the same thing. The intent is to describe different levels of framework capability and application structure.

For example, a Micro-style application should be able to stay small and direct. An Express-style application may need more framework conveniences. A Hybrid application may need clearer boundaries between application areas. An Enterprise-style application may need stronger module contracts, observability rules, package discipline, and long-term governance.

Those definitions are still being refined, but the direction matters: a small service should not be forced to look like a large enterprise system. At the same time, a growing system should not require a full rewrite just because the original structure was too minimal.

That is the long-term idea behind the phrase:

Start minimal. Scale to enterprise. Never rewrite.

This is still a design goal, not a completed promise. The current public work is focused on the foundation needed to make that direction possible.

Current status

Coretsia is currently in active development. The project already has a public monorepo, roadmap, documentation, contribution files, early package structure, deterministic tooling work, CLI tooling, package compliance rails, and early framework contracts.

There is no stable production release yet, so the project should be judged as an early framework foundation, not as a finished Laravel/Symfony alternative. That part is important because I do not want to present the project as more mature than it is.

Right now, Coretsia is best understood as an open framework design and implementation process. Some parts are implemented, some parts are locked as project rules, some parts are still planned, and some parts still need serious review.

That is exactly why I am sharing it now.

What kind of feedback I am looking for

I am not looking for implementation help in this post. At this stage, I am mostly looking for review.

The most useful feedback would be critical and specific.

For example:

places where the documentation and code do not match;
unclear concepts or confusing naming;
roadmap parts that look overdesigned;
package boundaries that do not make sense;
architecture rules that are hard to understand;
missing explanations for first-time readers;
places where the README assumes too much context;
problems in the local setup flow;
weak spots in the contribution model;
parts of the framework idea that are not convincing yet.

I am especially interested in feedback from people who have maintained long-lived PHP systems, not only built greenfield applications. I am interested in the kind of feedback that comes from maintaining code after the first version is already shipped.

What I am not looking for

I am not looking for “please add this feature” requests yet. I am not asking for production adoption.

I am not trying to start a framework war. I am not presenting Coretsia as “better than Laravel” or “better than Symfony”.

That is not the point.

The point is to explore a different framework design constraint:

What if deterministic tooling, explicit boundaries, and source-of-truth architecture were part of the framework from the beginning?

That is the experiment.

Website and visual direction

Coretsia already has a small public website. At the moment, it is intentionally minimal: a landing page and a privacy/cookie page. It exists so the project has a public surface, basic positioning, links to the monorepo, roadmap, documentation, and a way for people to contact the project.

But I do not consider the current website to be the final form of Coretsia’s public identity. It was built early, before the framework story, documentation structure, and visual direction were fully clear. That was useful, because it gave the project a real website instead of waiting for the “perfect” version.

The next version of the website should become a better explanation layer for the framework. It should help a first-time visitor understand what Coretsia is, what is implemented, what is still planned, why the project exists, and where to start reading.

I am also interested in ideas for the future website: homepage structure, documentation navigation, visual direction, roadmap presentation, and ways to explain Micro / Express / Hybrid / Enterprise modes without making the project look like a generic SaaS landing page.

Why share this now?

Because early-stage architecture is easiest to improve before it becomes stable. Once a project has a stable release, public API, documentation structure, package layout, and community expectations, every change becomes more expensive.

Right now, Coretsia is still in the phase where review can actually change the direction. That is why I would rather ask for criticism now than polish the surface too early.

A good review at this stage is more valuable than a star.

A found mismatch between code and documentation is more valuable than a generic compliment. A clear objection to an architectural decision is more useful than vague encouragement.

Links

GitHub organization: https://github.com/coretsia
Framework monorepo: https://github.com/coretsia/monorepo
Website repository: https://github.com/coretsia/website
Website Design RFC: https://github.com/coretsia/monorepo/discussions/categories/design-rfc

If you have experience with PHP frameworks, long-lived PHP applications, internal platforms, package architecture, documentation, or developer tooling, I would appreciate a critical look.

If you notice something specific, a comment is useful. If the feedback is about the broader direction, the Design RFC discussion is the best place for it. If it is a concrete mismatch in the repository, opening an issue would also be useful.

Not because Coretsia is finished.

Because it is not finished yet.