README

Source: semitexa/ultimate scaffold. This file is bundled with the Semitexa Ultimate package and is copied into new projects by bin/semitexa init. In the semitexa.dev monorepo edit the root copy and run bin/semitexa scaffold:sync-docs to propagate; in a consumer project, bin/semitexa init --only-docs refreshes the file and local edits will be overwritten.

"Make it work, make it right, make it fast." — Kent Beck

Semitexa isn't just a framework; it's a philosophy of efficiency. Engineered for the high-performance Swoole ecosystem and built with an AI-first mindset, it allows you to stop fighting the infrastructure and start building the future.

Simple by design. Powerful by nature.

Requirements

Docker and Docker Compose
Composer (on host for install)

Install

From an empty folder (get the framework and install dependencies):

composer require semitexa/ultimate

From a clone or existing project (dependencies already in composer.json):

composer install

Then:

cp .env.default .env

Run (Docker — supported way)

bin/semitexa server:start

To stop:

bin/semitexa server:stop

Default URL: http://0.0.0.0:9502 (configurable via .env SWOOLE_PORT).

Documentation

Official framework documentation lives in packages/semitexa-docs/. Package-level deep reference lives in vendor/ (or packages/ in the monorepo).

Topic	File or folder
AI context for this project	AI_CONTEXT.md
Framework docs hub	packages/semitexa-docs/docs/README.md
Workspace / monorepo docs — architecture, DI, PHPStan, testing, policy	packages/semitexa-docs/docs/workspace/README.md
Running the app — Docker, ports, logs	vendor/semitexa/core/docs/RUNNING.md
Adding pages and routes — modules, Request/Handler	vendor/semitexa/core/docs/ADDING_ROUTES.md
Attributes — AsPayload, AsPayloadHandler, AsResource, etc.	vendor/semitexa/core/docs/attributes/README.md
Service contracts — contracts:list, active implementation	vendor/semitexa/core/docs/SERVICE_CONTRACTS.md

The repository does not treat a root-level ./docs/ directory as canonical. Project-level AI guidance lives at root (AGENTS.md, AI_ENTRY.md, AI_CONTEXT.md, AI_NOTES.md); framework guidance lives in packages/semitexa-docs/; per-package reference lives in packages/<package>/docs/.

Structure

src/modules/ – your application modules (add new pages and endpoints here). New routes only in modules.
packages/semitexa-docs/ – official Semitexa framework and workspace documentation.
packages/<package>/docs/ – per-package canonical reference.
var/docs/ – working directory for notes, drafts, research, and remediation reports; not canonical.
AI_ENTRY.md, AI_CONTEXT.md, AGENTS.md – AI entrypoints and rules at project root; AI_NOTES.md is your notes (never overwritten).

Tests

Semitexa is Docker-based. Tests must run inside the project's test container. The only supported command is:

bin/semitexa test:run

This wraps PHPUnit with the correct container, environment, and test-path discovery. Pass PHPUnit arguments positionally:

bin/semitexa test:run --filter MyTest
bin/semitexa test:run packages/semitexa-core/tests/Integration

Running vendor/bin/phpunit directly on the host is not supported — the environment, service dependencies, and path resolution only match when tests run through bin/semitexa test:run.

Configuration lives in phpunit.xml.dist; tests live in packages/<package>/tests/ (auto-discovered). Local module tests live next to the module they cover at src/modules/<Module>/tests/. There is no root-level tests/ directory and no shared catch-all test bucket.

semitexa / ultimate

Maintainers

Package info

Statistics

Security