Download the PHP package dvictorjhg/braidphp without Composer

BraidPHP

BraidPHP is an attribute-driven PHP framework with module composition, routing, PSR HTTP messages, and a lightweight single-process TCP HTTP runtime. Dependency injection and provider storage are delegated to the standalone dvictorjhg/php-injector package.

• Package requirement: PHP ^8.4
• Runtime model: one blocking process accepts, parses, routes, invokes, and writes each request in sequence
• Main source areas: src/Router
• Checked-in sample app: Example/

Why to use?

Choose BraidPHP for small HTTP APIs or services where you want explicit module boundaries, attribute-declared controllers, constructor injection, and a request lifecycle you can read end to end. It combines those pieces without requiring a full-stack application framework or a separate server for local execution.

Characteristics Comparison

Prefer Slim when standardized middleware is central to your application, or Flight when route/helper-oriented simplicity is a better fit. BraidPHP's native listener handles one request at a time; it is not an async server or worker pool. Providers are process-global rather than request-scoped. These are constraints, not features to hide behind throughput numbers.

Representative HTTP Benchmarks

Measured freshly on 2026-10-19 with PHP 8.5.11, k6 2.3.0, Composer 2.10.3, and an AMD RYZEN AI MAX+ 392. Tool and benchmark dependency versions were checked against upstream stable releases before running. Median requests/second across three five-second samples after warmup, at 16 concurrent users, with the server and load generator on separate cores. All frameworks use the same optimized no-dev autoloader; OPcache is on, JIT and Xdebug are off. These are synthetic routing/response workloads, not real-world application capacity estimates.

For the shared-server comparison, every framework runs behind the same single-process PHP server and registers its routes per request. JSON is encoded per request; the parameter route returns its captured ID; expected 404 responses are checked as successes. With 100 routes, 97 unused parameterized routes are registered before the three measured handlers. Optional route caches are off.

Native-runtime results are a separate comparison: BraidPHP's App::listen() bootstraps once per process and uses its own HTTP parser/emitter instead of the PHP server. Its results include that lifecycle advantage and different logging.

CPU And Memory

Server-process resources for the JSON workload at 16 users. CPU 100% means one core; CPU us/request is server CPU time divided by completed requests. CPU and mean RSS are medians across repeats; the sampled RSS peak is the maximum across repeats. These exclude the load generator and are not whole-host totals.

Lower resource cost is better for equivalent work and process history. CPU % alone is not a ranking: low utilization can also mean fewer requests are served.

RSS includes PHP, extensions, resident shared pages, and state retained from earlier workloads in the same process. It is not framework-only or private memory. The three-route run also executes one-user workloads before 16-user workloads; the 100-route run does not. Their RSS values are not an isolated route-count comparison. Sampling is approximately every 100ms and can miss brief peaks. Resource windows include k6 launch/exit but exclude server startup and warmup.

All 10,136,660 requests across 180 measured samples passed status, exact-body, and content-type checks; the three-route run also tested one concurrent user. Variability is material: three-route BraidPHP JSON ranged from 7,979 to 12,223 req/s on the shared server. p95 is the median of per-run HTTP percentiles and excludes connection setup. Connections are not reused, matching the native listener's behavior. Closed-loop load and short local samples do not prove production capacity, overload behavior, or universal framework superiority.

See the benchmark report for ranges, low-concurrency results, the plain-PHP control, and provenance, and the benchmark instructions to reproduce the measurements. Database work, injected service graphs, production FPM/worker deployments, private/heap memory, and keep-alive are not measured.

Documentation

• Full guide: GitHub Pages documentation
• Local static entry point: docs/index.html
• First application walkthrough: GitHub Pages first-app guide
• Modules and dependency injection: GitHub Pages modules guide
• Routing reference: GitHub Pages routing guide
• Executable recipes: JSON API and request handling
• HTTP messages and runtime: GitHub Pages HTTP guide, runtime guide, operations guide
• Development and release workflow: GitHub Pages development guide

Requirements

• PHP ^8.4
• Composer

Installation

Verified Quick Start

Create one module, one provider, one controller, then start the TCP server:

Then request the route:

For the full empty-directory walkthrough, including composer.json, src/, and index.php, see the GitHub Pages first-app guide.

What The Package Includes

• #[Module] application composition with imports, providers, controllers, and bootstrap
• Optional initial providers passed to new App([...]) before module bootstrap
• Attribute-driven routing with class prefixes and method-level HTTP route attributes
• Supported shortcut attributes: #[Get], #[Head], #[Post], #[Put], #[Delete], #[Connect], #[Options], #[Trace], #[Patch]
• Programmatic routes via dvictorjhg\braidphp\Router\Classes\Route
• Path parameter capture through Request::getRouteParam() and Request::getRouteParams()
• Query-string parsing through Request::getQueryParams()
• PSR HTTP message implementations for Request, Response, Uri, and Stream
• A minimal TCP listener through App::listen()

