Download the PHP package cloude/framework without Composer

Cloude Framework

A minimalist PHP micro-framework. No magic, no service container. Persistence is opt-in: file-based (JSON / Markdown) by default, with a thin Active Record over PDO via Cloude\Model when you need a relational database.

• PHP 8.3+ (tested on 8.3, 8.4 and 8.5)
• PSR-4 autoloading, namespace Cloude\
• PSR-12 / PER-CS 2.0 coding style
• declare(strict_types=1) everywhere
• Zero runtime dependencies. Markdown rendering is in-house. Slug transliteration uses ext-intl when present (Cyrillic, Greek and other scripts romanise correctly). Without ext-intl non-ASCII characters are dropped — install it for sites that need accent-aware slugs.

Built with Claude Code

Cloude is shaped while pair-coding with Claude Code — Anthropic's terminal-native AI coding agent. The "one file per class, no magic, no DSL, no annotations" rules aren't aesthetic preferences: they exist so the agent (and you) can reason about any piece of the framework without loading a runtime in your head.

Try it:

Then ask Claude Code to scaffold a front controller with Cloude\Bootstrap, expose an MCP server with Cloude\Mcp\Server, or migrate a routes file into nested groups. The surface area is small enough that the agent usually nails it in one prompt.

For agents: see AGENTS.md — a tight reference card with the decision matrix, idioms and anti-patterns. AI tools (Claude Code, Cursor, Codex, …) pick it up automatically when they see the file at the repo root.

For Claude Code users specifically: CLAUDE.md is the "from zero to running feature" playbook — quick start, project layout, the standard add-a-feature workflow, common patterns, and how to brief Claude effectively. Copy it into your own project root once you start building on top of cloude/framework.

For design-pattern guidance: PATTERNS.md is the decision guide for picking an architecture — Transaction Script, MVC

• Repository, or DDD layered. It maps "what your app looks like" to "which example to copy", with migration paths and anti-patterns.

For brand-new projects, AI-guided: SETUP.md is an interview script for AI coding agents. Point Claude Code (or any tool-capable agent) at this file and it walks you through eight steps — namespace, docroot, run mode (php -S / Docker / both), pattern, CSS, JS, optional modules — and scaffolds the project based on your answers.

Installation

Repository layout

Components

Core

Cloude\Http\…

Cloude\Data\…

Cloude\Model\… and Cloude\Storage\…

Cloude\Markdown\…

Cloude\Mcp\…

Cloude\Testing\… — built-in test framework (no PHPUnit dependency)

Quick start

A typical www/index.php looks like this:

Bootstrap::run wires up ob_start, the global 503 error handler, and the view base path in one call. Drop in app/config.php and you have a complete front controller in ~15 lines.

Example projects

Ready-to-run sample apps live in examples/. Each one is fully self-contained — no cross-dependencies, no Apache or nginx required, no composer install needed when running from inside this repo. From the repository root:

Run via Docker without installing PHP locally — see DEPLOYMENT.md.

Class reference

Cloude\Router

{name} segments are extracted into an associative array and passed as the first handler argument.

Pattern syntax:

Examples:

Route groups stack a URL prefix onto a block of routes. Nestable.

Cloude\Input

Cloude\View

View templates use the .html.php double extension by convention — visually separates HTML-producing templates from PHP source files (controllers, models) and improves IDE highlighting. The render() / capture() methods don't enforce it; any require-able path works.

Short names inside views

include-based templates run in their own scope, so View::e() etc. need the framework namespace. Two equally supported shapes — pick the one that fits the project:

Option A — standard use statement (per-view, explicit, IDE-friendly):

Option B — declarative aliases in app/config/app.php (one declaration, every view inherits):

Bootstrap::run() reads the aliases list and calls class_alias('Cloude\<short>', '<short>') for each entry. The framework skips silently when the short name is already taken (your own classes, PHP built-ins, prior aliases) so user code is never stomped. Default config registers no aliases — the feature is strictly opt-in.

Bundled examples (examples/basic/, examples/contacts/, examples/library/) use Option A so they're explicit about every import. Real apps with many views often prefer Option B to drop the use boilerplate.

Cloude\Markdown

Supports minimal YAML frontmatter (single-line key: value pairs):

The body is rendered with the in-house Cloude\Markdown\Parser. To swap in a different engine (e.g. Parsedown if you want its full feature set):

Cloude\Markdown\Parser

Minimalist Markdown → HTML parser. Covers the editorial subset:

app/config/ ├── app.php # base — always loaded ├── db.php ├── mail.php ├── dev/ # active when environment is 'dev' │ └── app.php # deep-merged onto the base └── prod/ ├── app.php └── db.php json {"error": "not_found", "status": 404} apacheconf RewriteRule ^[0-9]+/assets/(.*)$ /assets/$1 [L] bash php app/cli/tasks.php # list every task php app/cli/tasks.php help content:rebuild-index # describe one php app/cli/tasks.php content:rebuild-index --country=fr --dry-run php app/cli/tasks.php content:purge-old --days=30 bash composer install composer test # cloude-test (Cloude\Testing\Runner) composer cs-check # php-cs-fixer in dry-run mode composer cs-fix # apply fixes bash git tag -a v0.15.0 -m "v0.15.0" git push origin v0.15.0 bash composer require cloude/framework bash vendor/bin/cloude-test # run tests/ (default) vendor/bin/cloude-test tests/Storage # scope to a directory vendor/bin/cloude-test --filter=Cast # regex match on ClassName::method vendor/bin/cloude-test --help # usage summary

