dvictorjhg / braidphp

1.0.2 2026-08-31 11:43 UTC

Requires

• php: ^8.4
• dvictorjhg/php-injector: ^1.0.1
• psr/http-message: ^2.0

Requires (Dev)

• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^3.0
• zalas/phpunit-globals: ^3.0

Provides

• psr/http-message-implementation: 2.0

Apache-2.0

• Víctor José Holgado Gallegos

• dvictorjhg
• braidphp

Published on Packagist.org on 2026-08-31 11:46 UTC

README

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/Core and src/Router
• Checked-in sample app: Example/

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
• 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

composer require dvictorjhg/braidphp

Verified Quick Start

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

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use dvictorjhg\braidphp\Core\App;
use dvictorjhg\braidphp\Core\Attributes\Module;
use dvictorjhg\braidphp\Router\Attributes\Get;
use dvictorjhg\braidphp\Router\Attributes\Route;
use dvictorjhg\braidphp\Router\Http\Request;
use dvictorjhg\braidphp\Router\HttpModule;

final class Greeter
{
    public function greeting(string $name): string
    {
        return "Hello $name!";
    }
}

#[Route(path: '/api')]
final class GreetingController
{
    public function __construct(private Greeter $greeter)
    {
    }

    #[Get('/hello/:name', pathMatch: 'full')]
    public function hello(Request $request): string
    {
        return $this->greeter->greeting($request->getRouteParam('name') ?? '');
    }
}

#[Module(
    imports: [HttpModule::class],
    providers: [Greeter::class],
    controllers: [GreetingController::class],
)]
final class AppModule
{
}

$app = new App();
$app->bootstrapModule(new AppModule());
$app->listen(address: '0.0.0.0', port: '8000');

Then request the route:

GET http://127.0.0.1:8000/api/hello/Ada
Hello Ada!

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.

Run The Example Application

From the repository root:

composer install
php Example/index.php

In a second terminal:

curl http://127.0.0.1:8000/api/hello/Ada
# Hello Ada!

curl 'http://127.0.0.1:8000/api/hello?name=Ada'
# Hello Ada!

curl -X POST http://127.0.0.1:8000/api/hi/Ada
# Hi Ada!

curl http://127.0.0.1:8000/health/status
# ok

Development Commands

composer validate --strict
composer check-platform-reqs
composer analyse
composer check-style
composer test
composer test:coverage
composer coverage:check

• CI runs the suite in .github/workflows/ci.yml on PHP 8.4 and 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%.

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:

./bin/podman-run.sh --environment development --detach
podman exec braidphp-development composer test
./bin/podman-run.sh --action down

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

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and AI_USE_POLICY.md.

Security

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

Release / Publishing

For a release, update CHANGELOG.md, run the validation commands above, create and push an annotated tag such as 1.0.2, publish a GitHub Release, and refresh the package on Packagist.

License And Attribution

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