Runtime Caveats

• App::listen() is a blocking single-process server loop.
• The example front controller reads SERVER_ADDRESS and SERVER_PORT from the environment and defaults to 0.0.0.0:8000.
• There is no worker pool, middleware pipeline, or FastCGI/SAPI integration in this repository.
• Scale by running multiple processes behind a process manager, reverse proxy, or container platform.
• The active PHPInjector is process-global, not request scoped. Do not cache request-specific state in shared providers or bootstrap independent apps in one process and expect separate containers.
• handleRequest() propagates controller exceptions. Only listen() catches them, logs details server-side, and returns a generic 500 response. Malformed requests receive a generic 400 response.
• By default, requests have a five-second total read deadline, a 64 KiB header limit, and an 8 MiB body limit. Invalid or duplicate Content-Length, truncated bodies, and Transfer-Encoding are rejected. Chunked requests are not supported.
• Response writes retry partial writes and have a separate five-second default deadline. Failed writes are logged and the client is closed without stopping the listener.
• Arrays are not converted to JSON automatically. Return a Response with an explicit JSON content type and json_encode(..., JSON_THROW_ON_ERROR) body.

Configure HTTP Limits

Pass HttpOptions to the application; no vendor edits or global settings are needed. Existing new App() and Request::fromResource($stream) calls retain the defaults. Options are immutable and invalid values throw InvalidArgumentException at construction.

This complete example configures an application and uses the same options for direct parsing without opening a listening socket:

Expected output:

Bootstrap modules and call $app->listen(address: '127.0.0.1', port: '8000') in your application's front controller. RequestParser::fromResource() accepts the same optional options argument. HTTP options do not change provider scopes, route matching, or the single-process model. Configure PHP's error_log setting to choose where server-side errors are written.

Test Requests Without A Server

This complete example uses the checked-in application, so run it from a repository clone after composer install, not from a package-only installation:

Expected output:

See the complete JSON recipe for decoded path parameters, query validation, dependency injection, strict path matching, and exception handling.

Run The Example Application

From the repository root:

In a second terminal:

Development Commands

• CI runs the suite in .github/workflows/ci.yml on PHP 8.4 and 8.5.
• CI also verifies executable documentation on PHP 8.5.
• composer coverage:check enforces a minimum 80% statement coverage from the generated Clover XML.
• codecov.yml separately configures Codecov project and patch targets at 50%.
• php tools/check-docs.php requires PHP DOM and proc_open. It executes marked HTML examples and non-server README examples in separate PHP processes and compares their expected output. Xdebug is disabled only for these child runs.

Customize Development Tools

Composer forwards arguments after --. The coverage checker defaults to build/test-results/clover.xml and 80%; supply both the report and a finite percentage between 0 and 100 to override them:

Use your own configuration paths with the same tool flags. Coverage output paths can be selected with vendor/bin/phpunit --coverage-clover /tmp/clover.xml; pass that report to the checker. Enable Xdebug coverage mode or PCOV for coverage runs. The CI gate and Codecov targets are separate settings, not runtime limits.

Containers

The repository includes a PHP image definition in docker/php/php.Dockerfile, a compose file in docker-compose.yml, and helper launchers in bin/podman-run.sh and bin/podman-run.ps1.

Typical local Podman flow:

The default .env values expose SERVER_PORT=8000 and set the base PHP image tag to php-8.5.11-cli-trixie. The Podman launcher appends the environment name, so its default development image is localhost/dvictorjhg/braidphp:php-8.5.11-cli-trixie-development.

Changelog

See CHANGELOG.md.

Contributing

See CODE_OF_CONDUCT.md, and AI_USE_POLICY.md.

Security

See SECURITY.md. Report vulnerabilities privately instead of opening a public issue.

Release / Publishing

The next release is 1.1.0. Finalize its dated entry in CITATION.cff and the English and Spanish documentation version labels aligned, and run every development command above. Review composer audit and inspect a composer archive build for source, licensing files, and unwanted local artifacts before tagging.

Publish PHPInjector 1.0.3 first, then create and push the annotated BraidPHP tag 1.1.0, publish the GitHub Release, and refresh Packagist. Composer derives the package version from the Git tag; do not add a version field to composer.json. Configuration defaults remain compatible with unconfigured calls; malformed request framing is now rejected and listener error details are logged instead of exposed to clients.

License And Attribution

BraidPHP is released under the Apache License 2.0. Preserve the license text, repository copyright, and attribution notices. See CITATION.cff for attribution details.