The runner discovers `*Test.php` files recursively, instantiates every
class extending `Cloude\Testing\TestCase`, and runs each public
method whose name starts with `test`. Dots / `F` / `E` printed
PHPUnit-style; final summary lists failures and errors with stack
traces. Exit code 0 on green, 1 on anything red.

**Why ship a custom runner?** The framework's philosophy is small,
hand-rolled, no dependencies the user didn't ask for. Dropping PHPUnit
(15+ MB in `vendor/`) keeps `composer install` lean for downstream
consumers; the runner itself is < 500 LOC across `Runner.php`,
`TestCase.php`, `Assert.php` and `bin/cloude-test`. PHPUnit's API
shape (method names, attributes, lifecycle) is mirrored so the muscle
memory transfers and existing tests migrate with two `use`
substitutions.

#### Writing a test

#### Assertions

PHPUnit-compatible names (`assertSame`, `assertTrue`, etc.) are
available both as `$this->...` and `self::...` (route to the same
implementation). The full list:

| Equality        | `assertSame`, `assertNotSame`, `assertEquals`, `assertEqualsWithDelta` |
| Booleans / null | `assertTrue`, `assertFalse`, `assertNull`, `assertNotNull` |
| Containers      | `assertCount`, `assertEmpty`, `assertNotEmpty`, `assertContains`, `assertArrayHasKey`, `assertArrayNotHasKey` |
| Type            | `assertInstanceOf`, `assertNotInstanceOf`, `assertIsString` |
| Strings         | `assertStringContainsString`, `assertStringNotContainsString`, `assertStringStartsWith`, `assertStringEndsWith`, `assertMatchesRegularExpression`, `assertJson` |
| Comparison      | `assertGreaterThan`, `assertLessThan`, `assertLessThanOrEqual` |
| Filesystem      | `assertFileExists`, `assertDirectoryExists` |
| Escape hatch    | `fail($message)` |

#### Cloude-specific helpers

| Helper                                     | Purpose                                                                                  |
|--------------------------------------------|------------------------------------------------------------------------------------------|
| `useArrayModel(class, rows = [])`          | Configure a `Model` subclass with `ArrayStorage` + seed rows for the duration of the test |
| `useSqliteModel(class, createSql)`         | Same, but with an in-memory SQLite + `PdoStorage`. Returns the PDO for extra setup        |
| `useMockModel(class, rows = [])`           | Like `useArrayModel()` but the storage records every call. Returns a `MockStorage` for assertions |
| `captureHttp($handler)`                    | Run a route handler; return `['status' => …, 'body' => …]`                               |
| `assertJsonResponse($expected, $handler)`  | Capture + decode + structural compare. Optional `status:` named arg                       |
| `assertHttpException($status, $handler)`   | Catch a `Cloude\Http\HttpException`; check status; return the exception for chaining     |
| `freezeTime($when)` / `unfreezeTime()`     | Pin `DateTime::now()` to a fixed instant for deterministic time-aware tests              |
| `assertModelReceived($store, $method, times: ?int)` | Assert that a `MockStorage` got `$method` (optionally exactly `$times` times)        |
| `assertModelDidNotReceive($store, $method)` | Inverse — assert `$method` was never called                                              |
| `assertModelHas($model, $attributes)`      | Assert each attribute key in `$attributes` matches on the model                          |

**Picking a model helper:**

| Need                                                          | Helper            |
|---------------------------------------------------------------|-------------------|
| State-based test ("after doing X, the row has these fields")  | `useArrayModel`   |
| Behaviour test ("X causes a delete on PK 42")                 | `useMockModel`    |
| Tests that go through `Model::query()` (joins, raw SQL builder) | `useSqliteModel`  |

`useMockModel` is the right choice when you want to assert _how_ the
code used the storage. Don't use it for code that calls
`Model::query()` — faking the SQL builder leads to tests that pass
even when the underlying SQL is wrong. SQLite in-memory (the
`useSqliteModel` path) is fast enough that real SQL is the better
default whenever the query shape matters.

State that bleeds across tests is automatically cleared in
`setUp()` / `tearDown()`:

- `Cloude\Config::reset()` — forgets all loaded config files
- `Cloude\DateTime::clearTestNow()` — releases any frozen `now()`

## Philosophy

- **No magic**: the code you read is the code that runs. No generators, annotations or proxies.
- **Small classes**: each class fits in a file you can read in one sitting — and so can [Claude Code](https://claude.com/claude-code).
- **No required dependencies**: the core pulls nothing in. `ext-intl` is recommended for slug transliteration but not required.
- **No global state**: no container, no singletons. Static classes are just namespaces for functions.
- **AI-readable by design**: explicit APIs, no DSL, no inheritance webs. The framework is small on purpose so an agent can edit any piece without missing context.

## License

MIT - see [LICENSE](LICENSE).