---
title: "Base for Applications Category"
description: "Base for Applications"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-09-09"
last_update: "2026-09-09"
time_minutes: 1
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/core"
---

# Base for Applications



---

## Website Project

Base for Derafu's Websites

# Base for Derafu's Websites

This guide explains how to create a new website using the [Derafu Website Base](https://github.com/derafu/website), the [Docker](https://www.derafu.dev/docs/sysadmin/docker-php-caddy-server) and [PHP Deployer](https://www.derafu.dev/docs/sysadmin/deployer) projects for local development and deployment to the production server.

> [!TIP] WIP: Work in Progress
>
> The Road to Success is Always Under Construction.

## Quick Start

Create a new website based on this base:

```shell
composer create-project derafu/website www.example.com --stability=dev
```

## Review what you need to do, install, or know

### Configure ZSH on local macOS machine

If you're on macOS and use ZSH as your shell, you can configure ZSH to accept comments in commands with:

```shell
echo "setopt interactivecomments" >> ~/.zshrc
source ~/.zshrc
```

### SSH Key on local machine

It's necessary to have an SSH key on your local machine. This key will be used to configure your Docker container.

With the following command, you'll get an existing key or create a new one in `$HOME/.ssh/id_rsa` and `$HOME/.ssh/id_rsa.pub`. If a new one is created, you'll need to enter your email to identify the key owner. If you prefer, you can enter your username and machine name (in case you have multiple SSH keys in different environments).

```shell
SSH_KEY="$HOME/.ssh/id_rsa"
if [ -f "$SSH_KEY.pub" ]; then
    cat "$SSH_KEY.pub"
else
    echo -n "Enter your email: "; read COMMENT
    ssh-keygen -t rsa -b 4096 -N "" -C "$COMMENT" -f "$SSH_KEY"
    cat "$SSH_KEY.pub"
fi
```

With this command, the public key will be displayed on screen. If you need to see it again in the future, run:

```shell
cat $HOME/.ssh/id_rsa.pub
```

**Important**: The key in `$HOME/.ssh/id_rsa` is **private** and should never be shared.

### Add SSH key to GitHub

1. Go to [GitHub](https://github.com/settings/ssh/new).
2. In `Title`, enter the same email or comment you chose when creating the key.
3. In `Key`, paste the public key extracted with `cat $HOME/.ssh/id_rsa.pub`.
4. Click on `Add SSH key`.

### Docker container with PHP and Caddy

Prepare [Docker](https://www.derafu.dev/docs/sysadmin/docker-php-caddy-server) in `$DOCKER_DIR` on your local machine:

```shell
DEV_DIR=$HOME/dev
DOCKER_DIR=$DEV_DIR/docker-sites-php
mkdir -p $DEV_DIR
git clone https://github.com/derafu/docker-php-caddy-server.git $DOCKER_DIR
cat $HOME/.ssh/id_rsa.pub > $DOCKER_DIR/config/ssh/authorized_keys
cd $DOCKER_DIR
```

Copy and edit the `.env` file and configure the environment variables as needed.

```shell
# It's recommended to at least configure the DEPLOYER_HOST variable.
cp .env-dist .env
```

> [!WARNING]
>
>Don't proceed until you've reviewed and configured the `.env` file.

Build the Docker container:

```shell
docker-compose up -d
```

With this configuration, the folder where sites to be developed will be installed will be in `$DOCKER_DIR/sites`. This folder will be shared between your local machine and the Docker container.

### Connect to Docker container

Configure the `dev` SSH alias on your local machine:

```shell
echo "
Host dev
    HostName localhost
    User admin
    Port 2222
    IdentityFile $HOME/.ssh/id_rsa
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
" >> $HOME/.ssh/config
```

Then you can enter the Docker container with:

```shell
ssh dev
```

**Note**: The alias name can be whatever you want; in this case, `dev` was used.

### SSH key in Docker container

To work with private repositories and deploy to the production server, it's necessary that the SSH key from your local machine be added to the Docker container.

On your local machine, run:

```shell
scp $HOME/.ssh/id_rsa* dev:.ssh/
```

### Basic Git configuration

Perform the following configurations inside the Docker container.

First, configure your GitHub email and name:

> [!WARNING]
>
>Before pasting this command in the Docker container, edit it to use your GitHub email and name.

```shell
git config --global user.email "you@example.com"  # Your github email.
git config --global user.name "Your Name"         # Your name.
```

Configure case sensitivity and avoid mixing changes:

```shell
git config --global core.ignorecase false         # Case sensitive.
git config --global pull.rebase false             # Rebase instead of merge.
git config --global merge.ff false                # Fast forward.
```

Configure text editor:

```shell
git config --global core.editor nano              # Default editor nano or any other.
```

### Configure commit signing in Git

First, create the SSH key on your local machine:

```shell
SSH_KEY="$HOME/.ssh/id_ed25519"
if [ -f "$SSH_KEY.pub" ]; then
    cat "$SSH_KEY.pub"
else
    echo -n "Enter your email: "; read COMMENT
    ssh-keygen -t ed25519 -N "" -C "$COMMENT" -f "$SSH_KEY"
    cat "$SSH_KEY.pub"
fi
```

Then add the SSH key to the Docker container:

```shell
scp $HOME/.ssh/id_ed25519* dev:.ssh/
```

Finally, inside the Docker container, configure Git to sign commits:

```shell
git config --global commit.gpgSign true               # Sign commits.
git config --global user.signingkey ~/.ssh/id_ed25519 # Your ssh key.
git config --global gpg.format ssh                    # Use ssh key.
git config --global tag.gpgSign true                  # Sign tags.
```

## Develop a website

### Create a new website

Enter the container and run:

```shell
site-create www.example.com
```

**Note**: Creating the website requires as a subsequent step that you configure its repository on GitHub and add the site to the `$DEPLOYER_DIR/sites.php` file using the `site-add` command.

### Clone a website

Enter the container and run:

```shell
site-clone www.example.com git@github.com:example/example.git
```

**Note**: When cloning an existing website, the site is automatically added to the `$DEPLOYER_DIR/sites.php` file.

### Visit the website in the browser

On your machine, configure `/etc/hosts` by adding the local development domain:

```shell
echo "127.0.0.1         www.example.com.local" | sudo tee -a /etc/hosts
```

Then you can access the website via the URL https://www.example.com.local:8443

## Deploy a website to production

All these instructions are executed in the Docker container.

### Add website to configuration file

If you created the site from scratch instead of cloning it, make sure the website is added to the `$DEPLOYER_DIR/sites.php` file. You can validate this by running:

```shell
site-add www.example.com git@github.com:example/example.git
```

**Note**: If the site requires special configuration, you'll need to manually edit the `$DEPLOYER_DIR/sites.php` file.

### Style tests, code quality, and unit tests

Run style tests, code quality, and unit tests in the Docker container with:

```shell
site www.example.com
site-check
```

### Push changes to GitHub

If everything is correct, push the changes to GitHub:

```shell
site www.example.com
site-send "Website update."
```

**Note**: If the GitHub repository has a [configured webhook](https://www.derafu.dev/docs/sysadmin/github), the website will be deployed automatically when pushing changes and passing the style tests, code quality, and unit tests in the GitHub Actions workflow.

### Deployment

> [!INFO]
>
>It's not necessary to deploy to the production server if the GitHub repository has a [configured webhook](https://www.derafu.dev/docs/sysadmin/github){.alert-link}.

If there are no errors, you can deploy to the production server with:

```shell
#DEPLOYER_HOST=hosting.example.com # Only if not configured in .env
site-deploy www.example.com
```

If an error occurs when deploying and you try to make a new deploy, it's very likely that the deploy is locked. If this happens, you can unlock and deploy again with:

```shell
#DEPLOYER_HOST=hosting.example.com # Only if not configured in .env
site-deploy-locked www.example.com
```

## Update components

### Update Docker

On your local machine, run:

```shell
DEV_DIR=$HOME/dev
DOCKER_DIR=$DEV_DIR/docker-sites-php
cd $DOCKER_DIR
git pull
docker-compose build --no-cache
docker-compose up -d
```

> [!WARNING]
>
>You must add the SSH keys to the Docker container again and configure Git inside the container.

### Update PHP Deployer

Enter the container and run:

```shell
cd $DEPLOYER_DIR
git pull
composer update
```

### Update website

Enter the container and run:

```shell
site www.example.com
site-update
```

## Using development tools

### Composer

Install dependencies:

```shell
composer install
```

Add development dependency:

```shell
composer require --dev dependency-name
```

Add production dependency:

```shell
composer require dependency-name
```

Remove dependency:

```shell
composer remove dependency-name
```

Update dependencies:

```shell
composer update
```

**Note**: Normally only `composer install` is used to install dependencies.

### NPM

Install dependencies:

```shell
npm install
```

Add development dependency:

```shell
npm install --save-dev dependency-name
```

Add production dependency:

```shell
npm install --save dependency-name
```

Remove dependency:

```shell
npm uninstall dependency-name
```

Update dependencies:

```shell
npm update
```

**Note**: Normally only `npm install` is used to install dependencies.

### Git

View change status:

```shell
git status
```

Add changes:

```shell
git add .
```

Make commit:

```shell
git commit -m "Commit message"
```

Push changes to GitHub:

```shell
git push
```

Update local repository:

```shell
git pull
```

Undo changes:

```shell
git checkout -- .
```

**Note**: Instead of using dot `.`, you can specify the files you want to add, commit, or revert.

### PHP CS Fixer

Check code style:

```shell
composer phpcs
```

Fix code style:

```shell
composer phpcs-fix
```

### PHP Unit

Run unit tests:

```shell
composer tests
```

## Using terminal in Docker container

Enter a website directory:

```shell
cd $SITES_DIR/www.example.com
```

Exit directory:

```shell
cd ..
```

List files:

```shell
ls -la
```

View file content:

```shell
cat $DEPLOYER_DIR/sites.php
```

Edit a file:

```shell
nano $DEPLOYER_DIR/sites.php
```

Save and exit in `nano`:

```shell
Ctrl + X
```




---

## Foundation Project

Derafu Foundation

# Derafu Foundation




---

### Introduction

Base for Derafu's Projects

# Base for Derafu's Projects

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/foundation/main)
![CI Workflow](https://github.com/derafu/foundation/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/foundation)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/foundation)
![Total Downloads](https://poser.pugx.org/derafu/foundation/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/foundation/d/monthly)

## Overview

Derafu Foundation is a standardized base for creating consistent PHP projects. It provides a pre-configured environment with best practices for code organization, documentation, testing, and code quality assurance. This foundation is designed to streamline the creation of new projects while ensuring they follow consistent patterns and standards.

## Key Features

- **Standardized Structure**: Consistent file and directory organization across all projects.
- **Code Quality Tools**: Pre-configured PHP CS Fixer, PHPStan, and PHPUnit setups.
- **Asset Management**: Built-in Vite configuration for CSS, JavaScript, and image optimization.
- **Documentation**: Automatic website generation from README.md with GitHub Pages deployment.
- **CI/CD Integration**: GitHub Actions workflows for continuous integration and deployment.
- **Middleware-based HTTP Layer**: Ready-to-use PSR-compliant HTTP handling.
- **Routing System**: Flexible routing with support for static routes and filesystem-based routes.
- **Templating**: Twig and Markdown rendering support.

## Quick Start

### Installation

Create a new project based on this foundation:

```shell
composer create-project derafu/project project_dir --stability=dev
```

### Asset Compilation

If your project uses CSS, JavaScript, or images, add them to the `assets` directory and compile them:

```shell
npm install
npm run build
```

### Development Server

Start the built-in PHP development server:

```shell
php -S localhost:9000 public/index.php
```

Then visit [http://localhost:9000](http://localhost:9000) to see your project.

## Project Structure

```
project_dir/
├── .github/             # GitHub configurations and workflows.
├── app/                 # Application bootstrap files.
├── assets/              # Frontend assets (CSS, JS, images).
├── config/              # Configuration files.
│   ├── routes.yaml      # Route definitions.
│   └── services.yaml    # Service container configuration.
├── public/              # Web server root directory.
│   ├── index.php        # Application entry point.
│   └── static/          # Compiled assets (generated).
├── src/                 # Source code.
├── templates/           # Template files.
│   ├── components/      # Reusable template components.
│   ├── layouts/         # Layout templates.
│   └── pages/           # Page templates.
├── tests/               # Test files.
│   ├── fixtures/        # Test fixtures.
│   └── src/             # Source code tests.
├── vendor/              # Composer dependencies.
├── var/                 # Temporary files and caches.
├── .gitignore           # Git ignore configuration.
├── LICENSE              # MIT License.
├── package.json         # NPM configuration.
├── php-cs-fixer.php     # PHP CS Fixer configuration.
├── phpstan.neon         # PHPStan configuration.
├── phpunit.xml          # PHPUnit configuration.
├── README.md            # Project documentation.
└── vite.config.js       # Vite build configuration.
```

## Customization

After creating a project based on this foundation, you can:

1. Modify `README.md` with your project-specific details.
2. Update `package.json` with your project information.
3. Add your routes in `config/routes.yaml`.
4. Customize services in `config/services.yaml`.
5. Create controllers and other classes in the `src/` directory.
6. Add templates to the `templates/` directory.
7. Write tests in the `tests/` directory.




---

### Project Structure

Project Structure

# Project Structure

Derafu Foundation provides a standardized directory structure for your projects. This document explains the purpose of each directory and key files.

## Root Directories

### `.github/`

Contains GitHub-specific configurations:

- `workflows/ci.yml`: Continuous Integration workflow that runs tests and code quality checks.
- `workflows/cd.yml`: Continuous Deployment workflow for automatically deploying. By default, it is configured to deploy to GitHub Pages. Deployment is disabled by default, just remove the `false &&` in the file to enable it.

### `app/`

Application bootstrap files:

- `bootstrap.php`: The main bootstrap file that initializes the application runtime.

### `assets/`

Frontend assets organized by type:

- `css/`: CSS stylesheets.
- `js/`: JavaScript files.
- `img/`: Images and other media files.

### `config/`

Configuration files:

- `routes.yaml`: Route definitions for your application.
- `services.yaml`: Service container configuration (dependency injection).

### `public/`

Web server document root:

- `index.php`: Application entry point with Front Controller.
- `static/`: Compiled assets (generated by the build process).

**Note**: If your application doesn't need a Front Controller, by default, it's used only for documentation.

### `src/`

Application source code. Organize your PHP classes here according to their namespace. By convention, but not enforced out of Derafu ORG, use:

- `Abstract/`: Abstract classes, with `Abstract` prefix.
- `Contract/`: Interfaces for your application, with `Interface` suffix.
- `Controller/`: Controller classes, with `Controller` suffix.
- `Service/`: Service classes.

### `templates/`

Template files for rendering HTML:

- `components/`: Reusable template components (header, footer, etc.).
- `layouts/`: Layout templates that define page structure.
- `pages/`: Page-specific templates.
- `base.html.twig`: Base template that defines the HTML structure for all layouts.
- `error.html.twig`: Error page template.
- `html.html.twig`: HTML wrapper template, used when rendering a markdown o php template.

### `tests/`

Test files:

- `fixtures/`: Test fixtures and sample data.
- `src/`: Tests for your source code. You can organize your tests by tests suits, mirroring the structure of the `src/` directory, by features or any other criteria (but not enforced out of Derafu ORG).

### `var/`

Temporary files and caches:

- `cache/`: Cache files.
- `logs/`: Log files.
- `tmp/`: Temporary files.

## Key Files

### Configuration Files

- `.gitignore`: Specifies files that Git should ignore.
- `LICENSE`: MIT license file by default.
- `package.json`: NPM configuration for frontend assets.
- `php-cs-fixer.php`: PHP CS Fixer configuration.
- `phpstan.neon`: PHPStan configuration.
- `phpunit.xml`: PHPUnit configuration.
- `vite.config.js`: Vite build configuration.

### Application Files

- `public/index.php`: Main entry point that bootstraps the application.
- `app/bootstrap.php`: Initializes the runtime environment.

## File Copying Mechanism

The `Installer` class in `Installer.php` is responsible for copying foundation files to new projects during Composer installation. This class:

1. Defines a list of files to copy in the `FILES` constant.
2. Copies each file from the foundation package to the project directory.
3. Creates necessary directories if they don't exist.
4. Handles file overwrite rules (some files are configured to be overwritten in updates, others not).

Files marked with `true` in the `FILES` constant will be overwritten if they already exist:

```php
private const FILES = [
    // Files that will not be overwritten if they exist.
    '.github/workflows/cd.yml',
    '.github/workflows/ci.yml',
    // Files that will be overwritten even if they exist.
    'app/bootstrap.php' => true,
    // ...
];
```

**Note**: The idea behind overwriting files is to make it easier to update the foundation. But, you can disable it by removing the `Derafu\\Foundation\\Installer::copyFiles` from the `post-install-cmd` and `post-update-cmd` scripts in your `composer.json` file.

## Extending the Structure

When creating a new project based on this foundation, you should:

1. Keep the existing directory structure.
2. Add your own directories as needed.
3. Follow PSR-4 autoloading standards for your PHP classes.
4. Place tests in the corresponding structure within the `tests/` directory.

The structure is designed to be flexible while providing a consistent organization pattern across projects.




---

### Assets

Frontend Asset Management

# Frontend Asset Management

Derafu Foundation includes a pre-configured asset build system using [Vite](https://vitejs.dev). This document explains how to work with frontend assets in your project.

## Overview

The asset management system handles:

- CSS compilation.
- JavaScript bundling.
- Image optimization.
- Source maps generation.
- Asset versioning.

## Directory Structure

```
project_dir/
├── assets/
│   ├── css/
│   │   └── app.css           # Main CSS file.
│   ├── img/                  # Image files.
│   └── js/
│       ├── app.js            # Main JavaScript entry point.
│       └── images.js         # Image import handling.
├── public/
│   └── static/               # Output directory (generated).
│       ├── css/
│       ├── img/
│       └── js/
└── vite.config.js            # Vite configuration.
```

## Configuration

The Vite configuration is defined in `vite.config.js`. Key features include:

- Multiple entry points: `app.js`, `app.css`, and `images.js`.
- Output directory: `public/static/`.
- Custom file naming with `.min` suffix.
- Image optimization using `vite-plugin-sharp`.

### Entry Points

- `app.js`: Main JavaScript code.
- `app.css`: Main CSS styles.
- `images.js`: Used for processing and importing images.

### Image Optimization

Images are automatically optimized during the build process using the Sharp image processing library. The configuration includes:

- PNG compression: Quality 85%, maximum compression level.
- JPEG compression: Quality 85%, progressive encoding.
- Automatic resizing of large images to a maximum of 2000×2000 pixels.

## Usage

### Adding Assets

1. **CSS**: Add your CSS files to the `assets/css/` directory.
2. **JavaScript**: Add your JavaScript files to the `assets/js/` directory.
3. **Images**: Add your images to the `assets/img/` directory.

### Importing Assets

#### CSS

In your main `app.css` file:

```css
/* Import other CSS files */
@import './components/buttons.css';
```

#### JavaScript

In your JavaScript files:

```javascript
// Import other JavaScript files.
import './components/slider.js';

// Import CSS from JavaScript.
import '../css/components/modal.css';

// Import images.
import logo from '../img/logo.png';
```

#### Images

For processing multiple images at once, use the `images.js` file:

```javascript
// Import all images in a directory.
import.meta.glob('../img/**/*');
```

### Building Assets

To build assets for production:

```shell
npm run build
```

This will:

1. Compile and bundle all assets.
2. Optimize images.
3. Generate minified files with source maps.
4. Output everything to the `public/static/` directory.

### Using Built Assets

In your HTML/Twig templates, reference the built assets:

```html
<link rel="stylesheet" href="https://www.derafu.dev/static/css/app.min.css">
<script src="https://www.derafu.dev/static/js/app.min.js"></script>
<img src="https://www.derafu.dev/static/img/logo.png">
```

## Best Practices

1. **Organize by component**: Group related CSS, JS, and images by feature or component.
2. **Optimize images before adding**: While the build process optimizes images, starting with optimized images is better.
3. **Use CSS imports**: Keep CSS modular by using imports.
4. **Lazy load images**: For image-heavy pages, consider implementing lazy loading.
5. **Watch file size**: Monitor the size of your built assets to ensure optimal loading times.

## Advanced Configuration

The Vite configuration can be extended to support:

- CSS preprocessors (Sass, Less, etc.).
- TypeScript.
- Additional plugins for specific needs.
- Custom output paths and formats.

To modify the configuration, edit the `vite.config.js` file as needed (remember to deactivate the `Derafu\\Foundation\\Installer::copyFiles` from the `post-install-cmd` and `post-update-cmd` scripts in your `composer.json` file).




---

### Code Quality

Code Quality Tools

# Code Quality Tools

Derafu Foundation comes with pre-configured code quality tools to ensure consistent code style and identify potential issues early in development. This document explains how to use these tools effectively.

## PHP CS Fixer

PHP CS Fixer is a tool that automatically fixes PHP coding standards issues in your code according to rules you define.

### Configuration

The configuration is defined in `php-cs-fixer.php` at the root of your project. Key features include:

- PSR-12 coding standards by default.
- Strict type declarations enabled.
- Automatic array syntax conversion to short syntax.
- Ordered imports.
- Modern PHP features optimization (e.g., arrow functions).
- PHPUnit strict assertions.

### Usage

Run PHP CS Fixer to check code style issues:

```shell
vendor/bin/php-cs-fixer fix --dry-run --diff
```

Fix code style issues automatically:

```shell
vendor/bin/php-cs-fixer fix
```

## PHPStan

PHPStan is a static analysis tool that finds bugs in your code without running it. It's focused on finding errors in code logic.

### Configuration

The configuration is defined in `phpstan.neon` at the root of your project. By default, it:

- Sets analysis level to 5 (out of 9)
- Analyzes code in the `src` and `tests` directories

### Levels Explained

- Level 1: Basic checks.
- Level 2: Possibly undefined variables.
- Level 3: Return types, phpdocs.
- Level 4: Type hints.
- Level 5: Basic dead code detection.
- Level 6: Detecting unreachable code.
- Level 7: Union types.
- Level 8: More precise analysis
- Level 9: Mixed type detection

### Usage

Run PHPStan analysis:

```shell
vendor/bin/phpstan analyse
```

## PHPUnit

PHPUnit is the standard testing framework for PHP applications.

### Configuration

The configuration is defined in `phpunit.xml` at the root of your project. Key features include:

- Test coverage reporting enabled.
- Strict mode enabled (fails on warnings, notices, etc.).
- Test results output to `var/tests-coverage.txt` and `var/tests-coverage.xml`.
- Test documentation output to `var/tests-testdox.txt`.

### Directory Structure

- `tests/src/`: Unit tests for your source code.
- `tests/fixtures/`: Test data and fixtures.

### Usage

Run the test suite:

```shell
vendor/bin/phpunit
```

Generate test coverage reports:

```shell
vendor/bin/phpunit --coverage-html var/coverage
```

## Integration with CI/CD

These tools are integrated into the CI workflow (`.github/workflows/ci.yml`), which automatically runs on each push to the repository. This ensures that code quality standards are maintained throughout development.

## Best Practices

1. **Run tools locally before committing**: This helps catch issues before they enter the codebase.
2. **Gradually increase PHPStan level**: Start with level 5 and work toward higher levels as your project matures.
3. **Aim for high test coverage**: Write tests for all critical code paths.
4. **Update rules as needed**: Customize tool configurations to match your project's specific requirements (remember to deactivate the `Derafu\\Foundation\\Installer::copyFiles` from the `post-install-cmd` and `post-update-cmd` scripts in your `composer.json` file).




---

### GitHub Actions

GitHub Actions

# GitHub Actions

Derafu Foundation includes pre-configured GitHub Actions workflows for continuous integration (CI) and continuous deployment (CD). This document explains how these workflows work and how to customize them.

## Overview

The `.github/workflows/` directory contains two main workflow files:

- `ci.yml`: Continuous Integration workflow.
- `cd.yml`: Continuous Deployment workflow.

## Continuous Integration (CI)

The CI workflow runs automatically on each push and pull request to validate code quality and ensure tests pass.

### What It Does

The CI workflow:

1. Sets up multiple PHP versions for testing.
2. Installs dependencies using Composer.
3. Validates Composer configuration.
4. Runs PHP CS Fixer to check code style.
5. Runs PHPStan for static analysis.
6. Runs PHPUnit tests.
7. Generates test coverage reports.

### Customization

To customize the CI workflow, edit the `.github/workflows/ci.yml` file. Common customizations include:

- Changing PHP versions to test against.
- Adding or removing validation steps.
- Modifying test coverage thresholds.
- Changing notification settings.

Example of adding a new PHP version to test against:

```yaml
# In .github/workflows/ci.yml
jobs:
  tests:
    strategy:
      matrix:
        php-version: ['8.3', '8.4']  # Add or remove versions as needed.
```

## Continuous Deployment (CD)

The CD workflow automatically builds and deploys your project documentation to GitHub Pages when changes are pushed to the main branch.

**Note**: Deployment is disabled by default, just remove the `false &&` in the file to enable it.

### What It Does

The CD workflow:

1. Checks out the repository.
2. Sets up Node.js.
3. Installs frontend dependencies.
4. Builds assets using Vite.
5. Sets up PHP.
6. Installs Composer dependencies.
7. Generates a static website from your project documentation.
8. Deploys the static website to GitHub Pages.

### GitHub Pages Setup

To use the CD workflow, you need to:

1. Enable GitHub Pages in your repository settings.
2. Set the source branch to `gh-pages` and the directory to `/` (root).
3. Ensure the workflow has permission to write to the repository.

### Customization

To customize the CD workflow, edit the `.github/workflows/cd.yml` file. Common customizations include:

- Changing the deployment branch.
- Adding custom build steps.
- Configuring environment variables.
- Adding additional deployment targets.

Example of changing the deployment branch:

```yaml
# In .github/workflows/cd.yml
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    publish_branch: documentation  # Change from gh-pages to another branch name.
```

## Workflow Badges

You can add workflow status badges to your README.md to show the current status of your workflows:

```markdown
![GitHub last commit](https://img.shields.io/github/last-commit/derafu/project/main)
![CI Workflow](https://github.com/derafu/project/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/project)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/project)
![Total Downloads](https://poser.pugx.org/derafu/project/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/project/d/monthly)
```

Replace `derafu/project` with your actual GitHub username and repository name.

## Best Practices

1. **Keep workflows fast**: Optimize workflows to complete quickly.
2. **Use caching**: Cache dependencies to speed up builds.
3. **Secure secrets**: Use GitHub Secrets for sensitive information.
4. **Test workflow changes**: Test workflow changes on a feature branch before merging to main.
5. **Monitor workflow runs**: Regularly check workflow runs for issues.

## Troubleshooting

If a workflow fails:

1. Check the workflow run logs in the GitHub Actions tab.
2. Verify that all dependencies are correctly installed.
3. Ensure environment variables are correctly set.
4. Check if tests are failing locally as well.
5. Look for GitHub Actions service status issues.

If needed, you can run the workflow manually from the Actions tab by selecting the workflow and clicking "Run workflow".




---

## HTTP Project

Derafu HTTP

# Derafu HTTP




---

### Introduction

Standard-Compliant HTTP Library with Extended Features

# Standard-Compliant HTTP Library with Extended Features

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/http/main)
![CI Workflow](https://github.com/derafu/http/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/http)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/http)
![Total Downloads](https://poser.pugx.org/derafu/http/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/http/d/monthly)

A PSR and RFC compliant HTTP library that provides elegant request/response handling, content negotiation and problem details for PHP applications.

## Why Derafu\Http?

### 🎯 **Simple, but not limited, HTTP Handling**

Most HTTP libraries either do too much or too little. Derafu\Http provides:

- **Extended Request/Response**: Smart content type negotiation and safe data access.
- **Content Negotiation**: Intelligent format detection and response transformation.
- **Problem Details**: RFC 7807 implementation for structured error handling.
- **PSR Compliance**: Built on PSR-7 and PSR-15 standards.
- **Middleware Architecture**: Flexible request/response processing pipeline.

### ✨ **Key Features**

- **Smart Request Handling**: Safe access to query, post, and JSON data.
- **Intelligent Responses**: Automatic content negotiation and format transformation.
- **Structured Errors**: Complete RFC 7807 Problem Details implementation.
- **Modular Design**: Core HTTP functionality with middleware support.
- **Type Safety**: Use of enums for HTTP status codes and content types.
- **Middleware Pipeline**: PSR-15 compliant middleware chain for request processing.

## Installation

```bash
composer require derafu/http
```

## Basic Usage

### public/index.php

```php
use Derafu\Http\Kernel;
use Derafu\Kernel\Environment;

require_once dirname(__DIR__) . '/app/bootstrap.php';

return fn (array $context): Kernel => new Kernel(new Environment(
    $context['APP_ENV'],
    (bool) $context['APP_DEBUG'],
    $context
));
```

### Middleware Configuration

The library uses PSR-15 middlewares for request processing. Configure your middleware stack in the services file, for example `services.yaml`:

```yaml
# Core middlewares in required order.
Psr\Http\Server\RequestHandlerInterface:
    class: Derafu\Http\Service\RequestHandler
    public: true
    arguments:
        $middlewares:
            - '@Derafu\Http\Middleware\RequestFactoryMiddleware'
            - '@Derafu\Http\Middleware\RouterMiddleware'
            - '@Derafu\Http\Middleware\DispatcherMiddleware'
            - '@Derafu\Http\Middleware\ResponseNormalizerMiddleware'

# Register individual middlewares.
Derafu\Http\Middleware\RequestFactoryMiddleware: ~
Derafu\Http\Middleware\RouterMiddleware: ~
Derafu\Http\Middleware\DispatcherMiddleware: ~
Derafu\Http\Middleware\ResponseNormalizerMiddleware: ~
```

### Core Middlewares

The library includes four essential middlewares that must be configured in order:

1. **RequestFactoryMiddleware**: Converts PSR-7 requests to Derafu requests.
2. **RouterMiddleware**: Handles URL routing and route matching.
3. **DispatcherMiddleware**: Executes route handlers (controllers, closures or templates).
4. **ResponseNormalizerMiddleware**: Ensures PSR-7 compliant responses.

### Custom Middlewares

Create custom middlewares by implementing PSR-15's `MiddlewareInterface`:

```php
class CustomMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        // Process request.
        $response = $handler->handle($request);
        // Process response.
        return $response;
    }
}
```

### Working with Requests

```php
// Safe access to request data.
$id = $request->query('id', 0);
$data = $request->json();
$file = $request->file('document');

// Content negotiation.
$format = $request->getPreferredFormat();
```

### Creating Responses

```php
// Automatic content negotiation.
// Returns JSON for API requests in `/api` paths
return ['status' => 'ok'];

// Explicit responses.
return (new Response())->asJson($data)->withHttpStatus(HttpStatus::CREATED);

// Redirect.
return (new Response())->redirect('https://www.example.com');
```

### Error Handling with Problem Details

Any exception will be treated as "Problem Detail" (RFC 7807). To have control over all fields, exceptions must implement `HttpExceptionInterface`.

```json
{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "No route found for \"/api/mustFail\".",
    "instance": "/api/mustFail",
    "extensions": {
        "timestamp": "2025-02-20T22:04:25+00:00",
        "environment": "dev",
        "debug": true,
        "context": [],
        "throwable": null
    }
}
```

## Integration with Other Packages

Derafu\Http is designed to work with other Derafu packages:

### Required

- **derafu/kernel**: The core of the application, with dependency injection.
- **derafu/renderer**: For template rendering, with dependency on **derafu/twig**.
- **derafu/routing**: For URL routing, with autodiscovery of templates.
- **derafu/translation**: For I18n, with a simple translator that supports ICU.

### Optional

- **derafu/markdown**: For renderig templates in markdown format.

### Suggested

- **derafu/data-processor**: For data processing: format, cast, sanitize and validate.




---

### HTTP Flow

Flow - Detailed Explanation

# Flow - Detailed Explanation

The Derafu HTTP component implements a clean, modular approach to handling HTTP requests in PHP applications. The flow diagram illustrates how an HTTP request travels through the system, from the initial client request to the final response delivery.

{.w-75 .mx-auto}
![HTTP Flow](https://www.derafu.dev/img/diagrams/content/docs/core/http/derafu-http-flow.svg)

## Key Components

### Client

The external entity (browser, API consumer, etc.) that initiates the HTTP request and receives the response.

### Runtime
The application's entry point and execution environment. It serves as the orchestrator of the entire HTTP flow, responsible for:

- Bootstrapping the application.
- Creating the PSR-7 request object from the HTTP request.
- Initializing the kernel.
- Delegating request processing.
- Sending the response back to the client.

### Kernel

The core of the application, responsible for:

- Building and configuring the dependency injection container.
- Loading application configurations.
- Managing the application lifecycle.
- Coordinating the request handling process.

The Kernel implements a micro-kernel architecture that keeps the core small and efficient while pushing most functionality to handlers and middleware.

### Request Handler

Processes the HTTP request and produces a response. Handlers:

- Receive the request from the kernel.
- Apply application logic.
- Generate an appropriate response.
- May use services from the container to fulfill the request.

### Request

A PSR-7 compliant ServerRequest object that represents the HTTP request. It encapsulates:

- HTTP method.
- URI and query parameters.
- Headers.
- Body content.
- Server and environment variables.

### Response

A PSR-7 compliant Response object that represents the HTTP response. It includes:

- Status code.
- Headers.
- Response body.

### Container

The dependency injection container that:

- Manages service instantiation and configuration.
- Provides service dependencies throughout the application.
- Implements the PSR-11 container interface.
- Supports autowiring for simplified service definition.

## The HTTP Request/Response Flow

1. **Client Sends HTTP Request**
   The flow begins when a client makes an HTTP request to the application.

2. **Runtime Creates Request Object**
   The Runtime transforms the raw HTTP request into a PSR-7 compliant Request object, preparing it for processing.

3. **Runtime Initializes Kernel**
   The Kernel is initialized with the necessary configurations to process the current request.

4. **Kernel Builds Container**
   The Kernel builds and configures the dependency injection container, making all application services available.

5. **Runtime Delegates Request Processing**
   The Runtime passes the Request object to the Kernel for processing.

6. **Kernel Delegates to Handler**
   The Kernel identifies the appropriate Request Handler based on routing information and delegates the request processing.

7. **Handler Generates Response**
   The Handler applies business logic, interacts with the application services as needed, and generates a Response object.

8. **Response Returned to Runtime**
   The generated Response is returned through the call chain back to the Runtime.

9. **Runtime Sends Response to Client**
   The Runtime outputs the Response to the client, completing the HTTP cycle.




---

### Design Principles

Design Principles

# Design Principles

The Derafu HTTP component provides a lightweight, standards-compliant approach to HTTP request handling. By following established PHP interoperability standards (PSRs) and sound architectural principles, it enables the development of robust, maintainable web applications with minimal overhead.

The Derafu HTTP is designed with several key principles in mind:

## PSR Compliance

- Implements PSR-7 for HTTP messages.
- Follows PSR-11 for container interoperability.
- Supports PSR-15 for middleware.

## Separation of Concerns

Each component has a single, well-defined responsibility:

- Runtime manages the application lifecycle.
- Kernel coordinates processing.
- Handlers implement business logic.
- Container manages dependencies.

## Flexibility

The design allows for:

- Custom request handlers.
- Middleware integration.
- Extensible container configuration.
- Multiple runtime environments.

## Testability

The clear separation of components and dependency injection make unit testing straightforward:

- Mock the container for handler tests.
- Create test requests easily.
- Validate responses without invoking the full stack.

## Implementation Guidelines

When working with the Derafu HTTP component:

1. **Define Request Handlers** for different routes or endpoints.
2. **Configure the Container** with your application services.
3. **Set up your routes** to map URLs to handlers.
4. **Extend the base classes** as needed for custom functionality.

The architecture is designed to be minimal yet powerful, allowing developers to focus on the business logic rather than HTTP processing details.




---

## Routing Project

Derafu Routing

# Derafu Routing




---

### Introduction

Elegant PHP Router with Plugin Architecture

# Elegant PHP Router with Plugin Architecture

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/routing/main)
![CI Workflow](https://github.com/derafu/routing/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/routing)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/routing)
![Total Downloads](https://poser.pugx.org/derafu/routing/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/routing/d/monthly)

A lightweight, extensible PHP routing library that combines simplicity with power through its parser-based architecture.

## Features

- 🔌 Plugin architecture with swappable parsers.
- 🎯 Multiple routing strategies (static, dynamic, filesystem).
- 🧩 Easy to extend with custom parsers.
- 📁 Built-in filesystem routing for static sites.
- 🔄 Support for different content types (.md, .twig, etc.).
- 🛠️ Clean separation of concerns.
- 🪶 Lightweight with zero dependencies.
- ⚡ Fast pattern matching.
- 🧪 Comprehensive test coverage.
- 🔗 URL generation for named routes.

## Why Derafu\Routing?

Unlike traditional monolithic routers, Derafu\Routing uses a unique parser-based architecture that offers several advantages:

- **Modularity**: Each routing strategy is encapsulated in its own parser.
- **Flexibility**: Easy to add new routing patterns without modifying existing code.
- **Clarity**: Clear separation between route matching and request handling.
- **Extensibility**: Add custom parsers for specific routing needs.
- **Predictability**: Each parser has a single responsibility.
- **Performance**: Only load the parsers you need.

## Installation

Install via Composer:

```bash
composer require derafu/routing
```

## Basic Usage

```php
use Derafu\Routing\Router;
use Derafu\Routing\Dispatcher;
use Derafu\Routing\Parser\StaticParser;
use Derafu\Routing\Parser\FileSystemParser;

// Create and configure router.
$router = new Router();
$router->addParser(new StaticParser());
$router->addParser(new FileSystemParser([__DIR__ . '/pages']));

// Add routes.
$router->addRoute('/', 'HomeController::index', name: 'home');
$router->addDirectory(__DIR__ . '/pages');

// Create and configure dispatcher.
$dispatcher = new Dispatcher([
    'md' => fn ($file, $params) => renderMarkdown($file),
    'twig' => fn($file, $params) => renderTwig($file, $params),
]);

// Handle request.
try {
    $route = $router->match();
    echo $dispatcher->dispatch($route);
} catch (RouterException $e) {
    // Handle error.
}
```

## Available Parsers

### StaticParser

Handles exact route matches:

```php
$router->addRoute('/about', 'PagesController::about', name: 'about');
```

### DynamicParser

Supports parameters and patterns:

```php
$router->addRoute('/users/{id:\d+}', 'UserController::show', name: 'user.show');
$router->addRoute('/blog/{year}/{slug}', 'BlogController::post', name: 'blog.post');
```

### FileSystemParser

Maps URLs to files in directories:

```php
$router->addDirectory(__DIR__ . '/pages');
// Examples:
// /about maps to /pages/about.md
// /contact maps to /pages/contact.html.twig
```

## URL Generation

Generate URLs for named routes:

```php
// Set request context (needed for absolute URLs).
$router->setContext(new RequestContext(
    baseUrl: '/myapp',
    scheme: 'https',
    host: 'example.com'
));

// Generate URLs.
$url = $router->generate('user.show', ['id' => 123]); // /myapp/users/123
$url = $router->generate('blog.post', [
    'year' => '2024',
    'slug' => 'hello-world'
]); // /myapp/blog/2024/hello-world

// Generate absolute URL.
$url = $router->generate('about', [], UrlReferenceType::ABSOLUTE_URL);
// https://example.com/myapp/about
```

## Creating Custom Parsers

Implement your own routing strategy by creating a parser:

```php
class CustomParser implements ParserInterface
{
    public function parse(string $uri, array $routes): ?RouteMatch
    {
        // Your custom routing logic.
    }

    public function supports(Route $route): bool
    {
        // Define what routes this parser can handle.
    }
}

$router->addParser(new CustomParser());
```

## File-based Routing Example

Perfect for static sites:

```
pages/
├── about.md
├── contact.html.twig
└── blog/
    ├── post-1.md
    └── post-2.md
```

URLs are automatically mapped to files:

- `/about` → `pages/about.md`
- `/contact` → `pages/contact.html.twig`
- `/blog/post-1` → `pages/blog/post-1.md`




---

### Guide

Complete Usage Guide

# Complete Usage Guide

Derafu Routing is a flexible PHP routing library that uses a parser-based architecture. Instead of having a monolithic router, it separates routing logic into specialized parsers, each handling different types of routes.

## Installation

```bash
composer require derafu/routing
```

## Basic Concepts

### Parser Architecture

The routing system is built around specialized parsers:

1. **StaticParser**: Handles exact route matches.
2. **DynamicParser**: Processes routes with parameters.
3. **FileSystemParser**: Maps URLs to physical files.

Each parser implements the `ParserInterface`:

```php
interface ParserInterface {
    public function parse(string $uri, array $routes): ?RouteMatchInterface;
    public function supports(RouteInterface $route): bool;
}
```

## Route Types

### Static Routes

The simplest form of routing, handled by `StaticParser`:

```php
$router = new Router([new StaticParser()]);
$router->addRoute('/about', 'PagesController::action', name: 'about');
$router->addRoute('/contact', 'ContactController::show', name: 'contact');
```

### Dynamic Routes

Handled by `DynamicParser`, supporting various parameter types:

```php
$router->addParser(new DynamicParser());

// Basic parameter.
$router->addRoute('/users/{id}', 'UserController::show', name: 'user.show');

// Validation with regular expressions.
$router->addRoute('/users/{id:\d+}', 'UserController::show', name: 'user.show');

// Optional parameters.
$router->addRoute('/blog/{year?}', 'BlogController::index', name: 'blog.index');

// Multiple parameters.
$router->addRoute('/blog/{year}/{month?}', 'BlogController::archive', name: 'blog.archive');

// Complex patterns.
$router->addRoute('/users/{username:[a-z0-9_-]+}', 'UserController::profile', name: 'user.profile');
```

### Filesystem Routes

The `FileSystemParser` maps URLs to actual files:

```php
$parser = new FileSystemParser(
    directories: [__DIR__ . '/pages'],
    extensions: ['.html.twig', '.md']
);
$router->addParser($parser);
```

Directory structure:
```
pages/
├── about.md           # Matches /about
├── contact.twig       # Matches /contact
└── blog/
    ├── post-1.md     # Matches /blog/post-1
    └── post-2.md     # Matches /blog/post-2
```

## Using the Router

### Basic Configuration

```php
use Derafu\Routing\Router;
use Derafu\Routing\Parser\StaticParser;
use Derafu\Routing\Parser\DynamicParser;

$router = new Router([
    new StaticParser(),
    new DynamicParser(),
]);
```

### Adding Routes

```php
// String handler (Controller@action).
$router->addRoute('/users', 'UserController::index', name: 'users.index');

// Closure handler.
$router->addRoute('/api/data', function($params) {
    return ['data' => 'value'];
}, name: 'api.data');

// Array handler.
$router->addRoute('/blog', [
    'controller' => 'BlogController',
    'action' => 'list'
], name: 'blog.index');

// Routes with name and parameters.
$router->addRoute(
    route: '/users/{id}',
    handler: 'UserController::show',
    name: 'user.show',
    parameters: ['active' => true]
);
```

### Route Matching

```php
try {
    $match = $router->match('/users/123');
    // $match->getHandler(): Returns the route handler.
    // $match->getParameters(): Returns the route parameters.
    // $match->getName(): Returns the route name if defined.
} catch (RouteNotFoundException $e) {
    // Handle 404.
}
```

### URL Generation

The router allows generating URLs from named routes:

```php
// Set request context (needed for absolute URLs).
$router->setContext(new RequestContext(
    baseUrl: '/myapp',
    scheme: 'https',
    host: 'example.com'
));

// Generate relative URLs.
$url = $router->generate('user.show', ['id' => 123]); // /myapp/users/123
$url = $router->generate('blog.archive', [
    'year' => '2024',
    'month' => '03'
]); // /myapp/blog/2024/03

// Generate URL without optional parameter.
$url = $router->generate('blog.archive', [
    'year' => '2024'
]); // /myapp/blog/2024

// Generate absolute URL.
$url = $router->generate('about', [], UrlReferenceType::ABSOLUTE_URL);
// https://example.com/myapp/about

// Generate network path URL.
$url = $router->generate('about', [], UrlReferenceType::NETWORK_PATH);
// //example.com/myapp/about
```

Available reference types are:

- `ABSOLUTE_PATH`: Absolute path from root (default).
- `ABSOLUTE_URL`: Complete URL with scheme and host.
- `NETWORK_PATH`: URL without scheme (useful for resources that work on both HTTP and HTTPS).

## The Dispatcher

The dispatcher handles the execution of matching routes:

```php
$dispatcher = new Dispatcher([
    'md' => function($file, $params) {
        // Render markdown file.
        return parseMarkdown(file_get_contents($file));
    },
    'twig' => function($file, $params) {
        // Render Twig template.
        return $twig->render($file, $params);
    }
]);

$result = $dispatcher->dispatch($match);
```

**Note**: This is a very basic *dispatcher*, you should implement your own.

## Advanced Usage

### Custom Parser Example

```php
class RegexParser implements ParserInterface
{
    public function parse(string $uri, array $routes): ?RouteMatchInterface
    {
        foreach ($routes as $route) {
            if (!$this->supports($route)) {
                continue;
            }

            // Custom regex matching logic
            if (preg_match($route->getPath(), $uri, $matches)) {
                return new RouteMatch(
                    $route->getHandler(),
                    $matches
                );
            }
        }
        return null;
    }

    public function supports(RouteInterface $route): bool
    {
        // Define what routes this parser can handle
        return str_starts_with($route->getPath(), '#');
    }
}
```

## Best Practices

1. **Parser Order**: Add parsers in order of specificity.
   - StaticParser first (faster, more specific).
   - DynamicParser next.
   - FileSystemParser last (more flexible but slower).

2. **Route Organization**: Group related routes.
   ```php
   // User management
   $router->addRoute('/users', 'UserController::index', name: 'users.index');
   $router->addRoute('/users/{id}', 'UserController::show', name: 'users.show');

   // Blog system
   $router->addRoute('/blog', 'BlogController::index', name: 'blog.index');
   $router->addRoute('/blog/{slug}', 'BlogController::show', name: 'blog.show');
   ```

3. **Parameter Validation**: Use regex constraints for better security.
   ```php
   // Ensure ID is numeric.
   $router->addRoute('/users/{id:\d+}', 'UserController::show', name: 'users.show');

   // Validate username format.
   $router->addRoute('/users/{username:[a-z0-9_-]+}', 'UserController::profile', name: 'users.profile');
   ```

4. **Error Handling**: Always wrap matches in try-catch.
   ```php
   try {
       $match = $router->match($uri);
       $result = $dispatcher->dispatch($match);
   } catch (RouteNotFoundException $e) {
       // Handle 404.
   } catch (DispatcherException $e) {
       // Handle dispatcher errors.
   }
   ```

5. **URL Generation**: Always use route names instead of hardcoded URLs.
   ```php
   // Bad
   $url = '/users/' . $id;

   // Good
   $url = $router->generate('users.show', ['id' => $id]);
   ```

6. **Request Context**: Configure context if absolute URLs are needed.
   ```php
   $router->setContext(new RequestContext(
       baseUrl: '/myapp',
       scheme: 'https',
       host: 'example.com',
       httpPort: 80,
       httpsPort: 443
   ));
   ```




---

## Kernel Project

Lightweight Kernel Implementation with DI Container

# Lightweight Kernel Implementation with DI Container

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/kernel/main)
![CI Workflow](https://github.com/derafu/kernel/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/kernel)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/kernel)
![Total Downloads](https://poser.pugx.org/derafu/kernel/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/kernel/d/monthly)

A lightweight kernel implementation with a dependency injection container, inspired by Symfony but with a minimal approach.

## Overview

Derafu Kernel provides a clean, flexible foundation for PHP applications with minimal dependencies. It offers:

- A lightweight kernel implementation with DI container.
- Environment-aware configuration management.
- Support for PHP and YAML configuration files.
- Container caching for improved performance.
- Built-in support for multiple environments (dev, prod, test, etc.).

## Installation

```bash
composer require derafu/kernel
```

## Basic Usage

### Create a Kernel

The simplest way to use the kernel is to create an instance with a specific environment:

```php
use Derafu\Kernel\MicroKernel;

// Create a kernel with 'dev' environment and debug mode enabled.
$kernel = new MicroKernel('dev', true);

// Boot the kernel to initialize the container.
$kernel->boot();
```

### Custom Kernel Implementation

You can extend the `MicroKernel` class to customize its behavior:

```php
use Derafu\Kernel\MicroKernel;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

class AppKernel extends MicroKernel
{
    // Override the default configuration files.
    protected const CONFIG_FILES = [
        'services.php' => 'php',
        'routes.php' => 'routes',
        'parameters.yaml' => 'yaml',
    ];

    // Add additional container configuration.
    protected function configure(ContainerConfigurator $configurator): void
    {
        $services = $configurator->services();

        // Register application services.
        $services->set('app.service', MyService::class)
            ->public()
            ->args(['param1', 'param2']);
    }
}
```

### Environment Configuration

The kernel uses an environment object to determine settings and directories:

```php
use Derafu\Kernel\Environment;

// Create an environment with custom settings.
$environment = new Environment(
    'prod',                 // Environment name.
    false,                  // Debug mode.
    ['custom' => 'value']   // Context variables.
);

// Create a kernel with the custom environment.
$kernel = new MicroKernel($environment);
```

## Configuration

### Directory Structure

The kernel expects a `config` directory for configurations. Any other structure is free.

### Service Configuration

Define services in `config/services.php`:

```php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator) {
    $services = $configurator->services();

    // Auto-configure and autowire services by default.
    $services->defaults()
        ->autowire()
        ->autoconfigure();

    // Register a single service.
    $services->set('app.service', AppService::class)
        ->public();

    // Register multiple services from namespace.
    $services->load('App\\Service\\', '../src/Service/*')
        ->public();
};
```

### Route Configuration

Define routes in `config/routes.php` or `config/routes.yaml`:

```php
// routes.php
return [
    'home' => [
        'path' => '/',
        'controller' => 'App\\Controller\\HomeController::index',
    ],
    'blog_show' => [
        'path' => '/blog/{slug}',
        'controller' => 'App\\Controller\\BlogController::show',
        'parameters' => [
            'requirements' => [
                'slug' => '[a-z0-9-]+',
            ],
        ],
    ],
];
```

Or in YAML:

```yaml
# routes.yaml
home:
    path: /
    controller: App\Controller\HomeController::index

blog_show:
    path: /blog/{slug}
    controller: App\Controller\BlogController::show
    parameters:
        requirements:
            slug: '[a-z0-9-]+'
```

## Environment Types

The kernel supports multiple environment types through constants in `EnvironmentInterface`:

- `LOCAL`: Local development environment.
- `DEVELOPMENT`: Development environment.
- `TEST`: Testing environment.
- `STAGING`: Staging environment.
- `QUALITY_ASSURANCE`: QA environment.
- `PREPRODUCTION`: Pre-production environment.
- `PRODUCTION`: Production environment.




---

## Backbone Project

Derafu Backbone

# Derafu Backbone




---

### Introduction

The Architectural Spine for PHP Libraries

# The Architectural Spine for PHP Libraries

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/backbone/main)
![CI Workflow](https://github.com/derafu/backbone/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/backbone)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/backbone)
![Total Downloads](https://poser.pugx.org/derafu/backbone/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/backbone/d/monthly)

Derafu Backbone is a lightweight architectural framework that provides a consistent structure for building modular, maintainable PHP libraries.

## Features

- **Hierarchical Organization**: Clear structure with Packages, Components, and Workers.
- **Separation of Concerns**: Jobs for atomic operations, Handlers for orchestration, Strategies for implementation variants.
- **Attribute-Based Discovery**: Use PHP 8 attributes instead of rigid namespace conventions.
- **Extensible Architecture**: Designed to grow with your application.

## Key Benefits

- **Consistent Structure**: Standardized approach to organizing domain logic.
- **Reduced Complexity**: Clear responsibilities for each architectural element.
- **Improved Testability**: Isolated components are easier to test.
- **Enhanced Collaboration**: Common vocabulary and patterns for development teams.
- **Flexible Implementation**: Adapt to different domains without changing the core architecture.

## Installation

```bash
composer require derafu/backbone
```

## Quick Example

```php
#[Package(name: 'billing')]
class BillingPackage extends AbstractPackage implements PackageInterface
{
    // Package implementation.
}

#[Component(name: 'document', package: 'billing')]
class DocumentComponent extends AbstractComponent implements ComponentInterface
{
    // Component implementation.
}

#[Worker(name: 'renderer', component: 'document', package: 'billing')]
class RendererWorker extends AbstractWorker implements WorkerInterface
{
    // Worker implementation.
}
```




---

### Architecture

Architecture

# Architecture

Derafu Backbone provides a structured framework for building modular and maintainable PHP libraries. It follows a hierarchical organization that separates concerns into distinct components, making your code more organized, testable, and extensible.

{.w-75 .mx-auto}
![Derafu Backbone Core Architecture](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-architecture.svg)

### Package

**Definition**: A high-level container representing a complete domain or subdomain within your application.

**Responsibility**: Groups functionally related components that work together to provide domain-specific capabilities.

**Characteristics**:

- Represents a complete business domain (e.g., Billing, Accounting, Human Resources).
- Contains multiple components.
- Provides domain-wide configuration and services.
- Acts as the primary entry point for domain functionality.

**Examples**: `BillingPackage`, `AccountingPackage`, `HumanResourcesPackage`

### Component

**Definition**: A functional area or module within a domain package.

**Responsibility**: Groups workers that handle specific aspects of the domain.

**Characteristics**:

- Represents a distinct functional area within a domain.
- Contains multiple workers focused on related tasks.
- Provides component-specific configuration.
- Manages cross-cutting concerns within its functional area.

**Examples**: `DocumentComponent`, `ExchangeComponent`, `TradingPartiesComponent`

### Worker

**Definition**: Coordinator of business operations related to a specific aspect of functionality.

**Responsibility**: Exposes public methods that can be called by clients and coordinates Jobs, Handlers, and Strategies to perform work.

**Characteristics**:

- Acts as a facade for the underlying implementation.
- Exposes domain operations through public methods.
- Coordinates the execution of jobs and handlers.
- May implement simple operations directly.
- Delegates complex processing to handlers.

**Examples**: `BuilderWorker`, `RendererWorker`

### Job

**Definition**: An atomic, self-contained unit of work that performs a single operation.

**Responsibility**: Executes a specific task with clear inputs and outputs.

**Characteristics**:

- Focused on doing one thing well.
- Encapsulates a single operation.
- Has clear, well-defined inputs and outputs.
- Does not orchestrate other jobs.
- Reusable across different contexts.
- Stateless and idempotent when possible.

**Examples**: `NormalizeBoletaAfectaJob`, `NormalizeFacturaAfectaJob`

### Handler

**Definition**: Orchestrator of complex processes involving multiple operations.

**Responsibility**: Coordinates multiple jobs or strategies to complete complex workflows.

**Characteristics**:

- Orchestrates multiple operations in sequence.
- Manages workflow and process state.
- Selects appropriate strategies based on context.
- Handles errors and transactional boundaries.
- Implements business process logic.
- Can use multiple jobs and strategies.

**Examples**: `EmailSenderHandler`, `SiiSenderHandler`

### Strategy

**Definition**: Specific implementation of an algorithm or approach to solving a problem.

**Responsibility**: Provides variant implementations for specific operations that can be interchanged.

**Characteristics**:

- Implements a specific algorithm or approach.
- Allows for swappable implementations.
- Used by handlers to provide different behaviors.
- Focuses on "how" something is done.
- Follows the Strategy design pattern.
- Encapsulates specific implementation details.

**Examples**: `JsonParserStrategy`, `XmlParserStrategy`, `YamlParserStrategy`

## Benefits of This Architecture

1. **Separation of Concerns**: Each component has a clear, single responsibility.
2. **Modularity**: Components can be developed, tested, and deployed independently.
3. **Extensibility**: New implementations can be added without modifying existing code.
4. **Testability**: Clear boundaries make testing easier and more focused.
5. **Maintainability**: Organized structure makes the codebase easier to understand and maintain.
6. **Flexibility**: Strategies allow for varying implementations without changing coordination logic.

## Design Pattern Comparisons

- **Jobs**: Similar to the Command Pattern.
- **Handlers**: Combination of Chain of Responsibility and Mediator patterns.
- **Strategies**: Direct implementation of the Strategy Pattern.
- **Workers**: Follow the Facade Pattern.
- **Overall Structure**: Influenced by Hexagonal/Ports and Adapters Architecture.

This architecture provides a clear separation of responsibilities, allowing for component reuse and making your system more adaptable to changing requirements.




---

### Relationships

Relationships and Interactions

# Relationships and Interactions

{.w-50 .mx-auto}
![Derafu Backbone Relationships](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-relationships.svg)

## Package → Component Relationship

- A Package contains multiple Components.
- Components within a Package are thematically related.
- Components access Package-level configuration and services.

## Component → Worker Relationship

- A Component contains multiple Workers.
- Workers are grouped logically within a Component.
- Workers share Component-level resources and configuration.

## Worker → Job/Handler/Strategy Relationship

- Workers expose public methods that can be called by clients.
- Workers delegate to Jobs for simple operations.
- Workers delegate to Handlers for complex workflows.
- Workers don't typically interact directly with Strategies (Handlers do).

## Handler → Job/Strategy Relationship

- Handlers coordinate the execution of multiple Jobs.
- Handlers select and use appropriate Strategies based on context.
- Handlers implement orchestration logic while Jobs and Strategies provide implementation.

## Strategy Relationships

- Strategies implement interchangeable algorithms.
- Handlers select appropriate Strategies based on conditions.
- Strategies focus on specific implementation details.




---

### Workflow

Typical Workflow

# Typical Workflow

{.w-75 .mx-auto}
![Derafu Backbone Workflow](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-workflow.svg)

1. A client interacts with a public method on a Worker.
2. The Worker can:
   - Execute simple logic internally.
   - Delegate to a Job for a specific task.
   - Delegate to a Handler for a complex process.

3. If a Handler is used:
   - The Handler coordinates the workflow.
   - May execute multiple Jobs in sequence.
   - May select different Strategies based on context.
   - Manages errors and transactions.

4. Strategies allow for varying the implementation of specific steps without changing the Handler's logic.




---

### Decision Flow

Decision Flow: Choosing the Right Component

# Decision Flow: Choosing the Right Component

This document expands on the Decision Flow Diagram, helping you understand when to use each architectural component in Derafu Backbone.

{.w-75 .mx-auto}
![Decision Flow](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-decision-flow.svg)

## Understanding the Decision Process

When implementing a new piece of functionality in Derafu Backbone, one of the most important decisions is determining which architectural component should handle that functionality. The diagram provides a decision tree to guide this process, but let's explore the reasoning and implications of each choice.

### When to Use Jobs

Jobs are the workhorses of Backbone architecture. You should choose a Job when:

- The operation performs a **single, well-defined task**
- The operation has **clear inputs and outputs**
- The operation doesn't need to manage complex flows or state
- The operation could potentially be reused in different contexts

Jobs are particularly valuable when you need to implement operations that might be used by multiple handlers or directly by workers. They represent atomic units of work that should follow the Single Responsibility Principle.

**Example scenarios for Jobs**:
- Validating input data
- Sending a notification
- Storing an entity in a repository
- Transforming data from one format to another
- Performing a calculation

### When to Use Handlers

Handlers should be your choice when:

- The operation involves **multiple steps** or jobs
- You need to **orchestrate a complex workflow**
- There's **conditional logic** determining the flow
- The operation manages **transactional boundaries**
- You need to **coordinate between different components**

Handlers encapsulate complex business processes and provide a higher level of abstraction. They know how to execute a complete business use case by coordinating the execution of multiple jobs and selecting appropriate strategies.

**Example scenarios for Handlers**:
- Processing a payment (validating, charging, recording transaction, sending receipt)
- Generating a report (gathering data, applying business rules, formatting, delivering)
- User registration flow (validating, creating account, sending welcome email, initializing user settings)

### When to Use Strategies

Strategies are the right choice when:

- You need **multiple implementations** of the same operation
- The implementation should be **selectable at runtime**
- The implementation choice depends on **context or configuration**
- You want to **eliminate conditional logic** from your handlers and jobs

Strategies allow your system to adapt to different circumstances without changing the orchestration logic. They encapsulate the "how" of an operation, while jobs and handlers focus on the "what".

**Example scenarios for Strategies**:
- Different export formats (PDF, CSV, Excel)
- Multiple payment processors (Stripe, PayPal, Bank Transfer)
- Various notification channels (Email, SMS, Push Notification)
- Different storage backends (File System, S3, Database)

### When to Use Direct Worker Implementation

In some cases, you might implement functionality directly in the Worker:

- For very simple operations that don't warrant a separate Job
- For operations that are specific to a particular Worker and won't be reused
- When acting as a simple facade over third-party libraries
- For convenience methods that combine calls to Jobs or Handlers

## Practical Applications

### Component Relationships

Notice how Jobs and Strategies are often used by Handlers. This relationship is key to understanding the architecture:

- **Jobs** provide the atomic operations
- **Handlers** orchestrate these operations
- **Strategies** provide implementation variants

### Benefits of Following This Decision Flow

By correctly choosing the appropriate architectural component:

1. **Improved Testability**: Jobs and Strategies are easier to test in isolation.
2. **Enhanced Maintainability**: Clear separation of concerns makes the code more maintainable.
3. **Greater Flexibility**: Strategies enable system adaptability without widespread changes.
4. **Better Reusability**: Jobs can be reused across multiple contexts.
5. **Clearer Intent**: The architecture communicates the intent of each piece of code.

### Edge Cases and Considerations

- **Size and Complexity**: Very simple applications might not need the full hierarchy. Start with Jobs and add Handlers and Strategies as complexity grows.
- **Performance**: While this architecture promotes good design, be mindful of potential overhead from excessive layering in performance-critical paths.
- **Boundaries**: Consider your domain boundaries carefully when organizing packages and components.

By following this decision flow, you can create a clean, maintainable, and adaptable codebase that effectively leverages the full potential of Derafu Backbone's architecture.




---

### Component Interaction

Component Interaction Sequence

# Component Interaction Sequence

This document explores how the various components of Derafu Backbone interact during typical operations, providing insight into the architectural flow and communication patterns.

{.w-100 .mx-auto}
![Sequence Diagram](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-component-interaction.svg)

## The Flow of Control

The sequence diagram illustrates the typical flow of control when using Derafu Backbone for a business operation. Understanding this flow is crucial for effectively working with the architecture and designing new components.

### 1. Entry Point: The Registry

All interaction with a Backbone-based system typically begins with the Package Registry. This is the service locator that provides access to the domain packages in your application. The Package Registry serves as the entry point into your domain architecture.

```php
// Obtaining the package registry (typically from a kernel or container).
$packageRegistry = $container->get(PackageRegistryInterface::class);
```

The Package Registry is responsible for:

- Maintaining references to all registered packages.
- Providing type-safe access to specific packages.
- Acting as the gateway to your domain architecture.

### 2. Accessing a Package

After obtaining the registry, the client accesses a specific domain package:

```php
// Get a specific package by name.
$billingPackage = $packageRegistry->getPackage('billing');
// Or using a type-safe helper method.
$billingPackage = $packageRegistry->getBillingPackage();
```

Packages represent complete domains or subdomains in your application. They contain all components related to a specific business area. The clean organization of packages helps maintain separation between different domains.

### 3. Accessing a Component

From a package, the client accesses a specific component:

```php
// Access a component within the package.
$invoiceComponent = $billingPackage->getComponent('invoice');
// Or using a type-safe helper method.
$invoiceComponent = $billingPackage->getInvoiceComponent();
```

Components group related functionality within a domain. They represent functional areas within your domain and contain workers that handle specific aspects of that functionality.

### 4. Accessing a Worker

From a component, the client accesses a specific worker:

```php
// Access a worker within the component.
$generatorWorker = $invoiceComponent->getWorker('generator');
// Or using a type-safe helper method.
$generatorWorker = $invoiceComponent->getGeneratorWorker();
```

Workers are the coordinators that expose domain operations through public methods. They manage jobs and handlers to perform specific tasks within a component.

### 5. Using Jobs or Handlers

Finally, the client accesses and executes a job or handler:

```php
// Using a job.
$invoice = $generatorWorker->getCreateJob()->execute($data);

// Or using a handler.
$result = $generatorWorker->getProcessHandler()->handle($invoice, $options);
```

Jobs and handlers do the actual work in the system. Jobs perform atomic operations, while handlers orchestrate complex processes that might involve multiple jobs and strategies.

## Direct Access vs. Hierarchical Access

While the diagram shows a step-by-step hierarchical flow, it's important to note that once a client has obtained the registry, it can access any level directly:

```php
// Hierarchical access (step by step).
$invoice = $packageRegistry
    ->getBillingPackage()
    ->getInvoiceComponent()
    ->getGeneratorWorker()
    ->getCreateJob()
    ->execute($data);

// Direct access (if you already have a reference to the worker).
$invoice = $generatorWorker->getCreateJob()->execute($data);
```

Both approaches are valid, but the hierarchical access pattern is generally recommended for application code as it:

- Makes the dependency hierarchy explicit.
- Follows a natural discovery pattern.
- Makes the code more readable and self-documenting.

The direct access pattern can be useful in:

- Unit tests where you want to focus on testing a specific component.
- Performance-critical paths where you can cache references to frequently used services.
- Situations where you already have a reference to a higher-level component.

## Alternative Path: Using Handlers

For more complex operations, handlers provide an alternative path:

```php
// Using a handler for complex operations.
$result = $generatorWorker->getProcessHandler()->handle($invoice, $options);
```

Handlers orchestrate complex workflows and can:

- Execute multiple jobs in sequence.
- Apply conditional logic.
- Select appropriate strategies based on input or configuration.
- Manage transactional boundaries.
- Handle cross-cutting concerns like logging or error handling.

## Communication Patterns

The diagram illustrates several important communication patterns in Backbone:

1. **Hierarchical Organization**: Components are organized in a clear hierarchy that reflects your domain structure.
2. **Dependency Injection**: Components receive their dependencies through constructor injection.
3. **Lazy Loading**: Services are typically loaded lazily, meaning they're only instantiated when needed.
4. **Interface-Based Programming**: Communication happens through well-defined interfaces.

## Performance Considerations

The hierarchical structure of Backbone might raise concerns about performance overhead. However, several aspects mitigate this:

1. **Lazy Loading**: Services are loaded only when needed.
2. **Cached References**: In performance-critical paths, you can cache references to frequently used services.
3. **DI Container Optimization**: Modern DI containers can optimize service instantiation.
4. **Proxy Generation**: Backbone can use proxies to further optimize lazy loading.

By understanding these interaction patterns, you can effectively design, implement, and use components within Derafu Backbone to create maintainable and extensible applications.




---

### Configuration Layers

Configuration Layers

# Configuration Layers

This document explores how configuration cascades through the architectural layers in Derafu Backbone, providing a powerful and flexible way to configure your application.

{.w-75 .mx-auto}
![Configuration Layers](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-configuration-layers.svg)

## Configuration Hierarchy

Derafu Backbone implements a hierarchical configuration system that follows the same structure as the architectural components. This cascade system allows for powerful customization while maintaining sensible defaults.

### Package Configuration

At the top of the hierarchy is the Package configuration, which provides the foundation for all configuration within a domain:

```yaml
# Example package configuration.
example_package:
  options:
    debug: false
    cache_enabled: true
  components:
    example_component:
      # Component-specific configuration.
    another_component:
      # Another component's configuration.
```

Package configuration is ideal for:

- Domain-wide settings that affect all components.
- Default values that components can override.
- Shared service configuration.
- Environment-specific settings for an entire domain.
- Feature flags that affect the entire package.

The Package configuration establishes the baseline for all contained components.

### Component Configuration

The Component configuration provides more specific settings for a functional area within a package:

```yaml
# Component configuration within a package.
example_package:
  components:
    example_component:
      options:
        timeout: 30
        max_retries: 3
      workers:
        example_worker:
          # Worker-specific configuration.
        another_worker:
          # Another worker's configuration.
```

Component configuration is appropriate for:

- Feature-specific settings.
- Overriding package defaults for a specific component.
- API keys or endpoints for external services used by the component.
- Component-specific validation rules or constraints.
- Logging or monitoring settings for a component.

Component configuration inherits from the package level but can override any setting as needed.

### Worker Configuration

Worker configuration provides even more specific settings for individual workers within a component:

```yaml
# Worker configuration within a component
example_package:
  components:
    example_component:
      workers:
        example_worker:
          options:
            batch_size: 100
            processing_mode: "async"
          jobs:
            # Job-specific configuration
          handlers:
            # Handler-specific configuration
```

Worker configuration is useful for:

- Task-specific settings.
- Overriding component defaults for a specific worker.
- Performance tuning parameters.
- Feature flags for specific functionality.
- Worker-specific thresholds or limits.

Worker configuration inherits from both the package and component levels.

### Job/Handler/Strategy Configuration

At the lowest level, individual jobs, handlers, and strategies can have their own configuration:

```yaml
# Job configuration within a worker
example_package:
  components:
    example_component:
      workers:
        example_worker:
          jobs:
            example_job:
              options:
                validation_level: "strict"
                timeout: 10
```

This level of configuration is ideal for:

- Operation-specific settings.
- Fine-grained control over individual operations.
- Feature flags for specific functionality.
- Operation-specific thresholds or limits.

## Accessing Configuration

Derafu Backbone provides a consistent way to access configuration at any level through the `ConfigurableInterface` and the `ConfigurableTrait`:

```php
// Inside a package, component, or worker.
$config = $this->getConfiguration();

// Accessing specific options.
$debug = $config->get('options.debug', false); // With default value.
$timeout = $config->get('options.timeout'); // Without default.

// Accessing nested configuration.
$workerConfig = $config->get('workers.example_worker');
```

The configuration system is designed to be:

- **Type-safe**: Configurations can be defined with schemas for validation.
- **Environment-aware**: Different configurations can be loaded based on the environment.
- **Hierarchical**: Configurations cascade from more general to more specific.
- **Defaulted**: Sensible defaults can be provided at any level.

## Configuration Inheritance Mechanism

The key benefit of Backbone's layered configuration is inheritance:

1. **Default Values**: Each layer can provide default values that are used if not overridden.
2. **Selective Overrides**: Lower levels can override specific settings without affecting others.
3. **Aggregation**: Configuration is aggregated from all levels before being used.

For example, if you have these configurations:

```yaml
# Package level.
example_package:
  options:
    debug: false
    cache_enabled: true
    timeout: 30

# Component level (in the same file).
example_package:
  components:
    example_component:
      options:
        timeout: 60
```

Then, when accessing configuration from within `ExampleComponent`:

```php
$config = $this->getConfiguration();
$debug = $config->get('options.debug'); // false (inherited from package)
$cacheEnabled = $config->get('options.cache_enabled'); // true (inherited from package)
$timeout = $config->get('options.timeout'); // 60 (overridden at component level)
```

## Best Practices for Configuration Management

When working with Backbone's configuration layers:

1. **Define defaults at the highest appropriate level**: Place configuration that applies broadly at the package level.
2. **Override only what's necessary**: Only override configuration when you need to change it.
3. **Be explicit about types and validation**: Use configuration schemas to validate configuration.
4. **Use environment-specific configuration**: Leverage environment variables and profiles for environment-specific settings.
5. **Document your configuration**: Clearly document what configuration options are available and what they do.
6. **Keep sensitive information separate**: Use environment variables or dedicated configuration stores for secrets.

By understanding and effectively using Backbone's configuration layers, you can create flexible, configurable applications that are easy to adapt to different environments and use cases.




---

### Service Lifecycle

Service Lifecycle

# Service Lifecycle

This document explains the lifecycle of services within Derafu Backbone, from definition to usage, providing insights into how services are discovered, configured, and instantiated.

{.w-75 .mx-auto}
![Service Lifecycle](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-service-lifecycle.svg)

## Three-Phase Lifecycle

Derafu Backbone services go through three distinct phases during their lifecycle:

1. **Definition Phase**: How services are defined in code.
2. **Discovery Phase**: How services are discovered and registered.
3. **Usage Phase**: How services are instantiated and used.

Understanding this lifecycle is crucial for developing with Backbone and troubleshooting any issues that may arise.

## 1. Definition Phase

The definition phase is where you define your Backbone services in code.

### Class Definition with PHP 8 Attributes

The cornerstone of Backbone's service definition is PHP 8 attributes. These attributes provide metadata about your services and eliminate the need for verbose configuration:

```php
#[Package(name: 'billing', description: 'Handles billing operations')]
class BillingPackage extends AbstractPackage implements PackageInterface
{
    // Package implementation.
}

#[Component(name: 'document', package: 'billing')]
class DocumentComponent extends AbstractComponent implements ComponentInterface
{
    // Component implementation.
}

#[Worker(name: 'renderer', component: 'document', package: 'billing')]
class RendererWorker extends AbstractWorker implements WorkerInterface
{
    // Worker implementation
}
```

The attributes provide several key pieces of information:
- **Service type**: Package, Component, Worker, Job, Handler, or Strategy
- **Service name**: The identifier used to reference the service
- **Service hierarchy**: The parent services (package, component, worker)
- **Description**: Optional description for better documentation

### Abstract Base Classes and Interfaces

All Backbone services extend abstract base classes and implement interfaces:

- **Abstract classes** provide common functionality like configuration handling, ID generation, and standardized constructors.
- **Interfaces** define the contract that each service must fulfill.

This combination ensures consistent behavior and makes services interchangeable and testable.

### Dependency Injection

Services declare their dependencies through constructor injection:

```php
#[Component(name: 'document', package: 'billing')]
class DocumentComponent extends AbstractComponent implements ComponentInterface
{
    public function __construct(
        private readonly BuilderWorker $builderWorker,
        private readonly RendererWorker $rendererWorker
    ) {
    }

    public function getWorkers(): array
    {
        return [
            'builder' => $this->builderWorker,
            'renderer' => $this->rendererWorker,
        ];
    }

    // Other component implementation.
    // It's recommended to create getters for the dependencies. This will
    // provide safe type hinting and autocompletion.
}
```

This explicit declaration of dependencies:

- Makes dependencies clear and traceable.
- Facilitates testing through mocking.
- Allows the DI container to resolve dependencies automatically.
- Ensures services are properly initialized.

## 2. Discovery Phase

The discovery phase is where defined services are found, processed, and registered in the dependency injection container.

### Compiler Passes

Backbone uses Symfony's compiler passes to discover and process services:

#### ServiceProcessingCompilerPass

This compiler pass:

1. Scans all service definitions in the container.
2. Identifies classes with Backbone attributes.
3. Extracts metadata from attributes.
4. Creates and registers service definitions.
5. Adds appropriate tags for later reference.
6. Mark all services as lazy services.
7. Mark only packages as public services.

The result is that all Backbone services are properly registered in the container, with appropriate tags and metadata.

#### ServiceConfigurationCompilerPass

This compiler pass:
1. Finds services that implement `ConfigurableInterface`.
2. Matches them with configuration from parameters.
3. Adds method calls to set configuration when the service is created.

This ensures that services receive their configuration during instantiation.

### Registration and Aliasing

During the discovery phase, services are registered in the container and aliased for easier access:

```php
// Original service ID (class name).
App\Billing\DocumentComponent

// Aliased as (from attribute metadata).
billing.document
```

These aliases make it easier to reference services by their logical names rather than class names.

## 3. Usage Phase

The usage phase is where services are actually instantiated and used at runtime.

### Lazy Loading

By default, Backbone services are registered as lazy services. This means:

- They're only instantiated when actually needed.
- A proxy is created that loads the real service on first method call.
- This improves performance by avoiding unnecessary service instantiation.

### Accessing Services

Services can be accessed through the Package Registry:

```php
// Get a package from the registry.
$billingPackage = $packageRegistry->getPackage('billing');

// Get a component from the package.
$documentComponent = $billingPackage->getComponent('document');

// Get a worker from the component.
$rendererWorker = $documentComponent->getWorker('renderer');

// Use the worker.
$pdf = $rendererWorker->render($data);
```

Each level in the hierarchy provides access to the level below it, creating a discoverable API.

### Configuration Application

When a service is instantiated:

1. The container resolves its dependencies.
2. Dependencies are injected via the constructor.
3. Configuration is applied via a method call (if the service is configurable).
4. The service is ready to use.

This ensures that services are fully initialized before use.

## Understanding the Flow

The complete flow from definition to usage:

1. **Define** services using PHP 8 attributes.
2. **Compile** the container, triggering discovery and registration.
3. **Build** the container for runtime use.
4. **Access** services through the registry.
5. **Use** services to perform domain operations.

## Benefits of This Lifecycle

This lifecycle approach provides several benefits:

1. **Discoverability**: Services are easily discoverable through attributes.
2. **Configuration**: Services receive appropriate configuration automatically.
3. **Lazy Loading**: Only services that are actually used are instantiated.
4. **Type Safety**: The full hierarchy is type-safe through interfaces.
5. **Testability**: Dependencies are explicit and can be mocked for testing.

## Troubleshooting the Lifecycle

Common issues and how to address them:

1. **Service not found**: Ensure attributes are correctly defined and the compiler pass is registered.
2. **Configuration not applied**: Check that your configuration keys match the expected structure.
3. **Dependencies not resolved**: Verify that all dependencies are correctly registered in the container.
4. **Performance issues**: Consider caching the compiled container in production.

By understanding the complete service lifecycle in Derafu Backbone, you can effectively develop, configure, and troubleshoot your application.




---

### Design Patterns

Backbone and Design Patterns

# Backbone and Design Patterns

This document explores how Derafu Backbone implements and leverages established design patterns to create a robust, maintainable architecture for PHP applications.

{.w-50 .mx-auto}
![Design Patterns](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-design-patterns.svg)

## Design Patterns in Backbone

Derafu Backbone draws inspiration from several well-established design patterns. Understanding these patterns and their implementation in Backbone helps developers use the framework effectively and extend it appropriately.

## Jobs and the Command Pattern

Jobs in Backbone are a direct implementation of the Command Pattern.

### Command Pattern Overview

The Command Pattern encapsulates a request as an object, allowing:

- Parameterization of clients with different requests.
- Queueing of requests.
- Logging of requests.
- Support for undoable operations.

### How Jobs Implement Command

Jobs in Backbone embody these principles:

- Each job is a class that encapsulates a single operation.
- Jobs have a standardized execution method (`execute()`).
- Jobs can be parameterized through their execute method.
- Jobs are self-contained and can be invoked by various clients.

```php
#[Job(name: 'create', worker: 'generator', component: 'invoice', package: 'billing')]
class CreateInvoiceJob extends AbstractJob implements JobInterface
{
    public function execute(array $data): Invoice
    {
        // Validate input.
        $this->validateInput($data);

        // Create invoice
        $invoice = new Invoice();
        $invoice->setCustomer($data['customer']);
        $invoice->setItems($data['items']);

        // Return result.
        return $invoice;
    }

    private function validateInput(array $data): void
    {
        // Validation logic.
    }
}
```

### Benefits of the Command Pattern in Jobs

This implementation provides several advantages:

- **Single Responsibility**: Each job has a clear, specific purpose.
- **Reusability**: Jobs can be reused in different contexts.
- **Testability**: Jobs are easy to test in isolation.
- **Extensibility**: New jobs can be added without modifying existing code.
- **Queueability**: Jobs can be serialized and queued for asynchronous processing.

## Handlers and the Mediator/Chain of Responsibility Patterns

Handlers in Backbone combine aspects of both the Mediator and Chain of Responsibility patterns.

### Mediator Pattern Overview

The Mediator Pattern defines an object that encapsulates how a set of objects interact, promoting loose coupling by preventing objects from referring to each other explicitly.

### Chain of Responsibility Overview

The Chain of Responsibility Pattern passes a request along a chain of handlers, with each handler deciding either to process the request or pass it to the next handler.

### How Handlers Implement These Patterns

Handlers in Backbone combine these concepts:

- They coordinate interactions between multiple Jobs (Mediator).
- They orchestrate a sequence of operations (Chain of Responsibility).
- They encapsulate complex workflows.

```php
#[Handler(name: 'process', worker: 'processor', component: 'invoice', package: 'billing')]
class ProcessInvoiceHandler extends AbstractHandler implements HandlerInterface
{
    public function handle(Invoice $invoice, array $options = []): Result
    {
        // Validate the invoice.
        $validationResult = $this->getJob('validate')->execute($invoice);
        if (!$validationResult->isValid()) {
            return Result::failure($validationResult->getErrors());
        }

        // Determine processing strategy.
        $strategyName = $options['strategy'] ?? 'default';
        $strategy = $this->getStrategy($strategyName);

        // Process the invoice.
        $processingResult = $strategy->process($invoice);
        if (!$processingResult->isSuccessful()) {
            return Result::failure($processingResult->getErrors());
        }

        // Send notifications.
        $this->getJob('notify')->execute($invoice, $options['notifications'] ?? []);

        // Return success.
        return Result::success(['invoice' => $invoice, 'processed' => true]);
    }
}
```

### Benefits of These Patterns in Handlers

This implementation provides several advantages:

- **Decoupling**: Components don't need to know about each other.
- **Centralized Control**: Complex workflows are managed in a single place.
- **Flexibility**: Processing steps can be changed without affecting clients.
- **Transactional Boundaries**: Handlers can manage transactions across multiple operations.
- **Error Handling**: Centralized error handling for multi-step processes.

## Strategies and the Strategy Pattern

Strategies in Backbone are a direct implementation of the Strategy Pattern.

### Strategy Pattern Overview

The Strategy Pattern defines a family of algorithms, encapsulates each one, and makes them interchangeable. It lets the algorithm vary independently from clients that use it.

### How Strategies Implement the Pattern

Strategies in Backbone embody these principles:

- They provide alternative implementations of an algorithm.
- They share a common interface.
- They can be selected and switched at runtime.

```php
#[Strategy(name: 'pdf', worker: 'renderer', component: 'document', package: 'billing')]
class PdfRenderStrategy extends AbstractStrategy implements RenderStrategyInterface
{
    public function render(Document $document): string
    {
        // PDF rendering implementation.
        return $this->pdfRenderer->renderDocument($document);
    }
}

#[Strategy(name: 'html', worker: 'renderer', component: 'document', package: 'billing')]
class HtmlRenderStrategy extends AbstractStrategy implements RenderStrategyInterface
{
    public function render(Document $document): string
    {
        // HTML rendering implementation.
        return $this->htmlRenderer->renderDocument($document);
    }
}
```

### Benefits of the Strategy Pattern

This implementation provides several advantages:

- **Encapsulation**: Different algorithms are encapsulated in separate classes.
- **Interchangeability**: Strategies can be swapped without changing client code.
- **Elimination of Conditionals**: Complex conditional logic is replaced with polymorphism.
- **Runtime Selection**: Algorithms can be selected based on runtime conditions.
- **Testability**: Each strategy can be tested independently.

## Workers and the Facade Pattern

Workers in Backbone implement the Facade Pattern.

### Facade Pattern Overview

The Facade Pattern provides a unified interface to a set of interfaces in a subsystem. It defines a higher-level interface that makes the subsystem easier to use.

### How Workers Implement the Facade

Workers in Backbone act as facades:

- They provide a simplified interface to complex subsystems.
- They handle the complexity of coordinating jobs, handlers, and strategies.
- They expose domain operations through a clean API.

```php
#[Worker(name: 'processor', component: 'invoice', package: 'billing')]
class InvoiceProcessorWorker extends AbstractWorker implements WorkerInterface
{
    // This method is part of the public API.
    public function processInvoice(Invoice $invoice, array $options = []): Result
    {
        // Delegate to the appropriate handler.
        return $this->getHandler('process')->handle($invoice, $options);
    }

    // Another public API method.
    public function validateInvoice(Invoice $invoice): ValidationResult
    {
        // Delegate to a job.
        return $this->getJob('validate')->execute($invoice);
    }
}
```

### Benefits of the Facade Pattern in Workers

This implementation provides several advantages:

- **Simplified Interface**: Clients interact with a clean, focused API.
- **Reduced Coupling**: Clients don't need to know about the subsystem's components.
- **Unified Entry Point**: Workers provide a single entry point to related functionality.
- **Abstraction**: Implementation details are hidden behind the facade.

## Hexagonal Architecture Influence

The overall architecture of Backbone is inspired by Hexagonal Architecture (also known as Ports and Adapters).

### Hexagonal Architecture Overview

Hexagonal Architecture aims to create loosely coupled application components that can be easily connected to their software environment by means of ports and adapters.

### How Backbone Implements Hexagonal Concepts

Backbone incorporates these principles:

- **Domain-Centric**: The architecture focuses on domain logic.
- **Ports**: Interfaces define how components interact.
- **Adapters**: Implementations connect the domain to external systems.
- **Inversion of Control**: Dependencies point inward toward the domain.

The Package-Component-Worker structure creates clear boundaries within the domain, while Strategies often serve as adapters to external systems.

## Practical Application

When applying these design patterns in your Backbone applications:

1. **Identify the Pattern**: Recognize which pattern applies to your situation.
2. **Follow the Template**: Use the appropriate Backbone component.
3. **Respect the Boundaries**: Maintain separation between different components.
4. **Leverage Polymorphism**: Use strategies for variant implementations.
5. **Focus on Composition**: Prefer composition over inheritance.

By understanding and applying these design patterns within Backbone, you can create well-structured, maintainable applications that are flexible enough to adapt to changing requirements.




---

### File Structure

Recommended File Structure for Projects

# Recommended File Structure for Projects

This document provides guidelines for organizing your code in Derafu Backbone projects, explaining the rationale behind the recommended structure and best practices for maintaining a clean, maintainable codebase.

{.w-75 .mx-auto}
![File Structure](https://www.derafu.dev/img/diagrams/content/docs/core/backbone/derafu-backbone-file-structure.svg)

## Domain-First Organization

Derafu Backbone encourages a domain-first approach to organizing your codebase. This means that the primary organizing principle is the business domain, not technical concerns.

### Root Structure

A typical Backbone project is organized as follows:

```
src/
├── Domain1/
├── Domain2/
├── Domain3/
└── Registry.php
config/
└── services.yaml
```

This structure puts domains at the forefront, making it immediately clear what business capabilities your application provides.

## Domain Structure

Each domain (represented by a Package) follows a consistent internal structure:

```
Domain/
├── DomainPackage.php
├── Component/
│   ├── Component1.php
│   └── Component2.php
├── Model/
│   ├── Model1.php
│   └── Model2.php
└── Exception/
    └── DomainException.php
```

### Key Elements

- **DomainPackage.php**: The package class that serves as the entry point to the domain
- **Component/**: Directory containing all components of this domain
- **Model/**: Directory containing domain models (entities, value objects, etc.)
- **Exception/**: Domain-specific exceptions

## Component Structure

Each component has its own structure that houses its workers and related classes:

```
Component/
├── Component.php
└── Worker/
    ├── Worker1.php
    ├── Worker2.php
    ├── Job/
    │   ├── Job1.php
    │   └── Job2.php
    ├── Handler/
    │   ├── Handler1.php
    │   └── Handler2.php
    └── Strategy/
        ├── Strategy1.php
        └── Strategy2.php
```

### Key Elements

- **Component.php**: The component class that serves as the entry point to this functional area
- **Worker/**: Directory containing workers and their related classes
- **Job/**: Directory containing jobs used by workers
- **Handler/**: Directory containing handlers used by workers
- **Strategy/**: Directory containing strategies used by handlers and jobs

## Namespacing

The file structure directly corresponds to the namespace structure, following PSR-4 autoloading standards:

```php
// DomainPackage.php
namespace App\Domain;

// Component.php
namespace App\Domain\Component;

// Worker.php
namespace App\Domain\Component\Worker;

// Job.php
namespace App\Domain\Component\Worker\Job;
```

This clear correspondence between namespaces and directories makes it easy to locate files and understand their role in the architecture.

## The Benefits of This Structure

### 1. Domain Discovery

The domain-first structure makes it easy to discover what domains your application handles. New team members can quickly understand the application's purpose by examining the top-level directories.

### 2. Component Cohesion

By grouping related components within a domain, the structure promotes cohesion. Classes that work together are located near each other, making it easier to understand and modify related functionality.

### 3. Clear Dependencies

The hierarchical structure reflects the dependency hierarchy in Backbone, making it clear how components relate to each other.

### 4. Consistent Navigation

Once familiar with the structure, developers can quickly navigate to any part of the codebase, even in unfamiliar domains, because the pattern is consistent.

### 5. Scalable Organization

The structure scales well from small applications to large enterprise systems. As your application grows, you can add new domains without restructuring existing code.

## Best Practices

### Naming Conventions

Adopting consistent naming conventions enhances the clarity of your codebase:

- **Packages**: Use singular nouns (e.g., `Billing`, not `Bills`).
- **Components**: Use singular nouns that describe their functionality (e.g., `Document`, `Exchange`).
- **Workers**: Use a noun followed by "Worker" (e.g., `BuilderWorker`, `RendererWorker`).
- **Jobs**: Use a verb in the imperative followed by a noun (e.g., `CreateInvoice`, `SendNotification`).
- **Handlers**: Use a verb in the imperative followed by a noun and "Handler" (e.g., `ProcessPaymentHandler`).
- **Strategies**: Use a descriptive adjective or noun followed by the purpose and "Strategy" (e.g., `PdfRenderStrategy`, `StripePaymentStrategy`).

### File Organization Tips

1. **Group Related Files**: Keep files that are likely to change together in the same directory.
2. **Domain Boundaries**: Be careful about cross-domain dependencies. If components in different domains need to communicate, consider defining interfaces.
3. **Package Size**: If a package grows too large (more than 7-10 components), consider splitting it into multiple packages.
4. **Shared Code**: Place shared code that's used across multiple domains in a separate `Shared` or `Common` package.
5. **Infrastructure Code**: Place infrastructure concerns (like database access, HTTP clients, etc.) in appropriate domains rather than in a separate "infrastructure" layer.

### Exception Hierarchy

Match your exception hierarchy to your package/component hierarchy:

```
Exception/
├── DomainException.php (base exception for the domain).
├── ComponentException.php (base exception for a component).
├── SpecificException1.php (specific exception type).
└── SpecificException2.php (specific exception type).
```

This makes error handling more consistent and helps identify the source of exceptions.

## Real-World Adaptations

While the recommended structure provides a solid foundation, you may need to adapt it to your specific needs.

### Microservice Adaptations

In a microservice architecture, each service might represent a single domain or even a single component:

```
services/
├── billing-service/
│   └── src/
│       └── Billing/
└── customer-service/
    └── src/
        └── Customer/
```

### Legacy Integration Adaptations

When integrating with legacy systems, you might need a different structure for adapter code:

```
src/
├── Domain/
│   └── ...
└── Legacy/
    └── Adapter/
        └── ...
```

### Infrastructure Concerns

For complex applications, you might introduce additional directories for infrastructure concerns:

```
src/
├── Domain/
├── Infrastructure/
│   ├── Database/
│   ├── Queue/
│   └── Cache/
└── Registry.php
```

However, try to keep these separate from your domain logic and limit dependencies on them from your domain code.

## Conclusion

The recommended file structure for Derafu Backbone projects emphasizes domain-driven organization, consistent patterns, and clear separation of concerns. By following these guidelines, you can create codebases that are easy to navigate, maintain, and extend, regardless of the size or complexity of your application.

Remember that the structure should serve your team and your application's needs. While consistency is important, don't be afraid to adapt the recommended structure when necessary to better suit your specific context.




---

### Operations

Marking Real Operations: `#[Operation]`

# Marking Real Operations: `#[Operation]`

A `Worker`'s public methods are ordinary PHP methods — but not all of them are business logic. Trait helpers (`JobsAwareTrait`/`HandlersAwareTrait`/`OptionsAwareTrait`) and `ServiceInterface` itself (`getId()`, `getName()`, `getDescription()`) contribute public methods too, and reflection alone cannot tell those apart from a worker's genuine capabilities. `#[Operation]` is the explicit signal that draws that line: tag a method with it, and any consumer — an allow-list policy, generated documentation, anything else that needs to enumerate what a worker can really do — has a reliable answer instead of a guess based on visibility alone.

```php
use Derafu\Backbone\Attribute\Operation;

class InvoiceBuilderWorker extends AbstractWorker implements WorkerInterface
{
    #[Operation]
    public function build(string $number, int $amount): array
    {
        // ...
    }
}
```

That's the entire required usage: no arguments, just the tag. Everything else this attribute offers is optional.

## Not a Service Attribute

`#[Package]`/`#[Component]`/`#[Worker]`/`#[Job]`/`#[Handler]`/`#[Strategy]` (see [Service Lifecycle](https://www.derafu.dev/docs/core/backbone/service-lifecycle)) all mark a *class* as a registrable service with its own identity, hierarchy and lifecycle — `TARGET_CLASS`, extending `AbstractServiceMetadata`. `#[Operation]` is deliberately different: `TARGET_METHOD`, and it does **not** extend `AbstractServiceMetadata` or implement `ServiceMetadataInterface`. An operation isn't a service of its own — it's a capability of a `Worker` that already exists, with no `id` or parent reference to manage, because the containing class's own service attribute already provides that context.

## What It Can Add on Top of Reflection

Every property exists only to say something reflection or a PHPDoc block cannot say on its own — none of it is required, and the normal case is to set none of it at all:

```php
#[Operation(
    name: 'Create a draft invoice',
    description: 'Builds a draft from the given data, without emitting it.',
    parameters: [
        'number' => ['example' => 'F-001'],
        'amount' => ['example' => 15000, 'description' => 'Amount in the smallest currency unit.'],
    ],
    results: [
        'success' => ['description' => 'The created draft.', 'example' => ['id' => 'DR-001']],
        MissingParameterException::class => ['description' => 'A required parameter was not provided.'],
    ],
)]
public function build(string $number, int $amount): array
```

- **`name`/`description`** override the method's own PHPDoc summary/description. Leave both `null` (the default, and the expected normal case) to keep using PHPDoc — this is not a place to duplicate what a good docblock already says; it exists for the rarer case where the text written for PHP maintainers isn't the text an external consumer should see.
- **`parameters`** overrides or extends what reflection already knows about each parameter, keyed by parameter name. Only the keys given are applied — reflection's own `type`/`required`/`default` stay exactly as reflected unless a key explicitly overrides them:
  - `'example'` — a realistic sample value. Reflection has no way to produce one on its own.
  - `'type'`/`'description'` — for when reflection's own type isn't precise enough (a union type collapsed to a plain string, a bare `array` that actually has a real shape).
- **`results`** documents outcomes, keyed however the consumer identifies each one — `'success'`, or the fully-qualified class name of an exception the operation can throw, with whatever data that consumer finds useful under each key. This attribute does not define what a key means or what it's for; it just holds what's given. A key is never anything transport-specific like an HTTP status code — resolving a scenario to something transport-specific (a status code, for instance) is a decision for whichever consumer needs that, not for this attribute.

## Who Reads It

`derafu/backbone` defines `#[Operation]` and stops there — it has no idea what, if anything, ever reads it. Nothing in this package depends on `derafu/backbone-dispatcher`, on purpose: a business library can tag its workers' operations without pulling in anything about how they'll eventually be dispatched.

The two real consumers today both live in [`derafu/backbone-dispatcher`](https://www.derafu.dev/docs/core/backbone-dispatcher):

- **[`TaggedOperationPolicy`](https://www.derafu.dev/docs/core/backbone-dispatcher#controlling-which-operations-can-be-dispatched-operationpolicyinterface)** — the recommended policy for anything reachable from outside PHP — only allows dispatching what's tagged, closing off every trait helper and `ServiceInterface` method this attribute exists to distinguish from.
- **`Inspector`**, and through it [`#[Operation]` in Backbone Dispatcher](/docs/core/backbone-dispatcher#documenting-an-operation-operation) and [`derafu/backbone-api`'s `Documenter`](https://www.derafu.dev/docs/core/backbone-api#autodiscovery) — merge the `name`/`description`/`parameters`/`results` given here on top of what reflection and PHPDoc already produced, to build generated documentation (an OpenAPI spec, for instance) that says more than reflection alone ever could.




---

## Translation Project

Derafu Translation

# Derafu Translation




---

### Introduction

Translation Library with Exception Support

# Translation Library with Exception Support

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/translation/main)
![CI Workflow](https://github.com/derafu/translation/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/translation)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/translation)
![Total Downloads](https://poser.pugx.org/derafu/translation/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/translation/d/monthly)

A small library that adds two things on top of `symfony/translation`:

1. **Translatable exceptions**: exceptions that carry a message, ICU
   parameters and a translation domain, and can render themselves in
   English (or any locale) with zero setup, or be translated later by
   handing them a real translator.
2. **A resource discovery layer**: `symfony/translation` doesn't provide a
   way to discover translation files in a directory on its own (that's
   normally wired by a full framework). This library adds that missing
   piece as a small, standalone component.

Everything else — ICU message formatting, locale fallback, file loaders
(YAML, JSON, PHP, XLIFF, PO, MO, CSV, INI) — comes directly from
`symfony/translation` itself. This library does not reimplement a
translation engine.

## Features

- 🔄 **Translatable Exceptions**: A full hierarchy of exceptions (mirroring
  PHP's SPL exceptions) that support translation with minimal setup.
- 🌍 **ICU Support**: Powered by PHP's `intl` extension via
  `symfony/translation`'s own ICU formatter. Works even without a
  translator configured.
- 📁 **Multi-Directory Resource Discovery**: Register N directories (or a
  tagged collection of providers, if you use a DI container) and have every
  translation file inside them loaded automatically.
- ⛓️ **Locale Fallback**: Configurable fallback locale chain, courtesy of
  `symfony/translation`.
- 🪶 **Lightweight**: The only hard dependencies are `symfony/translation`,
  `symfony/translation-contracts`, `symfony/yaml`, and the `intl` PHP
  extension. No framework, no `symfony/http-kernel`.

## Installation

```bash
composer require derafu/translation
```

## Basic Usage

### Making Exceptions Translatable

```php
// Before: your existing exception.
class ValidationException extends Exception
{
}

// After: extend one of the translatable base exceptions instead.
use Derafu\Translation\Exception\Core\TranslatableException;

class ValidationException extends TranslatableException
{
    // No further changes needed.
}
```

### Using Translatable Exceptions

```php
// 1. A plain string: used as both the message and the translation id.
throw new ValidationException('Email is invalid.');

// 2. An array: first element is the message/id, the rest are ICU
//    parameters keyed by name.
throw new ValidationException([
    'The value {value} is not a valid email.',
    'value' => 'test@example',
]);

// 3. A TranslatableInterface instance, built directly.
use Derafu\Translation\TranslatableMessage;

throw new ValidationException(new TranslatableMessage(
    'The value {value} is not a valid email.',
    ['value' => 'test@example'],
));
```

Without ever touching a translator, `getMessage()` already returns the
fully ICU-formatted English text — `TranslatableExceptionTrait` formats it
eagerly at construction time. Handing the exception a real translator later
(via `trans()`) is entirely optional, and is what actually produces a
translated string in another locale.

```php
try {
    // ...
} catch (ValidationException $e) {
    // Untranslated (eager ICU formatting only).
    echo $e->getMessage();

    // Translated, given a real translator.
    echo $e->trans($translator, 'es');
}
```

### Translation Files

Files follow `symfony/translation`'s own naming convention, flat inside a
directory: `{domain}(+intl-icu)?.{locale}.{format}`.

```php
// translations/errors+intl-icu.en.php
return [
    'The value {value} is not a valid email.' => 'The value {value} is not a valid email.',
];
```

```yaml
# translations/errors+intl-icu.es.yaml
'The value {value} is not a valid email.': 'El valor {value} no es un correo electrónico válido.'
```

The `+intl-icu` suffix in the domain activates ICU MessageFormat parsing
for that file (`{value}`-style placeholders, plural/select patterns). See
[ICU Formatting](icu-formatting) for details.

### Building a Translator and Registering Resources

```php
use Derafu\Translation\TranslationResourceRegistrar;
use Derafu\Translation\TranslatorFactory;

$translator = TranslatorFactory::create(
    defaultLocale: 'es',
    fallbackLocales: ['es', 'en'],
);

// Discover and register every translation file in a directory.
$registrar = new TranslationResourceRegistrar($translator);
$registrar->registerDirectory(__DIR__ . '/translations');

echo $translator->trans('The value {value} is not a valid email.', [
    'value' => 'test@example',
], 'errors+intl-icu', 'es');
```

## Key Benefits

1. **Zero Compromise**: Existing exception-handling code (`getMessage()`,
   `catch` blocks) keeps working unchanged.
2. **ICU Power**: Full ICU message formatting, with or without a
   translator.
3. **Built on `symfony/translation`**: No custom translation engine to
   maintain or learn — the real Symfony component, with all its loaders.
4. **Multi-Package Friendly**: Register directories from N sources (each
   package can ship its own translations) with a single registrar.

## When to Use This Library

- You want translatable exceptions without rewriting how you throw or
  catch them.
- You want ICU message formatting without depending on a full framework.
- You want a small, standalone way to discover translation files across
  multiple directories.




---

### Quick Start

Quick Start Guide

# Quick Start Guide

Get started with `derafu/translation` in a few minutes.

## Installation

```bash
composer require derafu/translation
```

That's it — there are no optional dependencies to add separately.
`symfony/translation`, `symfony/translation-contracts`, `symfony/yaml` and
the `intl` PHP extension all come as hard requirements, so every built-in
file format (YAML, JSON, PHP, XLIFF, PO, MO, CSV, INI) and ICU formatting
work out of the box.

## Basic Setup

### 1. Make an Exception Translatable

Extend one of the built-in translatable exceptions:

```php
use Derafu\Translation\Exception\Core\TranslatableException;

class ValidationException extends TranslatableException
{
    // No additional code needed.
}
```

If you can't change the parent class (you already extend something else),
use the trait instead:

```php
use Derafu\Translation\Contract\TranslatableInterface;
use Derafu\Translation\Trait\TranslatableExceptionTrait;
use DomainException;

class ValidationException extends DomainException implements TranslatableInterface
{
    use TranslatableExceptionTrait;
}
```

See [Exceptions](exceptions) for the full hierarchy.

### 2. Throw It

```php
// 1. A plain string: used as-is, and as the translation id.
throw new ValidationException('Email is required.');

// 2. An array: first element is the message/id, the rest are named ICU
//    parameters.
throw new ValidationException([
    'The value {value} must be between {min} and {max}.',
    'value' => 42,
    'min' => 1,
    'max' => 10,
]);
```

`getMessage()` already returns the fully formatted English text at this
point — no translator needed yet:

```php
try {
    // ...
} catch (ValidationException $e) {
    echo $e->getMessage();
    // "The value 42 must be between 1 and 10."
}
```

### 3. Create Translation Files

Files are flat inside a directory and follow the naming convention
`{domain}(+intl-icu)?.{locale}.{format}`. `TranslatableExceptionTrait`
defaults to the `errors` domain, so add `+intl-icu` to activate ICU
formatting for it:

```php
// translations/errors+intl-icu.en.php
return [
    'The value {value} must be between {min} and {max}.' =>
        'The value {value} must be between {min} and {max}.',
];
```

```php
// translations/errors+intl-icu.es.php
return [
    'The value {value} must be between {min} and {max}.' =>
        'El valor {value} debe estar entre {min} y {max}.',
];
```

YAML and JSON work exactly the same way:

```yaml
# translations/errors+intl-icu.es.yaml
'The value {value} must be between {min} and {max}.': 'El valor {value} debe estar entre {min} y {max}.'
```

```json
// translations/errors+intl-icu.es.json
{
    "The value {value} must be between {min} and {max}.": "El valor {value} debe estar entre {min} y {max}."
}
```

### 4. Build a Translator and Register the Files

```php
use Derafu\Translation\TranslationResourceRegistrar;
use Derafu\Translation\TranslatorFactory;

// Builds a Symfony Translator with every supported loader already wired.
$translator = TranslatorFactory::create(
    defaultLocale: 'es',
    fallbackLocales: ['es', 'en'],
);

// Discovers every translation file in the directory and registers it.
$registrar = new TranslationResourceRegistrar($translator);
$registrar->registerDirectory(__DIR__ . '/translations');
```

### 5. Translate

```php
try {
    // ...
} catch (ValidationException $e) {
    // Untranslated (English, formatted eagerly at construction time).
    echo $e->getMessage();

    // Translated to the translator's current locale.
    echo $e->trans($translator);

    // Translated to a specific locale.
    echo $e->trans($translator, 'es');
}
```

## Common Use Cases

### Form-Style Validation

```php
class UserValidator
{
    public function validateEmail(string $email): void
    {
        if (empty($email)) {
            throw new ValidationException('The field {field} is required.', ['field' => 'email']);
        }

        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new ValidationException([
                'The value {value} is not a valid email.',
                'value' => $email,
            ]);
        }
    }
}
```

### API Error Responses

```php
use Derafu\Translation\Contract\TranslatableInterface;
use Symfony\Contracts\Translation\TranslatorInterface;
use Throwable;

class ApiErrorHandler
{
    public function __construct(
        private readonly TranslatorInterface $translator,
    ) {
    }

    public function handle(Throwable $e): array
    {
        $message = $e instanceof TranslatableInterface
            ? $e->trans($this->translator)
            : $e->getMessage();

        return ['error' => ['message' => $message]];
    }
}
```

### Complex Messages (Pluralization, Gender)

```php
throw new ValidationException(
    '{count, plural, =0{No files uploaded} one{1 file uploaded} other{# files uploaded}}',
    ['count' => $fileCount],
);

throw new ValidationException(
    '{gender, select, female{She} male{He} other{They}} uploaded {count} files.',
    ['gender' => $user->getGender(), 'count' => $fileCount],
);
```

## Next Steps

1. Read about [ICU Message Format](icu-formatting) for pluralization,
   gender selection and more.
2. Learn about [Resource Providers](custom-providers) for multi-directory
   and multi-package setups.
3. Check the [API Reference](api-reference) for every class and interface.
4. See [Advanced Usage](advanced-usage) for composition and DI wiring.

## Common Pitfalls

1. Always include the `other` case in plural/select patterns:

    ```php
    // Wrong.
    '{gender, select, female{She} male{He}}'

    // Correct.
    '{gender, select, female{She} male{He} other{They}}'
    ```

2. Provide every parameter the message uses:

    ```php
    // Missing 'field' — the {field} placeholder is left unexpanded.
    throw new ValidationException('The field {field} is required.');
    // getMessage(): "The field {field} is required."

    // Correct.
    throw new ValidationException('The field {field} is required.', ['field' => 'email']);
    // getMessage(): "The field email is required."
    ```

3. Remember the `+intl-icu` suffix on the domain if your messages use ICU
   syntax (`{name}`, plural, select). Without it, `symfony/translation`
   uses plain `%name%`-style substitution instead, and `{name}` is left
   untouched. See [ICU Formatting](icu-formatting).

## Tips & Tricks

1. Add static factory methods to your exceptions for common cases:

    ```php
    class ValidationException extends TranslatableException
    {
        public static function required(string $field): self
        {
            return new self(['The field {field} is required.', 'field' => $field]);
        }
    }
    ```

2. Use type hints and PHPDoc for better IDE support:

    ```php
    /**
     * @throws ValidationException When the email is invalid.
     */
    public function validateEmail(string $email): void
    {
        // ...
    }
    ```




---

### API Reference

API Reference

# API Reference

Complete reference for every class and interface `derafu/translation`
ships.

## Interfaces

### TranslatableInterface

`Derafu\Translation\Contract\TranslatableInterface`. Extends Symfony's own
`Symfony\Contracts\Translation\TranslatableInterface` and adds
`Stringable`, so a translatable value can always be cast to a string (the
untranslated, eagerly ICU-formatted version) even without a translator.

```php
interface TranslatableInterface extends
    \Symfony\Contracts\Translation\TranslatableInterface,
    Stringable
{
    public function __toString(): string;
}
```

`Symfony\Contracts\Translation\TranslatableInterface` itself requires:

```php
public function trans(TranslatorInterface $translator, ?string $locale = null): string;
```

### TranslationResourceProviderInterface

`Derafu\Translation\Contract\TranslationResourceProviderInterface`.
Declares directories containing translation files, meant to be collected
(e.g. via a dependency-injection tagged iterator) so
`TranslationResourceRegistrar` can register every directory without a
central place having to know about each source in advance.

```php
interface TranslationResourceProviderInterface
{
    /**
     * @return iterable<string> Absolute paths to directories with files
     * named `domain(+intl-icu)?.locale.format`.
     */
    public function getDirectories(): iterable;
}
```

## Classes

### TranslatableMessage

`Derafu\Translation\TranslatableMessage`. A message with ICU placeholders
that can be translated using a translator, or eagerly ICU-formatted (as-is)
when no translator is available.

```php
final class TranslatableMessage implements TranslatableInterface
{
    /**
     * @param string $message ICU MessageFormat string, used as the
     * translation id and as the fallback text.
     * @param array<string, mixed> $parameters ICU placeholder values.
     * @param string|null $domain Translation domain, null for Symfony's
     * default ('messages').
     * @param string|null $defaultLocale Locale used for eager ICU
     * formatting in __toString() when no translator is available, and as
     * the fallback locale in trans() when none is given.
     */
    public function __construct(
        string $message,
        array $parameters = [],
        ?string $domain = null,
        ?string $defaultLocale = null,
    );

    public function trans(TranslatorInterface $translator, ?string $locale = null): string;

    /**
     * Formats the raw message via ICU, without a translator. Returns the
     * raw message unchanged if the pattern is invalid.
     */
    public function __toString(): string;
}
```

### TranslationResourceRegistrar

`Derafu\Translation\TranslationResourceRegistrar`. Discovers translation
files in directories and registers them as resources of a
`Symfony\Component\Translation\Translator`, using the `LoaderInterface`s
registered on it. This is the piece `symfony/translation` doesn't provide
standalone (directory discovery is normally wired by a full framework).

```php
final class TranslationResourceRegistrar
{
    public function __construct(private readonly Translator $translator);

    /**
     * Registers every file directly inside a directory.
     *
     * @throws InvalidArgumentException If the directory doesn't exist, a
     * file's name doesn't follow the `domain.locale.format` convention, or
     * its extension isn't supported.
     */
    public function registerDirectory(string $directory): void;

    /**
     * @param iterable<string> $directories
     */
    public function registerDirectories(iterable $directories): void;

    /**
     * @param iterable<TranslationResourceProviderInterface> $providers
     */
    public function registerFromProviders(iterable $providers): void;

    /** @return array<string> Every locale registered so far. */
    public function getRegisteredLocales(): array;

    /** @return array<string> Every domain registered so far. */
    public function getRegisteredDomains(): array;
}
```

Registration order is precedence order: for the same key in the same
domain/locale, the **last** directory registered wins.

Supported file extensions: `yaml`, `yml`, `json`, `php`, `xlf`, `xliff`,
`po`, `mo`, `csv`, `ini`.

### SimpleTranslationResourceProvider

`Derafu\Translation\SimpleTranslationResourceProvider`. Default
implementation of `TranslationResourceProviderInterface` that wraps a
fixed list of directories.

```php
final class SimpleTranslationResourceProvider implements TranslationResourceProviderInterface
{
    /** @param iterable<string> $directories */
    public function __construct(private readonly iterable $directories);

    public function getDirectories(): iterable;
}
```

### TranslatorFactory

`Derafu\Translation\TranslatorFactory`. Builds a
`Symfony\Component\Translation\Translator` with every file loader
`TranslationResourceRegistrar` supports already registered, plus the given
resource providers, plus fallback locales.

```php
final class TranslatorFactory
{
    /**
     * @param array<string> $fallbackLocales
     * @param iterable<TranslationResourceProviderInterface> $resourceProviders
     * Registered immediately, inside this call, so registration always
     * happens whenever a Translator is built — regardless of whether
     * anything else references a registrar directly (a dependency-injected
     * service nothing depends on is never instantiated by the container).
     */
    public static function create(
        string $defaultLocale,
        array $fallbackLocales = [],
        iterable $resourceProviders = [],
    ): Translator;
}
```

## Trait

### TranslatableExceptionTrait

`Derafu\Translation\Trait\TranslatableExceptionTrait`. Adds translation
support to any exception. Used internally by every exception class listed
below — apply it directly only if you can't extend one of them (see
[Exceptions](exceptions)).

```php
trait TranslatableExceptionTrait
{
    protected string $defaultDomain = 'errors';
    protected string $defaultLocale = 'en';

    /**
     * @param string|array|TranslatableInterface $message
     *   - string: used as both message and translation id.
     *   - array: first element is the message/id, the rest are named ICU
     *     parameters.
     *   - TranslatableInterface: used directly.
     * @throws InvalidArgumentException When an empty array is given, or
     * its first element isn't a string.
     */
    public function __construct(
        string|array|TranslatableInterface $message,
        int $code = 0,
        ?Throwable $previous = null,
    );

    public function trans(TranslatorInterface $translator, ?string $locale = null): string;

    /** @return array<string, mixed> */
    public function __serialize(): array;

    /** @param array<string, mixed> $data */
    public function __unserialize(array $data): void;
}
```

`__serialize()`/`__unserialize()` intentionally drop the stack trace (it
may contain non-serializable values such as closures or resources), so
these exceptions can safely be stored in sessions (e.g. for flash
messages). After unserializing, `getTrace()` no longer reflects the
exception's original call stack.

## Exception Hierarchy

Every class below implements `TranslatableInterface` via
`TranslatableExceptionTrait`, and mirrors the equivalent native PHP SPL
exception:

| Class | Extends |
| --- | --- |
| `Exception\Core\TranslatableException` | `Exception` |
| `Exception\Core\TranslatableLogicException` | `LogicException` |
| `Exception\Core\TranslatableRuntimeException` | `RuntimeException` |
| `Exception\Logic\TranslatableDomainException` | `DomainException` |
| `Exception\Logic\TranslatableInvalidArgumentException` | `InvalidArgumentException` |
| `Exception\Logic\TranslatableLengthException` | `LengthException` |
| `Exception\Logic\TranslatableOutOfRangeException` | `OutOfRangeException` |
| `Exception\Runtime\TranslatableOutOfBoundsException` | `OutOfBoundsException` |
| `Exception\Runtime\TranslatableOverflowException` | `OverflowException` |
| `Exception\Runtime\TranslatableRangeException` | `RangeException` |
| `Exception\Runtime\TranslatableUnderflowException` | `UnderflowException` |
| `Exception\Runtime\TranslatableUnexpectedValueException` | `UnexpectedValueException` |

All under the `Derafu\Translation\Exception\` namespace.

## Dependencies

`derafu/translation` requires:

- `php: ^8.5`
- `ext-intl` (PHP's ICU bindings, for `\MessageFormatter`)
- `symfony/translation-contracts: ^3.7`
- `symfony/yaml: ^8.1`
- `symfony/translation: ^8.1`

No dependency on `symfony/framework-bundle`, `symfony/http-kernel`, or
`symfony/dependency-injection` — the dependency-injection recipe described
in [Advanced Usage](advanced-usage) is entirely optional wiring that lives
in the consuming application.




---

### Exceptions

Working with Translatable Exceptions

# Working with Translatable Exceptions

This guide covers the translatable exception hierarchy shipped by
`derafu/translation`.

## A Note on Translation Ids

Every example in this guide uses **the real English message text as the
translation id** (e.g. `'The field {field} is required.'`), not an
abstract key like `validation.required`. This is deliberate: Symfony's own
translation documentation recommends real text for shared libraries
specifically (as opposed to end-user applications, where abstract keys
make more sense), so that code stays readable and still produces a sane
message even when no translator — or no matching translation — is
available. `TranslatableExceptionTrait` is built around this idea: the
message you throw with is always what `getMessage()` returns when
untranslated.

## Available Exceptions

The library mirrors PHP's own SPL exception hierarchy with translatable
equivalents.

### Core Exceptions

- `Derafu\Translation\Exception\Core\TranslatableException` — extends
  `Exception`.
- `Derafu\Translation\Exception\Core\TranslatableLogicException` — extends
  `LogicException`.
- `Derafu\Translation\Exception\Core\TranslatableRuntimeException` —
  extends `RuntimeException`.

### Logic Exceptions

- `Derafu\Translation\Exception\Logic\TranslatableDomainException` —
  extends `DomainException`.
- `Derafu\Translation\Exception\Logic\TranslatableInvalidArgumentException`
  — extends `InvalidArgumentException`.
- `Derafu\Translation\Exception\Logic\TranslatableLengthException` —
  extends `LengthException`.
- `Derafu\Translation\Exception\Logic\TranslatableOutOfRangeException` —
  extends `OutOfRangeException`.

### Runtime Exceptions

- `Derafu\Translation\Exception\Runtime\TranslatableOutOfBoundsException` —
  extends `OutOfBoundsException`.
- `Derafu\Translation\Exception\Runtime\TranslatableOverflowException` —
  extends `OverflowException`.
- `Derafu\Translation\Exception\Runtime\TranslatableRangeException` —
  extends `RangeException`.
- `Derafu\Translation\Exception\Runtime\TranslatableUnderflowException` —
  extends `UnderflowException`.
- `Derafu\Translation\Exception\Runtime\TranslatableUnexpectedValueException`
  — extends `UnexpectedValueException`.

Every class above implements `TranslatableInterface` and uses
`TranslatableExceptionTrait` internally, so they all share the same
constructor and `trans()` method described below.

## Using the Trait Directly

### TranslatableExceptionTrait

If you can't (or don't want to) extend one of the exceptions above — for
example, because you already extend something else — use the trait
instead:

```php
use Derafu\Translation\Contract\TranslatableInterface;
use Derafu\Translation\Trait\TranslatableExceptionTrait;
use DomainException;
use Throwable;

class OrderException extends DomainException implements TranslatableInterface
{
    use TranslatableExceptionTrait;

    // $defaultDomain is a *typed* property on the trait, so PHP does not
    // allow overriding its default value by simply redeclaring it here
    // (that's a fatal "incompatible property definition" error). Set it in
    // the constructor instead, before calling normalizeMessage().
    public function __construct(
        string|array|TranslatableInterface $message,
        int $code = 0,
        ?Throwable $previous = null,
    ) {
        $this->defaultDomain = 'orders';
        parent::__construct($this->normalizeMessage($message), $code, $previous);
    }

    public static function insufficientStock(string $product): self
    {
        return new self(['Not enough stock for "{product}".', 'product' => $product]);
    }
}
```

### When to Use the Trait vs. Extending a Base Exception

Use the trait when:

- You already extend another exception class.
- You need custom behavior beyond translation.

Use one of the base exceptions when:

- You don't need custom behavior.
- You want the simplest possible implementation:

    ```php
    class ValidationException extends TranslatableDomainException
    {
        // Inherits everything from the trait, with no extra code.
    }
    ```

## The Constructor

All translatable exceptions accept the same three argument shapes:

```php
public function __construct(
    string|array|TranslatableInterface $message,
    int $code = 0,
    ?Throwable $previous = null,
)
```

- **`string`**: used as both the exception message and the translation id.
- **`array`**: the first element is the message/id, the remaining elements
  are named ICU parameters (`['The field {field} is required.', 'field' => 'email']`).
- **`TranslatableInterface`**: a `TranslatableMessage` (or any other
  implementation) built directly — useful when you want to reuse the same
  translatable message in more than one place.

## Default Domain and Locale

`TranslatableExceptionTrait` defines:

```php
protected string $defaultDomain = 'errors';
protected string $defaultLocale = 'en';
```

Override `$defaultDomain` in your own exception class to group its
messages under a different translation domain. This works fine through
normal class inheritance, when you extend one of the built-in exceptions
(they already apply the trait for you):

```php
class OrderException extends TranslatableDomainException
{
    protected string $defaultDomain = 'orders';
}
```

If you `use TranslatableExceptionTrait` directly in your own class instead
(see above), redeclaring `$defaultDomain` in that *same* class fails with a
fatal "incompatible property definition" error — PHP does not allow a
class to override the default value of a trait's own *typed* property by
redeclaring it in the class that uses the trait. Set it in the constructor
instead in that case, as shown in the `OrderException` example above.

## Best Practices

1. **Choose the most specific exception type available.** It carries
   semantic meaning for callers doing `catch (SomeSplException $e)`, even
   before translation comes into play.
2. **Use the real message text as the id**, per the note above — don't
   introduce abstract keys unless you have a specific reason to (e.g. a
   dedicated translation-management workflow that needs stable ids
   independent of wording).
3. **Provide every ICU parameter the message references.** A missing
   parameter is left unexpanded in the output rather than throwing.
4. **Group related exceptions under a domain-specific base class:**

    ```php
    abstract class OrderException extends TranslatableDomainException
    {
        protected string $defaultDomain = 'orders';
    }

    class OrderNotFoundException extends OrderException {}
    class OrderValidationException extends OrderException {}
    ```




---

### ICU Formatting

ICU Message Formatting Guide

# ICU Message Formatting Guide

`derafu/translation` doesn't implement its own message formatter. ICU
formatting comes directly from PHP's `intl` extension (`\MessageFormatter`),
used in two places:

1. **`TranslatableMessage::__toString()`** — formats the raw message
   eagerly, without a translator. This is what makes `getMessage()` on a
   translatable exception return a fully formatted string with zero setup.
2. **`symfony/translation`'s own ICU formatter** — used when translating
   through a real `Translator`, for any domain whose name ends in
   `+intl-icu` (see [Resource Providers](custom-providers) and the
   [API Reference](api-reference)).

Both paths accept the exact same ICU MessageFormat syntax described below.

## Basic Placeholders

The simplest form uses named placeholders:

```php
throw new ValidationException(
    'The field {field} is required.',
    ['field' => 'email'],
);
// getMessage(): "The field email is required."
```

Multiple placeholders are supported:

```php
throw new ValidationException(
    'Value {value} for field {field} is invalid.',
    ['value' => 'test@', 'field' => 'email'],
);
// getMessage(): "Value test@ for field email is invalid."
```

## Pluralization

```php
$id = '{count, plural, =0{No messages} one{# message} other{# messages}}';

new TranslatableMessage($id, ['count' => 2]); // "2 messages"
new TranslatableMessage($id, ['count' => 1]); // "1 message"
new TranslatableMessage($id, ['count' => 0]); // "No messages"
```

Available plural categories:

- `zero`: for languages with a special zero form.
- `one`: singular form.
- `two`: dual form (for languages that have it).
- `few` / `many`: for languages with special handling of small/large
  numbers.
- `other`: default form (**required** — always provide it).
- `=n`: exact number matches (e.g. `=0`).

## Gender / Select

```php
$id = '{gender, select, female {She liked your post} male {He liked your post} other {They liked your post}}';

(string) new TranslatableMessage($id, ['gender' => 'female']);
// "She liked your post"
```

Nested placeholders work too:

```php
$id = '{gender, select, female {{name} added her comment} male {{name} added his comment} other {{name} added their comment}}';

(string) new TranslatableMessage($id, ['gender' => 'female', 'name' => 'Alice']);
// "Alice added her comment"
```

## Number Formatting

```php
'{value, number}'          // Plain number.
'{value, number, percent}' // Percentage.
'{value, number, currency}' // Currency, using the message's own locale.
```

Currency formatting depends on the locale carrying a specific currency
association (e.g. `en_US`, not just `en`):

```php
new TranslatableMessage(
    'Balance must be greater than {min, number, currency}.',
    ['min' => 100],
    null,
    'en_US',
);
// "Balance must be greater than $100.00."
```

## Nested Plural + Select

Patterns can be nested for combined scenarios:

```php
$id = '{gender, select,
    female {{count, plural, =0{She has no messages} one{She has # message} other{She has # messages}}}
    male {{count, plural, =0{He has no messages} one{He has # message} other{He has # messages}}}
    other {{count, plural, =0{They have no messages} one{They have # message} other{They have # messages}}}
}';

(string) new TranslatableMessage($id, ['gender' => 'female', 'count' => 5]);
// "She has 5 messages"
```

## Common Patterns

```php
// Range validation.
'Value must be between {min} and {max}.'

// List validation.
'{count, plural, =0{List cannot be empty} one{At least one item is required} other{At least # items are required}}'

// Status messages.
'{status, select, pending{Waiting for approval} approved{Approved on {date}} rejected{Rejected: {reason}} other{Unknown status}}'
```

## Troubleshooting

1. **Missing the `other` category** — required for every `select`/`plural`
   pattern. Without it, a value that doesn't match any listed category
   falls back to the raw, unformatted message (same as an invalid pattern,
   see below):

    ```php
    // Wrong.
    '{gender, select, male{He} female{She}}'

    // Correct.
    '{gender, select, male{He} female{She} other{They}}'
    ```

2. **Unmatched braces:**

    ```php
    // Wrong.
    'Hello {name'

    // Correct.
    'Hello {name}'
    ```

   `TranslatableMessage::__toString()` catches this: an invalid ICU pattern
   returns the raw message unchanged rather than throwing.

3. **Missing parameters** don't throw either — the placeholder is simply
   left unexpanded:

    ```php
    (string) new TranslatableMessage('{count} items'); // "{count} items"
    ```

---

For more on ICU MessageFormat syntax:

- [ICU User Guide](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
- [PHP `MessageFormatter` manual](https://www.php.net/manual/en/class.messageformatter.php)




---

### Resource Providers

Resource Providers

# Resource Providers

This guide explains `TranslationResourceProviderInterface` — the piece
that lets you (or a dependency injection container) discover translation
directories from multiple sources — and when you'd write a custom
`Symfony\Component\Translation\Loader\LoaderInterface` instead.

## What a Resource Provider Is (and Isn't)

`TranslationResourceProviderInterface` declares **directories containing
translation files**. It does not read or parse anything itself — that's
`TranslationResourceRegistrar`'s job (see the
[API Reference](api-reference)), using `symfony/translation`'s own file
loaders (YAML, JSON, PHP, XLIFF, PO, MO, CSV, INI).

```php
interface TranslationResourceProviderInterface
{
    /**
     * @return iterable<string> Absolute paths to directories containing
     * translation files, named `domain(+intl-icu)?.locale.format`.
     */
    public function getDirectories(): iterable;
}
```

If your translations always live in files on disk, this is the interface
to implement. If they come from somewhere else entirely (a database, an
API, Redis), see [Non-File Sources](#non-file-sources) below — that's a
different extension point.

## The Built-In Implementation

For the common case — "I have N directories and that's it" —
`SimpleTranslationResourceProvider` already does the job:

```php
use Derafu\Translation\SimpleTranslationResourceProvider;

$provider = new SimpleTranslationResourceProvider([
    __DIR__ . '/translations',
    __DIR__ . '/vendor/some-package/translations',
]);
```

## Writing Your Own

A custom provider is useful when the set of directories isn't a fixed,
hardcoded list — for example, when it needs to be computed:

```php
use Derafu\Translation\Contract\TranslationResourceProviderInterface;

final class PackageTranslationResourceProvider implements TranslationResourceProviderInterface
{
    public function getDirectories(): iterable
    {
        // Every installed vendor package that ships its own translations,
        // discovered instead of hardcoded.
        foreach (glob(__DIR__ . '/../../vendor/*/*/resources/translations', GLOB_ONLYDIR) as $dir) {
            yield $dir;
        }
    }
}
```

This is exactly the pattern used to expose a library's own bundled
translations to whatever application consumes it: the library ships a
small provider class pointing at its own `resources/translations`
directory, and the consuming application registers it (directly, or via a
tagged dependency-injection collection — see
[Advanced Usage](advanced-usage)).

```php
use Derafu\Translation\Contract\TranslationResourceProviderInterface;

final class MyLibraryTranslationResourceProvider implements TranslationResourceProviderInterface
{
    public function getDirectories(): iterable
    {
        return [__DIR__ . '/../../resources/translations'];
    }
}
```

## Registering Providers

`TranslationResourceRegistrar::registerFromProviders()` accepts any
`iterable` of `TranslationResourceProviderInterface` instances:

```php
use Derafu\Translation\TranslationResourceRegistrar;

$registrar = new TranslationResourceRegistrar($translator);
$registrar->registerFromProviders([
    new SimpleTranslationResourceProvider([__DIR__ . '/translations']),
    new PackageTranslationResourceProvider(),
]);
```

Or pass them straight to `TranslatorFactory::create()`, which registers
them as part of building the translator (see the
[API Reference](api-reference) for why that matters):

```php
use Derafu\Translation\TranslatorFactory;

$translator = TranslatorFactory::create(
    defaultLocale: 'es',
    resourceProviders: [
        new SimpleTranslationResourceProvider([__DIR__ . '/translations']),
        new PackageTranslationResourceProvider(),
    ],
);
```

Registration order is precedence order: when two directories define the
same key for the same domain/locale, the **last one registered wins**. If
you want your own application's translations to be able to override a
dependency's, register the dependency's provider(s) first and your own
last.

## Non-File Sources

If your translations genuinely don't live in files (a database table, a
remote API, Redis), `TranslationResourceProviderInterface` isn't the right
extension point — it only ever produces *directories*. Instead, write a
`Symfony\Component\Translation\Loader\LoaderInterface` and register it
directly on the `Translator`:

```php
use Symfony\Component\Translation\Loader\LoaderInterface;
use Symfony\Component\Translation\MessageCatalogue;

final class DatabaseLoader implements LoaderInterface
{
    public function __construct(private readonly PDO $db)
    {
    }

    public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogue
    {
        $stmt = $this->db->prepare(
            'SELECT message_key, message_text FROM translations WHERE locale = ? AND domain = ?'
        );
        $stmt->execute([$locale, $domain]);

        $catalogue = new MessageCatalogue($locale);
        $catalogue->add($stmt->fetchAll(PDO::FETCH_KEY_PAIR), $domain);

        return $catalogue;
    }
}
```

```php
$translator->addLoader('database', new DatabaseLoader($pdo));
$translator->addResource('database', 'irrelevant-for-this-loader', 'es', 'errors+intl-icu');
```

This bypasses `TranslationResourceRegistrar` entirely — it's a direct use
of `symfony/translation`'s own extension point, which this library builds
on rather than replaces.




---

### Advanced Usage

Advanced Usage Guide

# Advanced Usage Guide

This guide covers less common, but still fully supported, patterns.

## Reusable Message Templates

`TranslatableMessage` instances are plain value objects — build them once
and reuse them wherever a `TranslatableInterface` is expected (including
as an exception's message):

```php
use Derafu\Translation\Contract\TranslatableInterface;
use Derafu\Translation\TranslatableMessage;

final class Messages
{
    public static function required(string $field): TranslatableInterface
    {
        return new TranslatableMessage('The field {field} is required.', ['field' => $field]);
    }

    public static function invalid(string $field, mixed $value): TranslatableInterface
    {
        return new TranslatableMessage(
            'The value {value} for field {field} is invalid.',
            ['field' => $field, 'value' => (string) $value],
        );
    }
}

throw new ValidationException(Messages::required('email'));
```

## Multiple Directories and Precedence

`TranslationResourceRegistrar` accepts a single directory, a list of
directories, or a collection of
[resource providers](custom-providers) — and registration order defines
precedence:

```php
use Derafu\Translation\TranslationResourceRegistrar;

$registrar = new TranslationResourceRegistrar($translator);
$registrar->registerDirectories([
    __DIR__ . '/vendor/some-dependency/translations',
    __DIR__ . '/translations', // Your own, registered last: it can override the dependency's keys.
]);

$registrar->getRegisteredLocales(); // e.g. ['en', 'es']
$registrar->getRegisteredDomains(); // e.g. ['errors+intl-icu']
```

Prefer feeding providers straight into `TranslatorFactory::create()`
instead of instantiating `TranslationResourceRegistrar` yourself whenever
you can — see the [API Reference](api-reference) for why registration
needs to happen there rather than through a separately fetched registrar
object.

## Dependency Injection (`symfony/dependency-injection`)

`derafu/translation` doesn't depend on `symfony/dependency-injection` (or
any framework) — this is entirely optional wiring for applications that
choose to use it. The package ships
`resources/config/translation-services.yaml` with one thing: an alias from
the translation-contracts interface to the concrete `Translator` service,
so that code type-hinting the interface (as it should) still resolves
correctly:

```yaml
services:
    Symfony\Contracts\Translation\TranslatorInterface: '@Symfony\Component\Translation\Translator'
```

Import it, then register your own `Translator` and any
`TranslationResourceProviderInterface` implementations, tagged so they can
be collected automatically:

```yaml
imports:
    - { resource: '../vendor/derafu/translation/resources/config/translation-services.yaml' }

services:
    App\Translation\MyTranslationResourceProvider:
        tags: ['derafu_translation.resource_provider']

    Symfony\Component\Translation\Translator:
        factory: ['Derafu\Translation\TranslatorFactory', 'create']
        arguments:
            $defaultLocale: 'es'
            $fallbackLocales: ['es', 'en']
            $resourceProviders: !tagged_iterator derafu_translation.resource_provider
```

Note the tag is applied explicitly on each provider service, rather than
relying on Symfony's `_instanceof` autoconfiguration: `_instanceof` (like
`_defaults`) only applies to services declared in the *same* YAML file that
declares it — it does not propagate to services declared in a different
file, even one that imports it.

## Decorating the Translator

Since `derafu/translation` builds directly on
`Symfony\Contracts\Translation\TranslatorInterface`, any standard decorator
pattern for that interface works unchanged — for example, logging every
translation lookup:

```php
use Psr\Log\LoggerInterface;
use Symfony\Contracts\Translation\TranslatorInterface;

final class LoggingTranslator implements TranslatorInterface
{
    public function __construct(
        private readonly TranslatorInterface $translator,
        private readonly LoggerInterface $logger,
    ) {
    }

    public function trans(string $id, array $parameters = [], ?string $domain = null, ?string $locale = null): string
    {
        $result = $this->translator->trans($id, $parameters, $domain, $locale);

        $this->logger->debug('Translation performed.', [
            'id' => $id,
            'domain' => $domain,
            'locale' => $locale,
            'result' => $result,
        ]);

        return $result;
    }

    public function getLocale(): string
    {
        return $this->translator->getLocale();
    }
}
```

Wrap the `Translator` built by `TranslatorFactory::create()` with your
decorator, and pass the decorator — not the raw translator — to `trans()`
calls and to anything else that needs a `TranslatorInterface`:

```php
$translator = new LoggingTranslator(TranslatorFactory::create('en'), $logger);

echo $translator->trans('Hello {name}', ['name' => 'John'], 'messages+intl-icu');
// Logs the lookup, then: "Hello John"
```

Remember the `+intl-icu` domain suffix here too — the decorator forwards
whatever domain it's given straight to the wrapped translator, so the same
[ICU rules](icu-formatting) apply.




---

### Real World

Real World Examples

# Real World Examples

Practical, framework-agnostic examples of using `derafu/translation`.

## API Error Responses

```php
use Derafu\Translation\Contract\TranslatableInterface;
use Symfony\Contracts\Translation\TranslatorInterface;
use Throwable;

final class ApiErrorHandler
{
    public function __construct(
        private readonly TranslatorInterface $translator,
    ) {
    }

    /**
     * @return array{error: array{message: string, code: int}}
     */
    public function handle(Throwable $e, ?string $locale = null): array
    {
        $message = $e instanceof TranslatableInterface
            ? $e->trans($this->translator, $locale)
            : $e->getMessage();

        return [
            'error' => [
                'message' => $message,
                'code' => $e->getCode(),
            ],
        ];
    }
}
```

## Field-by-Field Validation Errors

A common pattern: collect one translatable exception per invalid field,
then translate them all at once when building the response. Remember to
register a `errors+intl-icu.*.*` resource (`ValidationException` uses the
`errors` domain by default) — without one, `trans()` falls back to
`symfony/translation`'s plain `%name%`-style substitution instead of ICU,
which does not understand `{value}`-style placeholders. See
[ICU Formatting](icu-formatting) for the full explanation.

```php
use Derafu\Translation\Exception\Core\TranslatableException;
use Symfony\Contracts\Translation\TranslatorInterface;

final class ValidationException extends TranslatableException
{
}

final class Validator
{
    /**
     * @return array<string, ValidationException> Keyed by field name.
     */
    public function validate(array $data): array
    {
        $errors = [];

        if (empty($data['email'])) {
            $errors['email'] = new ValidationException([
                'The field {field} is required.',
                'field' => 'email',
            ]);
        } elseif (!filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
            $errors['email'] = new ValidationException([
                'The value {value} is not a valid email.',
                'value' => $data['email'],
            ]);
        }

        return $errors;
    }
}

function formatErrors(array $errors, TranslatorInterface $translator, string $locale): array
{
    $formatted = [];
    foreach ($errors as $field => $exception) {
        $formatted[$field] = $exception->trans($translator, $locale);
    }
    return $formatted;
}
```

```php
// translations/errors+intl-icu.es.php
return [
    'The field {field} is required.' => 'El campo {field} es obligatorio.',
    'The value {value} is not a valid email.' => 'El valor {value} no es un correo electrónico válido.',
];
```

## Domain-Specific Exception Hierarchies

Group related exceptions under a shared base class with its own
translation domain (see [Exceptions](exceptions) for why `$defaultDomain`
must be overridden this way):

```php
use Derafu\Translation\Exception\Logic\TranslatableDomainException;

abstract class OrderException extends TranslatableDomainException
{
    protected string $defaultDomain = 'orders';
}

final class InsufficientStockException extends OrderException
{
    public static function forProduct(string $product, int $requested, int $available): self
    {
        return new self([
            'Not enough stock for "{product}": requested {requested}, available {available}.',
            'product' => $product,
            'requested' => $requested,
            'available' => $available,
        ]);
    }
}

final class InvalidStatusTransitionException extends OrderException
{
    public static function fromTo(string $from, string $to): self
    {
        return new self([
            'Cannot transition order from "{from}" to "{to}".',
            'from' => $from,
            'to' => $to,
        ]);
    }
}
```

```php
// translations/orders+intl-icu.es.php
return [
    'Not enough stock for "{product}": requested {requested}, available {available}.' =>
        'No hay stock suficiente de "{product}": se pidieron {requested}, hay {available} disponibles.',
    'Cannot transition order from "{from}" to "{to}".' =>
        'No se puede pasar el pedido de "{from}" a "{to}".',
];
```

## CLI Tools

Translatable exceptions work just as well outside of HTTP contexts —
useful for CLI tools that need to report errors in the operator's
language:

```php
use Derafu\Translation\TranslatorFactory;
use Derafu\Translation\TranslationResourceRegistrar;

$locale = getenv('APP_LOCALE') ?: 'en';

$translator = TranslatorFactory::create($locale, ['en']);
(new TranslationResourceRegistrar($translator))->registerDirectory(__DIR__ . '/translations');

try {
    runCommand();
} catch (Throwable $e) {
    $message = $e instanceof \Derafu\Translation\Contract\TranslatableInterface
        ? $e->trans($translator)
        : $e->getMessage();

    fwrite(STDERR, $message . PHP_EOL);
    exit(1);
}
```




---

### Symfony Integration

Symfony Integration

# Symfony Integration

`derafu/translation` doesn't *integrate with* `symfony/translation` the way
a bridge or an adapter would — it's built directly **on top of** it.
`TranslatorFactory::create()` returns a real
`Symfony\Component\Translation\Translator` instance, not a custom
wrapper. Everything this library adds (translatable exceptions, resource
discovery across directories) sits alongside that instance, not between
your code and it.

## No Framework Dependency

The only hard dependencies are `symfony/translation`,
`symfony/translation-contracts`, `symfony/yaml`, and the `intl` PHP
extension. There is no dependency on `symfony/framework-bundle` or
`symfony/http-kernel`, and there will not be one — this library works in
any PHP application, framework or not.

## Using the Real `Translator` Directly

Because `TranslatorFactory::create()` gives you the actual Symfony class,
every native method is available — this library doesn't hide or wrap it:

```php
use Derafu\Translation\TranslatorFactory;

$translator = TranslatorFactory::create('es', ['es', 'en']);

// Native Symfony\Component\Translation\Translator methods, all available.
$translator->setLocale('en');
$translator->getFallbackLocales();
$translator->getCatalogue('es')->all('errors+intl-icu');
```

If you need a loader this library doesn't pre-wire (for example,
`IcuResFileLoader` or `IcuDatFileLoader`, or your own custom loader — see
[Resource Providers](custom-providers)), add it the normal Symfony way:

```php
$translator->addLoader('my_format', new MyCustomLoader());
```

## Locale-Aware Contracts

`Symfony\Component\Translation\Translator` also implements
`Symfony\Component\Translation\TranslatorBagInterface` and
`Symfony\Contracts\Translation\LocaleAwareInterface`, so it can be used
anywhere those contracts are expected, not just where
`Symfony\Contracts\Translation\TranslatorInterface` is required — which is
the interface `TranslatableExceptionTrait::trans()` itself expects.

## Dependency Injection

If your application uses `symfony/dependency-injection` (with or without
the rest of the Symfony Framework), see [Advanced Usage](advanced-usage)
for the wiring recipe this package ships.




---

### Testing

Testing Guide

# Testing Guide

How to test code that uses `derafu/translation` — translatable exceptions,
ICU formatting, and resource registration.

## Testing Untranslated Behavior

Since `getMessage()` is fully formatted at construction time, most tests
don't need a translator at all:

```php
use PHPUnit\Framework\TestCase;

final class ValidationExceptionTest extends TestCase
{
    public function testPlainStringMessage(): void
    {
        $exception = new ValidationException('Email is invalid.');

        $this->assertSame('Email is invalid.', $exception->getMessage());
    }

    public function testIcuParametersAreSubstitutedEagerly(): void
    {
        $exception = new ValidationException([
            'The value {value} is not a valid email.',
            'value' => 'test@example',
        ]);

        $this->assertSame(
            'The value test@example is not a valid email.',
            $exception->getMessage(),
        );
    }
}
```

## Testing with a Stub Translator

For unit tests, a `TranslatorInterface` stub configured with
`willReturnCallback()` is usually enough — it doesn't need to verify how
many times it was called, just what it returns:

```php
use PHPUnit\Framework\TestCase;
use Symfony\Contracts\Translation\TranslatorInterface;

final class OrderExceptionTest extends TestCase
{
    public function testTranslation(): void
    {
        $translator = $this->createStub(TranslatorInterface::class);
        $translator->method('trans')->willReturnCallback(
            fn (string $id, array $parameters = []): string => match ($id) {
                'Not enough stock for "{product}".' => sprintf(
                    'No hay stock de "%s".',
                    $parameters['product'],
                ),
                default => $id,
            },
        );

        $exception = OrderException::insufficientStock('Widget');

        $this->assertSame(
            'No hay stock de "Widget".',
            $exception->trans($translator, 'es'),
        );
    }
}
```

Use `createMock()` instead of `createStub()` only when you actually need to
assert on the number of calls (e.g. `expects($this->once())`) — PHPUnit
flags `createMock()` used purely for return-value stubbing as unnecessary.

## Testing with a Real Translator

For integration tests, use the real `TranslatorFactory` +
`TranslationResourceRegistrar` against fixture translation files —
verifying the actual behavior end to end, ICU formatting included.

Fixtures for the examples below (`tests/fixtures/translations/`):

```php
// errors+intl-icu.es.php
return [
    'The value {value} is not a valid email.' => 'El valor {value} no es un correo electrónico válido.',
];
```

```php
// messages+intl-icu.en.php
return [
    'welcome' => 'Welcome!',
];
```

And an extra directory used only by the precedence test below,
`tests/fixtures/translations-override/`:

```php
// messages+intl-icu.en.php
return [
    'welcome' => 'Overridden message.',
];
```

```php
use PHPUnit\Framework\TestCase;
use Derafu\Translation\TranslationResourceRegistrar;
use Derafu\Translation\TranslatorFactory;
use Symfony\Component\Translation\Translator;

final class TranslationIntegrationTest extends TestCase
{
    private Translator $translator;

    protected function setUp(): void
    {
        $this->translator = TranslatorFactory::create('en', ['en', 'es']);

        $registrar = new TranslationResourceRegistrar($this->translator);
        $registrar->registerDirectory(__DIR__ . '/../fixtures/translations');
    }

    public function testValidationErrorIsTranslated(): void
    {
        $exception = new ValidationException([
            'The value {value} is not a valid email.',
            'value' => 'test@example',
        ]);

        $this->assertSame(
            'El valor test@example no es un correo electrónico válido.',
            $exception->trans($this->translator, 'es'),
        );
    }
}
```

## Testing Resource Registration

Test `TranslationResourceRegistrar` directly against a fixtures directory
to verify discovery and precedence, without needing any specific exception
class:

```php
use PHPUnit\Framework\TestCase;
use Derafu\Translation\TranslationResourceRegistrar;
use Derafu\Translation\TranslatorFactory;

final class TranslationResourceRegistrarTest extends TestCase
{
    public function testDiscoversDomainsAndLocales(): void
    {
        $translator = TranslatorFactory::create('en');
        $registrar = new TranslationResourceRegistrar($translator);

        $registrar->registerDirectory(__DIR__ . '/../fixtures/translations');

        sort($domains = $registrar->getRegisteredDomains());
        sort($locales = $registrar->getRegisteredLocales());

        $this->assertSame(['errors+intl-icu', 'messages+intl-icu'], $domains);
        $this->assertSame(['en', 'es'], $locales);
    }

    public function testLaterDirectoriesOverridePreviousOnesForTheSameKey(): void
    {
        $translator = TranslatorFactory::create('en');
        $registrar = new TranslationResourceRegistrar($translator);

        $registrar->registerDirectories([
            __DIR__ . '/../fixtures/translations',
            __DIR__ . '/../fixtures/translations-override',
        ]);

        $this->assertSame(
            'Overridden message.',
            $translator->trans('welcome', [], 'messages+intl-icu'),
        );
    }
}
```

## Testing Custom Resource Providers

```php
use PHPUnit\Framework\TestCase;
use Derafu\Translation\Contract\TranslationResourceProviderInterface;

final class PackageTranslationResourceProviderTest extends TestCase
{
    public function testReturnsExpectedDirectories(): void
    {
        $provider = new PackageTranslationResourceProvider();

        $directories = iterator_to_array($provider->getDirectories());

        $this->assertNotEmpty($directories);
        foreach ($directories as $directory) {
            $this->assertDirectoryExists($directory);
        }
    }
}
```

## Testing ICU Edge Cases

```php
use PHPUnit\Framework\TestCase;
use Derafu\Translation\TranslatableMessage;

final class IcuFormattingTest extends TestCase
{
    public function testMissingOtherCategoryFallsBackToRawMessage(): void
    {
        $message = new TranslatableMessage(
            '{gender, select, male{He} female{She}}',
            ['gender' => 'unknown'],
        );

        $this->assertSame(
            '{gender, select, male{He} female{She}}',
            (string) $message,
        );
    }

    public function testUnmatchedBraceFallsBackToRawMessage(): void
    {
        $message = new TranslatableMessage('Hello {name', ['name' => 'John']);

        $this->assertSame('Hello {name', (string) $message);
    }

    public function testMissingParameterLeavesPlaceholderUnexpanded(): void
    {
        $message = new TranslatableMessage('{count} items');

        $this->assertSame('{count} items', (string) $message);
    }
}
```

---

Remember:

- Test both the untranslated (`getMessage()`) and translated (`trans()`)
  paths.
- Prefer `createStub()` over `createMock()` for a `TranslatorInterface`
  double unless you're actually asserting call counts.
- Use real fixture files and a real `Translator` for integration-level
  coverage of ICU formatting and resource discovery — it's fast and
  catches naming-convention mistakes that a stub translator can't.
- Always test with the `other` case missing and with missing parameters:
  both fail *silently*, falling back to the raw message, not by throwing.




---

## Support Project

Essential PHP Utilities

# Essential PHP Utilities

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/support/main)
![CI Workflow](https://github.com/derafu/support/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/support)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/support)
![Total Downloads](https://poser.pugx.org/derafu/support/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/support/d/monthly)

A collection of essential PHP utility classes that provide common functionality for string manipulation, array handling, file operations, date management, and more.

## Features

{.list-unstyled}
- 🔡 String manipulation utilities.
- 📚 Array handling helpers.
- 📅 Date and time management.
- 📂 File system operations.
- 📝 CSV file handling.
- 🔧 Object manipulation tools.
- 🐛 Debugging utilities.
- 🏭 Object factory and hydration.
- 🔄 Data serialization helpers.
- 🧪 Comprehensive test coverage.

## Why Derafu\Support?

This package focuses on solving specific business and data processing needs that are often overlooked by standard PHP utilities:

- **Business Date Handling**: Working days calculation, fiscal period management, and date ranges that understand holidays and weekends.
- **Robust CSV Processing**: Consistent handling of different encodings, separators, and quote styles across systems.
- **Practical Data Transformations**: Convert between different data structures (trees, tables, lists) while preserving data integrity.
- **Real-world File Operations**: Safe file handling with proper error management and automatic MIME type detection.

If your application deals with business dates, data processing, or file management, these utilities can save you from reinventing common solutions.

## Installation

Install via Composer:

```bash
composer require derafu/support
```

## Usage Examples

### String Manipulation (Str)

```php
use Derafu\Support\Str;

// Generate UUID.
$uuid = Str::uuid4();

// Replace placeholders.
$result = Str::format('Hello {{name}}!', ['name' => 'John']);

// Normalize strings for URLs.
$slug = Str::slug('Hello World!'); // "hello-world".
```

### Array Handling (Arr)

```php
use Derafu\Support\Arr;

// Auto-cast array values.
$result = Arr::cast($array);

// Convert array to tree structure.
$tree = Arr::toTree($items, 'parent_id', 'children');
```

### Date Management (Date)

```php
use Derafu\Support\Date;

// Add working days.
$newDate = Date::addWorkingDays('2024-01-15', 5, $holidays);

// Format date in Spanish.
$formatted = Date::formatSpanish('2024-01-15'); // "Lunes, 15 de enero del 2024".

// Calculate periods
$nextPeriod = Date::nextPeriod(202401); // 202402.
```

### File Operations (File)

```php
use Derafu\Support\File;

// Get file MIME type.
$mime = File::mimetype('document.pdf');

// Compress directory.
File::compress('/path/to/dir');

// Send file through browser.
File::send('document.pdf');
```

### CSV Handling (Csv)

```php
use Derafu\Support\Csv;

// Read CSV file.
$data = Csv::read('file.csv', ';');

// Generate CSV content.
$csvString = Csv::generate($data);

// Send CSV as download.
Csv::send($data, 'export.csv');
```

### Object Manipulation (Obj)

```php
use Derafu\Support\Obj;

// Fill object properties.
$object = Obj::fill($instance, $data);

// Get public properties.
$properties = Obj::getPublicProperties($instance);
```

### Object Factory and Hydration

```php
use Derafu\Support\Factory;
use Derafu\Support\Hydrator;

// Create and hydrate objects.
$instance = Factory::create($data, MyClass::class);

// Hydrate existing instance.
$hydrated = Hydrator::hydrate($instance, $data);
```

### Debug Utilities

```php
use Derafu\Support\Debug;

// Inspect variable.
$info = Debug::inspect($var, 'myVar');

// Print debug information.
Debug::print($var);
```




---

## Backbone Dispatcher Project

Safely Invoke Any Backbone Operation, From Anywhere

# Safely Invoke Any Backbone Operation, From Anywhere

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/backbone-dispatcher/main)
![CI Workflow](https://github.com/derafu/backbone-dispatcher/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/backbone-dispatcher)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/backbone-dispatcher)
![Total Downloads](https://poser.pugx.org/derafu/backbone-dispatcher/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/backbone-dispatcher/d/monthly)

Generic invocation and introspection for [Backbone](https://www.derafu.dev/docs/core/backbone) services: turn any worker's operation into something safely callable by id, with plain array parameters, from outside PHP's own type system.

## Why

A [Backbone](https://www.derafu.dev/docs/core/backbone) worker's public methods are ordinary, statically-typed PHP methods — great for an in-process PHP caller, useless for anything else. Backbone Dispatcher adds a generic invocation layer on top: it turns a string operation id (`"package.component.worker::operation"`) plus a plain associative array of parameters into a real, reflection-resolved, type-coerced method call on the right worker, and turns whatever comes back — a return value **or** an uncaught exception — into a plain, serializable shape.

That is what makes it possible for a caller with no concept of PHP reflection, PHP's type system, or PHP exceptions — Python code across a [`phpy`](https://www.derafu.dev/docs/core/backbone-bridge-python) boundary, an HTTP client through [Backbone API](https://www.derafu.dev/docs/core/backbone-api), or anything else — to invoke any Backbone operation and get back a predictable, serializable answer either way.

## Installation

```bash
composer require derafu/backbone-dispatcher
```

## The Three-Tier Dispatcher

Each tier wraps the one below it and adds exactly one thing — none of them re-implement the others' job.

### `DirectDispatcherInterface`

```php
public function dispatch(
    string $package, string $component, string $worker,
    string $operation, array $params = []
): mixed;
```

Resolves the worker from the package registry, resolves and validates the parameters against the operation's real method signature, and calls it. Returns exactly what the operation returned, as a real PHP value — no wrapping. Any `Throwable` propagates unaltered. Use this directly only when you're a PHP-only caller happy to get real domain objects back and to handle exceptions yourself.

### `TypedDispatcherInterface`

```php
public function dispatch(OperationRequestInterface $request): OperationResultInterface;
```

Adapts `DirectDispatcher` to the `OperationRequest` → `OperationResult` shape. Still does **not** catch exceptions — a thrown `Throwable` propagates unaltered, and a successful call always has `isSuccess() === true` (there is no "failure" `OperationResult` coming out of this tier, only a thrown exception). It doesn't serialize the return value either: a domain object comes back as the real object.

### `SafeDispatcherInterface`

```php
public function dispatch(OperationRequestInterface $request): OperationResultInterface;
```

Same signature as `TypedDispatcher`, but **never throws**: any `Throwable` becomes a failure `OperationResult` carrying a `ProblemDetail`. It's also the only tier that **serializes** the success value before returning it — because it's the tier meant to actually cross a process/language boundary, where an uncaught PHP exception is a dead end.

```php
$inspector = new Inspector();

$directDispatcher = new DirectDispatcher(
    $registry,
    $inspector,
    new Resolver(
        $inspector,
        new Caster(new ObjectFactoryRegistry(fallback: new FromArrayDeserializer())),
        new Validator(),
    ),
    // 4th argument, OperationPolicyInterface, defaults to AllowAllOperationPolicy — see below.
);

$safeDispatcher = new SafeDispatcher(
    new TypedDispatcher($directDispatcher),
    new Serializer(),
    environment: 'prod',
    debug: false,
);
```

There is no bundled DI wiring for this chain — wire it however your application already wires services (a `config/services.yaml`, a PHP-DI container, etc.), using the composition above as the reference.

`DirectDispatcher` invokes the resolved operation with a native named-argument call (`$worker->$operation(...$args)`) rather than a generic invoker library: `Resolver` already produces `$args` as a plain, name-keyed, fully-cast array, so nothing is left for an invoker to resolve that hasn't already been resolved.

## Controlling Which Operations Can Be Dispatched: `OperationPolicyInterface`

By default, any public method of a worker is dispatchable — the historical
behavior, kept as `AllowAllOperationPolicy`, `DirectDispatcher`'s 4th
constructor argument's default value. **This default is convenient, not
recommended**: "any public method" includes infrastructure methods a
worker gets from `JobsAwareTrait`/`HandlersAwareTrait`/`OptionsAwareTrait`
(`getJobs()`, `setOptions()`, ...) and from `ServiceInterface` itself
(`getId()`, `getName()`, `getDescription()`) — none of it business logic,
all of it just as dispatchable as a real operation while this policy is
active. `TaggedOperationPolicy` is the recommended choice for
anything reached from outside PHP: it only allows what is explicitly
tagged `#[Operation]`, which is the one real signal for "this is meant
to be exposed" — reflection alone cannot tell "a public method that
happens to exist" apart from "an operation" (see `AllowAllOperationPolicy`'s
own docblock). Two other policies ship with the package, and swapping the
one wired into `DirectDispatcher` is the only change needed — nothing else
in the three-tier chain knows a policy exists:

```php
use Derafu\BackboneDispatcher\Service\Policy\TaggedOperationPolicy;
use Derafu\BackboneDispatcher\Service\Policy\AllowListOperationPolicy;

// Only methods tagged with derafu/backbone's #[Operation] attribute.
$policy = new TaggedOperationPolicy($registry, $inspector);

// Only operations matching one of these ids. fnmatch() wildcards allowed,
// e.g. "billing.invoice.builder::*" for every operation of that worker,
// or "billing.*" for an entire package.
$policy = new AllowListOperationPolicy([
    'billing.invoice.builder::build',
    'billing.invoice.builder::cancel',
]);

$directDispatcher = new DirectDispatcher(
    $registry,
    $inspector,
    $resolver,
    $policy,
);
```

Two guards run in `DirectDispatcher::dispatch()`, in this order, before an
operation is ever resolved or invoked — so every tier built on top of it
enforces both without knowing they exist:

- Does the operation exist at all, as a public method declared on the
  worker? Independent of which policy is configured — throws
  `OperationNotFoundException` otherwise.
- Does the active `OperationPolicyInterface` allow it? Throws
  `OperationNotAllowedException` otherwise.

`Explorer` accepts the same `OperationPolicyInterface` as an optional
constructor argument, so documentation never advertises an operation the
dispatcher would then reject — without one, it lists everything, matching
`AllowAllOperationPolicy`. With one, the pruning goes all the way up the
tree: `getOperations()` drops operations it rejects, and
`getWorkers()`/`getComponents()`/`getPackages()` drop any branch left with
zero visible operations underneath — a worker nobody may call does not
show up at all, not even as an empty entry.

Implementing `OperationPolicyInterface` yourself (a single `isAllowed()`
method) covers any other rule — e.g. combining policies, or checking
against the current user's permissions.

## Dispatching an Operation

```php
use Derafu\BackboneDispatcher\ValueObject\OperationRequest;

$request = OperationRequest::fromId(
    'billing.invoice.builder::build',
    ['number' => 'F-001', 'amount' => 15000],
);

$result = $safeDispatcher->dispatch($request);

if ($result->isSuccess()) {
    $invoice = $result->getValue(); // already serialized: array/scalar, never a raw PHP object.
} else {
    $problem = $result->getProblem(); // RFC 7807-shaped ProblemDetail.
}
```

`OperationRequest::fromId()` parses `"package.component.worker::operation"` — an id with the wrong shape (missing `::`, wrong number of `.`-segments, any empty piece) throws `InvalidOperationIdException`. `::` (not a single `:`) on purpose: `derafu/backbone` already uses a single `:` for its own `.job:name`/`.handler:name`/`.strategy:name` ids — this identifier is a dispatcher-only concept, unrelated to that family, and `::` keeps it visually distinct.

## Handling Failure: `ProblemDetail`

An RFC 7807-shaped, transport-agnostic problem description — `type`/`title`/`detail`/`instance` at the top level, everything else namespaced under `extensions`:

```php
$problem->getDetail();               // The exception's own message.
$problem->getInstance();              // The failed request's id: "billing.invoice.builder::build".
$problem->getThrowable()->getClass(); // e.g. "RuntimeException" — only exposed when debug is true.
$problem->toArray();
```

```php
[
    'type' => 'about:blank',
    'title' => 'RuntimeException',
    'detail' => 'Something went wrong while running the operation.',
    'instance' => 'billing.invoice.builder::build',
    'extensions' => [
        'timestamp' => 1755500000.123456, // Unix epoch, seconds — same instant and representation as `ExecutionMetadata::getTimestamp()`.
        'data_type' => null,              // Always null on a failure — there is no value to describe.
        'environment' => 'prod',
        'debug' => false,
        'context' => [],
        'throwable' => null, // hidden outside debug mode.
    ],
]
```

The wrapped `SafeThrowable` actively scrubs sensitive data before it ever gets this far: trace frame `args` are stripped, and absolute file paths are rewritten relative to a project directory (`"project_dir:src/Foo.php"` instead of `/home/user/project/src/Foo.php`) — neither call arguments nor local filesystem layout leak to whatever is on the other side of the boundary.

## Execution Metadata: `ExecutionMetadata`

Every `OperationResultInterface` — success or failure alike — also carries `getMetadata(): ExecutionMetadataInterface`, statistics about the dispatch that produced it. A consumer decides whether, and how, to use these; this package only collects them:

```php
$metadata = $result->getMetadata();

$metadata->getStartedAt();       // "2026-01-20T10:00:00+00:00"
$metadata->getFinishedAt();
$metadata->getTimestamp();       // The same instant as getFinishedAt(), as a Unix epoch float — flexible to reuse (sorting, arithmetic), unlike the DATE_ATOM string.
$metadata->getRealTime();        // Seconds, wall-clock — the "real" of `time`.
$metadata->getUserTime();        // Seconds of CPU in user mode — the "user" of `time`.
$metadata->getSystemTime();      // Seconds of CPU in kernel mode — the "sys" of `time`.
$metadata->getMemoryUsed();      // Bytes, a delta — can be negative if the GC freed more than this dispatch allocated.
$metadata->getPeakMemory();      // Bytes, the whole process's peak up to this point — stable against that same GC noise.
$metadata->getPid();
$metadata->getLoadAverage1Min(); // Plus 5/15-minute variants — tells "slow because of this operation" apart from "slow because the system itself was saturated."
```

Assumes Linux/macOS: built on `getrusage()` and `sys_getloadavg()`, neither of which exists on Windows — no Windows support is offered.

`TypedDispatcher` and `SafeDispatcher` each measure their own scope independently, never reusing the other's numbers: `TypedDispatcher`'s metadata covers only resolving parameters and invoking the worker (via `DirectDispatcher`); `SafeDispatcher`'s covers that plus serializing the result on success, or everything up to the moment it caught the exception on failure. `ProblemDetailInterface::getTimestamp()` (above) does reuse `ExecutionMetadata`'s own reading rather than taking a second, independent one, so both always agree on the exact same instant for the same dispatch.

## What Kind of Value Was Returned: `getDataType()`

Alongside `getValue()`, a successful `OperationResultInterface` also carries `getDataType(): ?string` — the type of the value *before* `SafeDispatcher` serializes it (`get_class()` for an object, `gettype()` for a scalar/array), e.g. `"App\Entity\Invoice"` or `"integer"`. `null` on a failure, since there is nothing to describe.

```php
$result->getDataType(); // e.g. "App\Entity\Invoice" — even though getValue() is already a plain array.
```

This exists because the information is only available at the exact moment of dispatch: once `SafeDispatcher` has serialized a domain object into a plain array, its original class is gone for good — a transport built on top (like [Backbone API](https://www.derafu.dev/docs/core/backbone-api) or [Backbone Console](https://www.derafu.dev/docs/core/backbone-console)) cannot recover it afterward, so `TypedDispatcher` captures it up front and `SafeDispatcher` carries it through unchanged.

## Turning Array Data Into Real Objects

A parameter typed as a class or interface doesn't have to arrive pre-built — a plain array (or string, for things like base64-encoded certificates) is deserialized on the way in:

- Any class exposing a static `fromArray(array $data): self` works with **zero registration**, via `FromArrayDeserializer` (the conventional fallback).
- A specific class can instead get its own `DeserializerInterface` registered on `ObjectFactoryRegistry`, which takes priority over the fallback — useful when construction isn't a plain `fromArray()` (loading a certificate from either raw data or a key pair, for example).
- Union-typed parameters (`A|B`) try each candidate class in order.

```php
$resolver = new Resolver(
    new Inspector(),
    new Caster(new ObjectFactoryRegistry(
        deserializers: [Caf::class => new CafDeserializer()], // explicit, takes priority.
        fallback: new FromArrayDeserializer(),                // used for everything else.
    )),
    new Validator(),
);
```

On the way out, `Serializer` mirrors this: arrays recurse, `JsonSerializable` objects recurse into `jsonSerialize()`, objects with a `toArray()` recurse into that — so a nested domain object graph comes back from `SafeDispatcher` as plain, nested arrays.

## Discovery: `Explorer` and `Inspector`

`Explorer` walks the package registry (packages → components → workers → operations) — no `_links`/HATEOAS shaping, that's left to transports like [Backbone API](https://www.derafu.dev/docs/core/backbone-api). `Inspector` is the *only* class in the package that imports anything from `Reflection*`: every other collaborator that needs to know something about a class or a method — `Resolver`, `Explorer`, the operation policies — asks `InspectorInterface` for it instead of reflecting directly.

`getPackage()`, `getComponent()` and `getWorker()` include the real `name`/`summary`/`description` of each. `name` is read straight off the instance via `ServiceInterface::getName()` (from `derafu/backbone`, backed by its `#[Package]`/`#[Component]`/`#[Worker]` attributes) — a routing slug, never empty by omission, since it is what builds the discovery id. `summary`/`description` both come from the class' own PHPDoc: `summary` is always the PHPDoc's, verbatim (there is no `#[Worker(summary: ...)]` to prefer instead), while `description` prefers the same attribute's `description` argument first, falling back to the PHPDoc (its own description, then its summary) only when that argument was left unset — the same "explicit value, else PHPDoc" precedence `Inspector::getPublicMethods()` already gives an operation's `#[Operation]` attribute over its method's PHPDoc (see below), just one level up: a `#[Worker(...)]`-style attribute's `description` is just as easy to leave unset as an `#[Operation]`'s, and the class right below it almost always already documents itself. `getOperation(string $package, string $component, string $worker, string $operation)` looks up exactly one operation by name — unlike `getOperations()` (a listing, which silently omits what a policy rejects), a direct lookup throws: `OperationNotFoundException` if it does not exist, `OperationNotAllowedException` if the active policy rejects it.

Worth knowing: ids are dot-separated for the hierarchy (`"package"`, `"package.component"`, `"package.component.worker"`) and `::`-separated for an operation (`"package.component.worker::operation"`) — the same shape `OperationRequest`'s invocation id uses. A discovery id with an operation and an invocation id are the same string; `::` never appears anywhere except right before the operation.

`describe(?string $id = null)` is a single entry point over the rest of `ExplorerInterface`: it resolves an id to whichever of `getPackage()`/`getComponent()`/`getWorker()`/`getOperation()` matches, or, for `null` (there is no single "root" resource to look up), `{'summary' => ..., 'description' => ..., 'packages' => getPackages()}`:

```php
$explorer->describe();                                              // {'summary' => ..., 'description' => ..., 'packages' => getPackages()}
$explorer->describe('billing');                                     // getPackage('billing')
$explorer->describe('billing.invoice');                              // getComponent(...)
$explorer->describe('billing.invoice.builder');                      // getWorker(...)
$explorer->describe('billing.invoice.builder::createDraft');         // getOperation(...)
```

`summary`/`description` are the package registry's own PHPDoc — kept alongside `packages` rather than replacing it, the same way every other level keeps its own `summary`/`description` alongside its children (`components`/`workers`/`operations`). `tree(null)` nests the same way, just with each package in `packages` deeply nested instead of the shallow `getPackage()` shape `describe(null)` holds.

More than 3 dot-separated segments before an operation, an empty segment, or an empty operation after `::` all throw `InvalidDiscoveryIdException` — a different exception from `InvalidOperationIdException` on purpose, even though the shape is identical once an operation is present: `describe()` also accepts a *partial* id (just a package, or a package and component) to browse with, something `OperationRequest::fromId()` (always a complete, 4-part invocation) never allows.

`tree(?string $id = null)` resolves the same id the same way, but nests every level's children instead of stopping at that one node — a worker comes back with its own `operations` nested right in:

```php
$explorer->tree('billing.invoice.builder');
// [
//     'id' => 'billing.invoice.builder',
//     'name' => 'builder',
//     'summary' => 'Invoice Builder.',
//     'description' => '...',
//     'operations' => [
//         ['id' => 'billing.invoice.builder::build', 'name' => 'build', /* ... */],
//         ['id' => 'billing.invoice.builder::cancel', 'name' => 'cancel', /* ... */],
//     ],
// ]
```

A package nests its `components`, each of those its own `workers`, each of those its own `operations` — operations are always the leaves, nothing nests under them, so an operation id resolves exactly like `describe()`. The same policy-based pruning as the rest of `Explorer` applies at every level: a worker left with zero visible operations does not appear in its component's `workers`, and so on up to the root.

For `null`, same as `describe(null)`: `{'summary' => ..., 'description' => ..., 'packages' => [...]}`, except each package in `packages` is deeply nested here instead of the shallow `getPackage()` shape `describe(null)` holds:

```php
$explorer->tree();
// [
//     'summary' => '...',       // the package registry's own PHPDoc, first sentence.
//     'description' => '...',   // the rest of the same PHPDoc.
//     'packages' => [
//         ['id' => 'billing', 'name' => 'billing', 'summary' => '...', 'description' => '...', 'components' => [/* ... */]],
//     ],
// ]
```

Every other level in this tree is `{id, name, summary, description, <children>}`; the root is the same shape minus `id`/`name` (a registry is not a `ServiceInterface` with an identity, unlike a package/component/worker) — `summary`/`description` still have the same honest source as everywhere else, the registry class' own PHPDoc, so there is no reason for them to be missing just because `id`/`name` do not apply.

> [!TIP] Operation ≠ Job
>
> An "operation" here is simply a public method of a worker, discovered via reflection. It has nothing to do with Backbone's own formally-registered `JobInterface`/`#[Job]` concept — a worker's operation may use zero, one, or several real jobs internally, and the dispatcher neither knows nor cares.

### Documenting an Operation: `#[Operation]`

`derafu/backbone`'s [`#[Operation]` attribute](/docs/core/backbone/operations) (see [Controlling Which Operations Can Be Dispatched](#controlling-which-operations-can-be-dispatched-operationpolicyinterface) above) can also carry documentation reflection/PHPDoc cannot produce on its own:

```php
use Derafu\Backbone\Attribute\Operation;

#[Operation(
    name: 'Create a draft invoice',       // overrides the PHPDoc summary, if given.
    description: 'Builds a draft from the given data, without emitting it.', // overrides the PHPDoc description.
    parameters: [
        'number' => ['example' => 'F-001'],
        'amount' => ['example' => 15000, 'description' => 'Amount in the smallest currency unit.'],
    ],
    results: [
        'success' => ['description' => 'The created draft.', 'example' => ['id' => 'DR-001']],
        MissingParameterException::class => ['description' => 'A required parameter was not provided.'],
    ],
)]
public function build(string $number, int $amount): array
```

`Inspector::getPublicMethods()` merges whatever is given here on top of what reflection and PHPDoc already produced, before any policy or documentation consumer ever sees it — see [Operations](https://www.derafu.dev/docs/core/backbone/operations) for the full attribute reference (every property, what each one means, and why it's not a service-defining attribute like `#[Job]`/`#[Handler]`/`#[Strategy]`).

### Caching Reflection: `CachedInspector`

`getClassDoc()` and `getPublicMethods()` parse PHPDoc for every method of a class — the same result every time for a given class, until the next deploy. `CachedInspector` decorates any `InspectorInterface` with a PSR-6 `CacheItemPoolInterface`, caching exactly those two calls:

```php
use Derafu\BackboneDispatcher\Service\Reflection\CachedInspector;
use Derafu\Cache\Adapter\PhpFilesCache;

$inspector = new CachedInspector(
    new Inspector(),
    new PhpFilesCache('backbone_dispatcher', '/var/cache/backbone_dispatcher'), // any PSR-6 Psr\Cache\CacheItemPoolInterface.
    ttl: 3600,
);
```

There is no default pool: `$cache` must always be given explicitly — `derafu/cache`'s `PhpFilesCache`/`FilesystemCache` (shown above), any other PSR-6 implementation (Redis, APCu, an in-memory one for tests), or `derafu/cache`'s `LocalCacheFactory` if the backend is itself a runtime choice. If caching isn't wanted at all, the simplest option is not using `CachedInspector` — inject the plain `Inspector` wherever `InspectorInterface` is expected instead, no flag needed anywhere.

Set `ttl: 0` to skip the pool on every call without swapping which `InspectorInterface` is injected — useful when the choice comes from runtime configuration rather than wiring. There is no invalidation logic inside the package on purpose: whether an entry outlives a deploy is entirely up to which pool gets injected — a file-based pool under the system temp directory is exactly as ephemeral as the process using it; a shared backend (Redis, APCu) is the caller's to flush, or not, as part of their own deploy.

`isOperation()`, `hasOperationAttribute()` and `getOperationParameters()` are deliberately **not** cached, in `CachedInspector` or otherwise: they never parse PHPDoc, they run on every single dispatch regardless of which tier or policy is used, and reading them through a cache backend could easily cost more than the reflection they would replace.

## Never Failing While Exploring: `SafeExplorer`

`Explorer`/`ExplorerInterface` throw — `OperationNotFoundException`, `OperationNotAllowedException`, `InvalidDiscoveryIdException`, or any of `derafu/backbone`'s own "not found" exceptions when a given package/component/worker doesn't exist. `SafeExplorer` wraps any `ExplorerInterface` the same way `SafeDispatcher` wraps `TypedDispatcher`: no `Throwable` ever crosses back to the caller — every one of `ExplorerInterface`'s 10 public methods instead returns a `DiscoveryResultInterface`:

```php
use Derafu\BackboneDispatcher\Service\Discovery\SafeExplorer;

$safeExplorer = new SafeExplorer($explorer, environment: 'prod', debug: false);

$result = $safeExplorer->tree('billing.invoice.builder::build');

if ($result->isSuccess()) {
    $operation = $result->getValue();
} else {
    $problem = $result->getProblem(); // Same RFC 7807-shaped ProblemDetail as SafeDispatcher's.
}
```

`DiscoveryResultInterface` has the same `isSuccess()`/`getValue()`/`getProblem()` shape as `OperationResultInterface`, but is a deliberately separate type: one is about dispatching an operation, the other about exploring the package tree, and keeping them independent means either one is free to grow its own data later without dragging the other along. It has no `getMetadata()`: `SafeExplorer` does not measure `ExecutionMetadata`.

## Exceptions

```
InvalidOperationIdException     — malformed "package.component.worker::operation" id.
InvalidDiscoveryIdException     — malformed discovery id passed to Explorer::describe().

ResolverException
├── InvalidParameterTypeException — a scalar parameter has the wrong native type.
└── MissingParameterException     — a required parameter is absent.

ObjectFactoryException
├── ClassNotFoundException            — fromArray() target class doesn't exist.
├── FromArrayMethodNotFoundException  — target class has no static fromArray().
└── NoDeserializerFoundException      — no registered deserializer, and the fallback failed too.

OperationNotFoundException  — the operation does not exist as a public method of the worker.
OperationNotAllowedException — the operation exists, but the active OperationPolicyInterface rejects it.
```

Every exception exposes a semantic static factory (`InvalidOperationIdException::forId()`, `MissingParameterException::forParameter()`, etc.) instead of a public constructor, and is translatable via [`derafu/translation`](https://www.derafu.dev/docs/core/translation).

## Requirements

PHP 8.5+. Depends on [`derafu/backbone`](https://www.derafu.dev/docs/core/backbone), [`derafu/cache`](https://www.derafu.dev/docs/core/cache) and [`derafu/translation`](https://www.derafu.dev/docs/core/translation).




---

## Backbone API Project

HTTP API With Zero Per-Operation Controllers

# HTTP API With Zero Per-Operation Controllers

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/backbone-api/main)
![CI Workflow](https://github.com/derafu/backbone-api/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/backbone-api)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/backbone-api)
![Total Downloads](https://poser.pugx.org/derafu/backbone-api/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/backbone-api/d/monthly)

Turns every operation of every worker registered in a [Backbone](https://www.derafu.dev/docs/core/backbone) package registry into an HTTP endpoint automatically — no per-operation controller code, self-documenting as HATEOAS resources and an OpenAPI 3.1 spec.

## Why

Instead of writing `POST /invoices/build` → `InvoiceController::build()` by hand for each operation, you write one generic route pointing at one controller, and the URL path itself tells the package which worker method to call. The actual resolution and invocation is delegated entirely to [`derafu/backbone-dispatcher`](https://www.derafu.dev/docs/core/backbone-dispatcher), which is transport-agnostic — this package only deals with the HTTP-specific concerns: parsing the route, listing packages/components/workers as browsable resources, serving OpenAPI documentation, and extracting parameters from the request body.

## Installation

```bash
composer require derafu/backbone-api
```

There is no bundled route table or DI wiring — wiring `Dispatcher` and a controller into your framework's routes and container is left to your application.

## Routing Convention

`Router::parse()` resolves an incoming request into up to four path segments:

```
/[api/]:package/:component/:worker/:operation
```

The `/api` prefix is optional and stripped if present — `/api/billing/document` and `/billing/document` resolve identically. A path with more than 4 segments throws `InvalidRouteException`. Trailing segments are simply omitted rather than required, which is what drives the dispatch behavior below.

Two special one-segment paths are intercepted before being treated as a package name:

- Empty path or `index` → the root HATEOAS listing.
- `openapi-docs.json` → the generated OpenAPI document.

```php
public function dispatch(ServerRequestInterface $request): mixed
{
    $route = $this->router->parse($request);

    return match (true) {
        $route->getId() === 'index' || $route->getId() === null => $this->handleRoot(),
        $route->getId() === 'openapi-docs.json' => $this->documenter->document(),
        $route->getComponent() === null => $this->handlePackage($route->getPackage()),
        $route->getWorker() === null => $this->handleComponent($route->getPackage(), $route->getComponent()),
        $route->getOperation() === null => $this->handleWorker(...),
        default => $this->handleOperation($request, ...),
    };
}
```

So `GET /api/billing` lists `billing`'s components, `GET /api/billing/document` lists that component's workers, and only a full 4-segment path actually invokes an operation.

## Invoking an Operation

Every operation is invoked with the parameters read from the JSON request body's `parameters` key — nothing else (no query string, no path params beyond routing):

```
POST /api/billing/invoice/builder/build
Content-Type: application/json
Accept: application/json

{ "parameters": { "number": "F-001", "amount": 15000 } }
```

```php
$requestContent = json_decode($request->getBody()->getContents(), true);
$params = $requestContent['parameters'] ?? [];

$operationRequest = new OperationRequest($package, $component, $worker, $operation, $params);

return $this->dispatcher->dispatch($operationRequest); // SafeDispatcherInterface — never throws.
```

`handleOperation()` returns the `OperationResultInterface` itself, unwrapped — `AbstractController` (below) is the single place that turns it into the actual response, since it is also the place that already builds every other response shape this package produces.

## Response Shape

A successful, JSON-wanting request (`Accept: application/json` or `*/*`) gets wrapped in a small envelope — for an operation result, `meta.timestamp`/`meta.data_type` come straight from `OperationResultInterface::getMetadata()->getTimestamp()`/`::getDataType()` (see [Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher#what-kind-of-value-was-returned-getdatatype)), not recomputed from the already-serialized value:

```json
{
    "meta": { "timestamp": 1755500000.123456, "data_type": "integer" },
    "data": 12
}
```

Two results bypass the envelope entirely: a PSR-7 `ResponseInterface` returned by the underlying dispatch (passed through unchanged), and the OpenAPI document itself (detected by its own `openapi` key). If the request doesn't ask for JSON, the raw result is returned unwrapped for the framework layer to render however it sees fit.

### Failure: a Real Status Code, Never a Silent 200

`SafeDispatcherInterface` never throws, so `AbstractController` is also the one place that decides what a failed operation actually looks like to the client — a real PSR-7 response (built via an injected `Psr\Http\Message\ResponseFactoryInterface`, so this package stays implementation-agnostic about which PSR-17 factory produces it) carrying:

- The resolved HTTP status, from `HttpStatusResolver` (below) — never a default `200` masking a real failure.
- The exact same `ProblemDetailInterface::toArray()` body [Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher#handling-failure-problemdetail) and [Backbone Console](https://www.derafu.dev/docs/core/backbone-console) already produce — the same failure looks the same across every transport.

```php
$problem = $result->getProblem();
$status = $this->httpStatusResolver->resolve($problem->getThrowable()->getClass());

$response = $this->responseFactory
    ->createResponse($status)
    ->withHeader('Content-Type', 'application/json')
;
$response->getBody()->write((string) json_encode($problem->toArray()));
```

### `HttpStatusResolver`: Mapping Exceptions to Status Codes

Shared by two consumers: `AbstractController` above (a real failure's actual status) and `Documenter` below (what to document for each `#[Operation(results: ...)]` scenario) — the same resolution, kept in one place instead of two copies that could drift apart. Only `derafu/backbone-dispatcher`'s own 7 generic exceptions are mapped (the same 7 [Backbone Console](https://www.derafu.dev/docs/core/backbone-console#exitcoderesolverinterface-mapping-exceptions-to-codes)'s `DefaultExitCodeResolver` maps, mirroring that same split) — anything else, including a business-specific exception, falls back to `500`:

| Status | Exception |
| --- | --- |
| `200` | (`'success'`) |
| `403` | `OperationNotAllowedException` |
| `422` | `MissingParameterException`, `InvalidParameterTypeException`, `NoDeserializerFoundException`, `ClassNotFoundException`, `FromArrayMethodNotFoundException` |
| `500` | anything else, including `OperationNotFoundException` and any business-specific exception |

There is no built-in way to extend this mapping with a project's own business exceptions yet — unlike `DefaultExitCodeResolver`, `HttpStatusResolver` is not currently designed to be subclassed for that. A project needing its own status codes today would wrap or replace it in its own DI wiring.

## Autodiscovery

One shared criterion for what counts as "visible", applied consistently across both surfaces — because both are walked from the exact same source:

**`Explorer`** composes over `derafu/backbone-dispatcher`'s own `ExplorerInterface` rather than reimplementing its walk, only adding HATEOAS `_links` on top of whatever it returns — `GET /api/billing/document/builder` returns the worker's `_links` plus its operations. Every id, name, description and policy-based visibility rule (see [Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher#controlling-which-operations-can-be-dispatched-operationpolicyinterface)) comes straight from the delegate: with a policy wired into it, a worker nobody may call does not show up here either.

**`Documenter`** generates the OpenAPI 3.1 document served at `GET /api/openapi-docs.json`, walked from `Explorer::tree()` — the exact same nested, policy-pruned structure `Explorer` itself is built on, not a separate traversal of the package registry. This used to not be true: `Documenter` had its own, independent notion of "visible" (any method tagged with Backbone's `#[Operation]` attribute, optionally narrowed by a *second*, separately-injected policy instance), which could silently drift from what a real `DirectDispatcher` would actually accept — an operation the active `OperationPolicyInterface` allowed, but nobody had gotten around to tagging, was dispatchable and browsable yet absent from the spec, understating the real attack surface. There is no way to configure `Documenter` differently from `Explorer` anymore: whatever `OperationPolicyInterface` was wired into the `ExplorerInterface` `Explorer` composes over is the one and only thing that decides what gets documented.

`#[Operation]` still exists and is still useful — for overriding a parameter's reflected type/description/example, or the operation's own name/description, when the reflected PHPDoc isn't enough (see [Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher#documenting-an-operation-operation)) — it just no longer gates *whether* something gets documented, only how it looks once it is. If you want a real, non-`#[Operation]`-tagged public method to disappear from both `Explorer` and `Documenter` at once, that is exactly what [`TaggedOperationPolicy`](https://www.derafu.dev/docs/core/backbone-dispatcher#controlling-which-operations-can-be-dispatched-operationpolicyinterface) is for — wired once, where the dispatch chain itself is built, never in `backbone-api`.

Every documented operation is generated as a single OpenAPI `post` entry (there's no GET/PUT/DELETE distinction), and its request/response schema is built from the reflected parameter types, following the same type-name vocabulary as `backbone-dispatcher`'s `Caster::resolveType()` (`string`, `number`, `integer`, `boolean`, `array`, `object`).

> [!TIP] Operation ≠ Job
>
> Same terminology note as [Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher#discovery-explorer-and-inspector): an "operation" here is any public method found via reflection, unrelated to Backbone's own `JobInterface`/`#[Job]` concept.

## Requirements

PHP 8.5+. Depends on [`derafu/backbone`](https://www.derafu.dev/docs/core/backbone), [`derafu/backbone-dispatcher`](https://www.derafu.dev/docs/core/backbone-dispatcher), `psr/http-message`, and `psr/http-factory` (for building the real failure response — a concrete PSR-17 implementation, e.g. `nyholm/psr7`, is the consuming application's to provide).




---

## Backbone Bridge Python Project

Call Any Backbone-Dispatcher Library From Python

# Call Any Backbone-Dispatcher Library From Python

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/backbone-bridge-python/main)
![CI Workflow](https://github.com/derafu/backbone-bridge-python/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/backbone-bridge-python)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/backbone-bridge-python)
![PyPI version](https://img.shields.io/pypi/v/derafu-backbone-bridge)
![PyPI downloads](https://img.shields.io/pypi/dm/derafu-backbone-bridge)

Generic Python bridge for any [`derafu/backbone-dispatcher`](https://www.derafu.dev/docs/core/backbone-dispatcher)-based PHP library, via [`swoole/phpy`](https://github.com/swoole/phpy) — without a caller ever having to know `phpy` exists.

## Why

`derafu/backbone-dispatcher`'s `SafeDispatcherInterface` already turns any Backbone operation into something that never throws a raw PHP exception and always returns a serializable value — exactly the contract a foreign-language caller needs. `swoole/phpy` lets Python call into a real, embedded PHP interpreter in the same process. This package is the glue between the two: it boots a real `SafeDispatcherInterface` and exposes it as `dispatch(operation_id, **params)`, translating PHP exceptions into typed Python exceptions on the way back.

It knows nothing about any specific library. A specific PHP library's own bridge subclasses `GenericDispatcher` (and, for exploring a package tree, `GenericExplorer` — see [Exploring the Package Tree](#exploring-the-package-tree-genericexplorer) below), pre-wiring how its own `SafeDispatcherInterface`/`SafeExplorerInterface` gets booted — this is exactly what this package's own test suite does, against a real, minimal PHP fixture (no mocks):

```python
class ExampleDispatcher(GenericDispatcher):
    _BOOTSTRAP_CLASS = 'Derafu\\TestsBackboneBridgePython\\Fixture\\Bootstrap'

    def __init__(self, autoload_path=None):
        super().__init__(self._BOOTSTRAP_CLASS, autoload_path=autoload_path)
```

## Installation

```bash
pip install derafu-backbone-bridge
```

`phpy` itself is **not** a normal pip dependency and never will be resolvable from PyPI: it requires a PHP build with `--enable-embed`, so it must already be present system-wide wherever this package runs — see [Docker with Python and Caddy](https://www.derafu.dev/docs/sysadmin/docker-python-caddy-server) for a ready-made image with an optional `PHPY_ENABLED` build. Install this package into a virtualenv created with `--system-site-packages` so it can see the system `phpy`.

> [!WARNING] PyPI has an unrelated package also named `phpy`
>
> There is a long-abandoned, unrelated package on PyPI called `phpy` ("call legacy PHP functions from Python", 2013). It is **not** `swoole/phpy`. This package deliberately does not declare `phpy` as a dependency at all, specifically so `pip install` never silently resolves that decoy instead of the real, system-provided one.

## Usage

```python
from derafu_backbone_bridge import GenericDispatcher

dispatcher = GenericDispatcher(
    'Derafu\\TestsBackboneBridgePython\\Fixture\\Bootstrap',
    autoload_path='/path/to/backbone-bridge-python/tests/php/vendor/autoload.php',
)

result = dispatcher.dispatch(
    'example_package.example_component.example_worker::sum',
    a=5, b=7,
)
result.value      # 12
result.data_type  # "integer" — `gettype()`/`get_class()` of `value`, before PHP serializes it.
result.metadata   # ExecutionMetadata — see below.
```

`operation_id` uses the same `"package.component.worker::operation"` format as `OperationRequest::fromId()` on the PHP side. Every keyword argument becomes a named operation parameter — `b` falls back to the operation's own PHP default (`10`) when omitted, exactly as it would for a direct PHP caller.

`dispatch()` always returns an `OperationResult` — never the bare value — because the PHP side's own `OperationResultInterface::getMetadata()` is never optional either: a successful dispatch always has execution statistics attached, so the Python side always has somewhere to put them.

```python
@dataclass(frozen=True)
class OperationResult:
    value: Any
    metadata: ExecutionMetadata
    data_type: str
```

`data_type` mirrors PHP's `OperationResultInterface::getDataType()` — never `None` here, unlike the PHP interface: a failed dispatch never reaches `OperationResult` at all (it raises instead, see [Handling Errors](#handling-errors)), so there is no failure case for it to be `None` for.

`ExecutionMetadata` mirrors PHP's `ExecutionMetadataInterface` field for field, just in `snake_case`:

```python
result.metadata.started_at          # "2026-01-20T10:00:00+00:00"
result.metadata.finished_at
result.metadata.timestamp           # 1755500000.123456 — same moment as `finished_at`, as a Unix epoch float.
result.metadata.real_time           # Seconds, wall-clock — the "real" of `time`.
result.metadata.user_time           # Seconds of CPU in user mode — the "user" of `time`.
result.metadata.system_time         # Seconds of CPU in kernel mode — the "sys" of `time`.
result.metadata.memory_used         # Bytes, a delta — can be negative if the GC freed more than this dispatch allocated.
result.metadata.peak_memory         # Bytes, the whole process's peak up to this point.
result.metadata.pid
result.metadata.load_average_1min   # Plus 5min/15min variants.
```

Assumes Linux/macOS, same as the PHP side: built on `getrusage()`/`sys_getloadavg()`, neither of which exists on Windows — no Windows support is offered.

### Where the PHP autoloader lives

`GenericDispatcher` resolves the PHP autoloader to `phpy.include()` from, in order: an explicit `autoload_path` argument, or the `BACKBONE_DISPATCHER_AUTOLOAD` environment variable. Exactly one variable is used regardless of which library is being bridged, because in practice a given process only ever hosts one bridge:

```bash
export BACKBONE_DISPATCHER_AUTOLOAD=/path/to/backbone-bridge-python/tests/php/vendor/autoload.php
```

```python
dispatcher = ExampleDispatcher()  # No path needed if the env var is set.
```

Neither of those is `phpy`-specific knowledge — they're just "where does my dependency live," the same kind of configuration any bridge would need regardless of the underlying interop mechanism.

## Exploring the Package Tree: `GenericExplorer`

`GenericExplorer` mirrors `GenericDispatcher`'s boot mechanism, wrapping a real `SafeExplorerInterface` instead of a `SafeDispatcherInterface`, with the same 10 methods `SafeExplorerInterface` has on the PHP side:

```python
from derafu_backbone_bridge import GenericExplorer

explorer = GenericExplorer(
    'Derafu\\TestsBackboneBridgePython\\Fixture\\Bootstrap',
    bootstrap_method='bootExplorer',
    autoload_path='/path/to/backbone-bridge-python/tests/php/vendor/autoload.php',
)

explorer.get_packages()
explorer.get_components('example_package')
explorer.get_workers('example_package', 'example_component')
explorer.get_operations('example_package', 'example_component', 'example_worker')
explorer.get_package('example_package', with_components=True)
explorer.get_component('example_package', 'example_component', with_workers=True)
explorer.get_worker('example_package', 'example_component', 'example_worker', with_operations=True)
explorer.get_operation('example_package', 'example_component', 'example_worker', 'sum')
explorer.describe('example_package.example_component.example_worker')
explorer.tree('example_package.example_component.example_worker')
```

Every method returns a plain `dict`/`list` (or scalar), same shape `derafu/backbone-dispatcher`'s `ExplorerInterface` produces, or raises a `BackboneBridgeError` — see [Handling Errors](#handling-errors) below, `GenericExplorer` uses the exact same mapping. Unlike `GenericDispatcher.dispatch()`, none of these return an `OperationResult`: there is no `ExecutionMetadata` to attach, since `SafeExplorerInterface` does not measure one.

## Handling Errors

A failed operation raises `BackboneBridgeError` or one of its subclasses — never a raw `phpy` call failure, and never a PHP exception object:

```python
from derafu_backbone_bridge import MissingParameterError

try:
    dispatcher.dispatch('example_package.example_component.example_worker::sum')
except MissingParameterError as e:
    print(e.php_class)  # "Derafu\BackboneDispatcher\Exception\MissingParameterException"
```

Every `BackboneBridgeError` carries the full `Problem` behind it (in `.problem`), not just a class name and a message:

```python
except MissingParameterError as e:
    e.problem.detail                 # The exception's own message.
    e.problem.instance                # "example_package.example_component.example_worker::sum"
    e.problem.timestamp               # 1755500000.123456 — Unix epoch float, same as `ExecutionMetadata.timestamp`.
    e.problem.throwable.php_class     # Same as `.php_class` below — a read-only shortcut to this.
    e.problem.throwable.file
    e.problem.throwable.line
    e.problem.throwable.trace
    e.metadata                        # ExecutionMetadata of the failed attempt, or `None` — see below.
```

`Problem`/`SafeThrowable` mirror PHP's `ProblemDetailInterface`/`SafeThrowableInterface`, in `snake_case`. Unlike PHP's own `ProblemDetail::toArray()`, `.throwable` here is **always** populated, regardless of whether the underlying `SafeDispatcher` was booted with `debug=True` or `False`: that flag only gates what PHP embeds when *serializing* a problem for an untrusted HTTP consumer, and does not apply to this bridge — `phpy` is an in-process, same-machine, trusted boundary.

`.metadata` is `None` when the failure came from `GenericExplorer` rather than `GenericDispatcher` — `SafeExplorerInterface` does not measure `ExecutionMetadata` (see [Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher#never-failing-while-exploring-safeexplorer)), so there is honestly none to give in that case; a dispatch failure always has one, and its `.timestamp` is the exact same clock reading as `.problem.timestamp` — not two independent captures.

`.php_class` is a read-only shortcut to `.problem.throwable.php_class` — it exists for backward-compatible ergonomics, not stored data:

```python
from derafu_backbone_bridge import BackboneBridgeError

try:
    dispatcher.dispatch('example_package.example_component.example_worker::fail')
except BackboneBridgeError as e:
    print(e.php_class)  # "RuntimeException" — a plain, unmapped PHP exception.
```

The hierarchy mirrors `derafu/backbone` and `derafu/backbone-dispatcher`'s own exceptions one level deep (`ServiceNotFoundError`/`PackageNotFoundError`/`ComponentNotFoundError`/…, `ResolverError`/`InvalidParameterTypeError`/…), so callers can catch broadly or narrowly exactly as they would in PHP. Anything unmapped still raises `BackboneBridgeError`.

A specific library's own domain exceptions are registered by its own bridge, not by this package:

```python
dispatcher.exceptions.register('App\\Exception\\SomeDomainException', SomeDomainError)
```

Separately, a failure while booting PHP itself (a missing autoloader, a broken dependency, a bootstrap class or method that doesn't exist) raises `BootstrapError` — never a raw `phpy` error either, but also never confused with an operation failure, since booting happens before any `SafeDispatcherInterface` exists to produce a `Problem` from.

## Architecture

`phpy` is only ever imported by `GenericDispatcher`, `GenericExplorer`, and the internal `_phpy_conversions` module they both share for turning a live PHP object into a plain Python one — never by the tests, a specific library's own bridge, or the application consuming it. Building one specific library's bridge means subclassing `GenericDispatcher`/`GenericExplorer` with its `bootstrap_class`, and never touching `phpy` directly:

```python
class GenericDispatcher:
    _AUTOLOAD_PATH_ENV = 'BACKBONE_DISPATCHER_AUTOLOAD'

    def __init__(
        self,
        bootstrap_class: str,
        bootstrap_method: str = 'boot',
        bootstrap_args: tuple = (),
        exception_registry: ExceptionRegistry | None = None,
        autoload_path: str | None = None,
    ) -> None: ...

    def dispatch(self, operation_id: str, **params) -> OperationResult: ...
```

`ExceptionRegistry` (the PHP-class-name → Python-exception mapping, via `raise_for(problem, metadata=None)`), and the `OperationResult`/`Problem`/`SafeThrowable`/`ExecutionMetadata` dataclasses themselves, are all separate, independent components that never touch `phpy` — plain, immutable data holders that can be built, tested and reasoned about with no PHP interpreter involved at all. `_phpy_conversions` is the one place that bridges the two worlds, turning a live PHP object into one of those.

## Requirements

Python 3.14+. `phpy` itself requires PHP built with `--enable-embed`.




---

## Mail Project

Derafu Mail

# Derafu Mail




---

### Introduction

Elegant orchestration of email communications for PHP

# Elegant orchestration of email communications for PHP

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/mail/main)
![CI Workflow](https://github.com/derafu/mail/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/mail)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/mail)
![Total Downloads](https://poser.pugx.org/derafu/mail/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/mail/d/monthly)

A flexible PHP email library, built on Derafu Backbone architecture, that leverages other libraries and orchestrates the entire sending and receiving process.

## Overview

Derafu Mail provides a robust, extensible framework for sending and receiving emails in PHP applications. Built on the [Derafu Backbone architecture](https://www.derafu.dev/docs/core/backbone), it offers a clean, maintainable structure with clear separation of concerns.

## Features

- **Clean Architecture**: Follows the Derafu Backbone hierarchical structure.
- **Sending Emails**: SMTP support with easy extensibility for other transport methods.
- **Receiving Emails**: IMAP support with customizable search criteria and filtering.
- **Flexible Configuration**: Comprehensive options for both sending and receiving.
- **Robust Error Handling**: Proper exception handling throughout the library.
- **Attachment Management**: Support for both sending and receiving attachments.
- **Strategy Pattern**: Easily swap out sending/receiving implementations.

## Installation

Install the package via Composer:

```bash
composer require derafu/mail
```

## Quick Start

### Sending Emails

```php
use Derafu\Backbone\Contract\PackageRegistryInterface;
use Derafu\Mail\Model\Message;
use Derafu\Mail\Model\Envelope;
use Derafu\Mail\Model\Postman;
use Symfony\Component\Mime\Address;

// Find the package registry using dependency injection and get a $senderWorker
// Also you can inject directly the SenderWorkerInterface wherever you want.
$packageRegistry = $container->get(PackageRegistryInterface::class);
$mailPackage = $packageRegistry->getPackage('mail');
$exchangeComponent = $mailPackage->getExchangeComponent();
$senderWorker = $exchangeComponent->getSenderWorker();

// Create a message.
$message = new Message();
$message->subject('Hello World')
    ->text('This is a plain text message')
    ->html('<h1>Hello World</h1><p>This is an HTML message</p>')
    ->from(new Address('sender@example.com', 'Sender Name'))
    ->to(new Address('recipient@example.com', 'Recipient Name'));

// Create an envelope and add the message.
$envelope = new Envelope(
    new Address('sender@example.com', 'Sender Name'),
    [new Address('recipient@example.com', 'Recipient Name')]
);
$envelope->addMessage($message);

// Create a postman with SMTP configuration.
$postman = new Postman([
    'strategy' => 'smtp',
    'transport' => [
        'host' => 'smtp.example.com',
        'port' => 587,
        'encryption' => 'tls',
        'username' => 'your_username',
        'password' => 'your_password',
    ],
]);
$postman->addEnvelope($envelope);

// Send the email.
$envelopes = $senderWorker->send($postman);
```

### Receiving Emails

```php
use Derafu\Backbone\Contract\PackageRegistryInterface;
use Derafu\Mail\Model\Postman;

// Find the package registry using dependency injection and get a $receiverWorker
// Also you can inject directly the ReceiverWorkerInterface wherever you want.
$packageRegistry = $container->get(PackageRegistryInterface::class);
$mailPackage = $packageRegistry->getPackage('mail');
$exchangeComponent = $mailPackage->getExchangeComponent();
$receiverWorker = $exchangeComponent->getReceiverWorker();

// Create a postman with IMAP configuration.
$postman = new Postman([
    'strategy' => 'imap',
    'transport' => [
        'host' => 'imap.example.com',
        'port' => 993,
        'encryption' => 'ssl',
        'username' => 'your_username',
        'password' => 'your_password',
        'mailbox' => 'INBOX',
        'search' => [
            'criteria' => 'UNSEEN',
            'markAsSeen' => true,
            'attachmentFilters' => [
                'extension' => ['pdf', 'doc', 'docx'],
            ],
        ],
    ],
]);

// Receive emails.
$envelopes = $receiverWorker->receive($postman);

// Process received emails.
foreach ($envelopes as $envelope) {
    foreach ($envelope->getMessages() as $message) {
        echo "Subject: " . $message->getSubject() . PHP_EOL;
        echo "From: " . $message->getFrom()[0]->getAddress() . PHP_EOL;
        echo "Body: " . $message->getTextBody() . PHP_EOL;

        // Process attachments.
        foreach ($message->getAttachments() as $attachment) {
            file_put_contents('/path/to/save/' . $attachment->getFilename(), $attachment->getBody());
        }
    }
}
```

## Extending with New Strategies

The library is designed to be easily extended with new sending or receiving strategies:

1. Create a new strategy class implementing `SenderStrategyInterface` or `ReceiverStrategyInterface`.
2. Tag it with the appropriate attribute.

Example:
```php
use Derafu\Backbone\Attribute\Strategy;
use Derafu\Mail\Component\Exchange\Worker\Sender\Strategy\Abstract\AbstractMailerStrategy;
use Derafu\Mail\Component\Exchange\Worker\Sender\Strategy\Contract\SenderStrategyInterface;

#[Strategy(name: 'mailgun', worker: 'sender', component: 'exchange', package: 'mail')]
class MailgunStrategy extends AbstractMailerStrategy implements SenderStrategyInterface
{
    // Implementation of SenderStrategyInterface that leverages AbstractMailerStrategy.
}
```

## Architecture

Derafu Mail follows the Derafu Backbone architecture:

- **Package**: MailPackage - The main entry point.
- **Component**: ExchangeComponent - Handles email exchange.
- **Workers**: SenderWorker and ReceiverWorker - Handle sending and receiving.
- **Handlers**: SendHandler and ReceiveHandler - Orchestrate the process.
- **Strategies**: Implement different methods of sending or receiving.




---

### Architecture

Derafu Mail Architecture

# Derafu Mail Architecture

This guide explains the architecture of the Derafu Mail library, which is built on the Derafu Backbone architectural framework. Understanding this architecture will help you effectively use and extend the library.

## Architectural Overview

Derafu Mail follows a hierarchical architecture that separates concerns into distinct layers, each with specific responsibilities:

1. **Package Layer**: The entry point and container for all components.
2. **Component Layer**: Functional modules within the package.
3. **Worker Layer**: Task executors within components.
4. **Handler Layer**: Process orchestrators that coordinate strategies.
5. **Strategy Layer**: Specific implementations of mail operations.
6. **Model Layer**: Domain models representing email-related entities.

![Derafu Mail Architecture](https://www.derafu.dev/img/diagrams/content/docs/core/mail/derafu-mail-architecture.svg)

## Package Layer

The `MailPackage` serves as the entry point for the entire library, following the Package pattern from Derafu Backbone.

```php
#[Package(name: 'mail')]
class MailPackage extends AbstractPackage implements MailPackageInterface
```

**Responsibilities**:

- Provides access to components (currently just `ExchangeComponent`).
- Acts as the root of the dependency tree.
- Maintains registry information for service discovery.

## Component Layer

The `ExchangeComponent` represents a specific functional area within the mail domain, handling both sending and receiving of emails.

```php
#[Component(name: 'exchange', package: 'mail')]
class ExchangeComponent extends AbstractComponent implements ExchangeComponentInterface
```

**Responsibilities**:

- Manages workers for sending and receiving emails.
- Provides access to these workers through getter methods.
- Groups related functionality under a single namespace.

## Worker Layer

Workers expose the public API for specific tasks:

### SenderWorker

```php
#[Worker(name: 'sender', component: 'exchange', package: 'mail')]
class SenderWorker extends AbstractWorker implements SenderWorkerInterface
```

**Responsibilities**:

- Provides a public `send()` method for sending emails.
- Delegates the actual sending process to handlers.
- Manages any worker-specific resources.

### ReceiverWorker

```php
#[Worker(name: 'receiver', component: 'exchange', package: 'mail')]
class ReceiverWorker extends AbstractWorker implements ReceiverWorkerInterface
```

**Responsibilities**:

- Provides a public `receive()` method for receiving emails.
- Delegates the receiving process to handlers.
- Manages any worker-specific resources.

## Handler Layer

Handlers orchestrate complex processes, selecting appropriate strategies and managing the workflow:

### SendHandler

```php
class SendHandler extends AbstractHandler
```

**Responsibilities**:

- Selects the appropriate sending strategy based on configuration.
- Orchestrates the email sending process.
- Handles errors in a centralized manner.
- Manages options and configuration.

### ReceiveHandler

```php
class ReceiveHandler extends AbstractHandler
```

**Responsibilities**:

- Selects the appropriate receiving strategy based on configuration.
- Orchestrates the email receiving process.
- Handles errors in a centralized manner.
- Manages options and configuration.

## Strategy Layer

Strategies implement specific methods for sending or receiving emails:

### SmtpStrategy

```php
#[Strategy(name: 'smtp', worker: 'sender', component: 'exchange', package: 'mail')]
class SmtpStrategy extends AbstractMailerStrategy implements SenderStrategyInterface
```

**Responsibilities**:

- Configures and uses Symfony Mailer for SMTP transport.
- Builds appropriate DSN string based on configuration.
- Handles the actual sending of emails.
- Manages SMTP-specific settings.

### ImapStrategy

```php
#[Strategy(name: 'imap', worker: 'receiver', component: 'exchange', package: 'mail')]
class ImapStrategy extends AbstractMailboxStrategy implements ReceiverStrategyInterface
```

**Responsibilities**:

- Configures and uses PHP-IMAP for IMAP access.
- Builds appropriate DSN string for IMAP connection.
- Searches for and retrieves emails based on criteria.
- Manages IMAP-specific settings.

## Abstract Base Classes

The library provides abstract base classes that implement common functionality:

### AbstractMailerStrategy

```php
abstract class AbstractMailerStrategy extends AbstractStrategy implements SenderStrategyInterface
```

**Responsibilities**:

- Provides common code for email sending strategies.
- Handles the creation of Symfony Mailer instances.
- Processes envelopes and messages.

### AbstractMailboxStrategy

```php
abstract class AbstractMailboxStrategy extends AbstractStrategy implements ReceiverStrategyInterface
```

**Responsibilities**:

- Provides common code for email receiving strategies.
- Handles the creation of Mailbox instances.
- Processes received emails into envelopes.

## Model Layer

Domain models represent the core entities of the email domain:

### Envelope

```php
class Envelope extends SymfonyEnvelope implements EnvelopeInterface
```

**Responsibilities**:

- Contains sender and recipient information.
- Holds one or more messages.
- Provides a container for email communication.

### Message

```php
class Message extends SymfonyEmail implements MessageInterface
```

**Responsibilities**:

- Represents an individual email message.
- Contains subject, body, attachments, etc.
- Tracks sending/receiving errors.

### Postman

```php
class Postman implements PostmanInterface
```

**Responsibilities**:

- Acts as a transport container for envelopes.
- Holds configuration options for sending/receiving.
- Provides a unified interface for email operations.

### Mailbox

```php
class Mailbox implements MailboxInterface
```

**Responsibilities**:

- Represents an email mailbox (IMAP folder).
- Provides methods for searching and retrieving emails.
- Handles connection to mail servers.

## Data Flow Examples

### Sending an Email

1. Client code creates a Message and adds it to an Envelope.
2. Envelope is added to a Postman with SMTP configuration.
3. Client calls SenderWorker's send() method with the Postman.
4. SenderWorker delegates to SendHandler.
5. SendHandler selects SmtpStrategy based on configuration.
6. SmtpStrategy uses Symfony Mailer to send the emails.
7. Results are returned through the same chain.

### Receiving Emails

1. Client creates a Postman with IMAP configuration.
2. Client calls ReceiverWorker's receive() method with the Postman.
3. ReceiverWorker delegates to ReceiveHandler.
4. ReceiveHandler selects ImapStrategy based on configuration.
5. ImapStrategy connects to the mailbox and retrieves emails.
6. Retrieved emails are converted to Envelopes with Messages.
7. Envelopes are added to the Postman and returned.

## Extending the Library

The architecture makes it easy to extend the library with new strategies:

1. **New Sending Strategy**: Create a class that extends AbstractMailerStrategy or implements SenderStrategyInterface.
2. **New Receiving Strategy**: Create a class that extends AbstractMailboxStrategy or implements ReceiverStrategyInterface.
3. **Tag with Attribute**: Use the #[Strategy] attribute for automatic discovery.
4. **Use via Configuration**: Specify your strategy in the Postman options.

## Key Benefits of This Architecture

1. **Separation of Concerns**: Each class has a single, well-defined responsibility.
2. **Extensibility**: Easy to add new strategies without modifying existing code.
3. **Testability**: Clean interfaces make unit testing straightforward.
4. **Configurability**: Comprehensive options at every level.
5. **Maintainability**: Clear structure makes code easy to understand and modify.

## Conclusion

Derafu Mail's architecture provides a solid foundation for email operations in PHP applications. By leveraging the Derafu Backbone patterns, it achieves a clean separation of concerns while remaining flexible and extensible.

Understanding this architecture will help you effectively use the library and extend it with new capabilities when needed.




---

### Custom Sender Strategy

Creating a Custom Sender Strategy for Derafu Mail

# Creating a Custom Sender Strategy for Derafu Mail

This guide explains how to create custom sender strategies for Derafu Mail. Sender strategies allow you to implement different methods of sending emails beyond the default SMTP implementation.

## Understanding Sender Strategies

A sender strategy in Derafu Mail is responsible for the actual transmission of email messages. The library comes with an SMTP implementation, but you might want to add support for:

- API-based email services (SendGrid, Mailgun, Postmark, etc.).
- Custom internal email systems.
- Database-based email queues.
- Testing/mock implementations.

## Option 1: Extending AbstractMailerStrategy

The simplest approach is to extend the `AbstractMailerStrategy` class, which provides reusable functionality for most email sending scenarios that utilize Symfony Mailer internally.

### When to Use This Approach

- When your email service has a Symfony Transport implementation.
- When you need to reuse the core sending logic.
- When your strategy follows a similar workflow to the SMTP strategy.

### Implementation Steps

1. Create a new class that extends `AbstractMailerStrategy`:

```php
<?php

declare(strict_types=1);

namespace YourNamespace\Strategy;

use Derafu\Backbone\Attribute\Strategy;
use Derafu\Config\Contract\OptionsInterface;
use Derafu\Mail\Component\Exchange\Worker\Sender\Strategy\Abstract\AbstractMailerStrategy;
use Derafu\Mail\Component\Exchange\Worker\Sender\Strategy\Contract\SenderStrategyInterface;

#[Strategy(name: 'mailgun', worker: 'sender', component: 'exchange', package: 'mail')]
class MailgunStrategy extends AbstractMailerStrategy implements SenderStrategyInterface
{
    /**
     * Schema of the options.
     *
     * @var array<string,array>
     */
    protected array $optionsSchema = [
        'strategy' => [
            'types' => 'string',
            'default' => 'mailgun',
        ],
        'transport' => [
            'types' => 'array',
            'schema' => [
                'api_key' => [
                    'types' => 'string',
                    'required' => true,
                ],
                'domain' => [
                    'types' => 'string',
                    'required' => true,
                ],
                'region' => [
                    'types' => 'string',
                    'default' => 'us',
                ],
                'dsn' => [
                    'types' => 'string',
                ],
                'endpoint' => [
                    'types' => 'string',
                ],
            ],
        ],
    ];

    /**
     * {@inheritDoc}
     */
    protected function resolveDsn(OptionsInterface $options): string
    {
        $transportOptions = $options->get('transport');

        if (!empty($transportOptions['dsn'])) {
            return $transportOptions['dsn'];
        }

        // Construct the DSN for Mailgun using Symfony's format.
        $dsn = sprintf(
            'mailgun://%s@%s?region=%s',
            $transportOptions['api_key'],
            $transportOptions['domain'],
            $transportOptions['region'] ?? 'us'
        );

        $options->set('transport.dsn', $dsn);

        return $dsn;
    }

    /**
     * {@inheritDoc}
     */
    protected function resolveEndpoint(OptionsInterface $options): string
    {
        $transportOptions = $options->get('transport');

        if (!empty($transportOptions['endpoint'])) {
            return $transportOptions['endpoint'];
        }

        $endpoint = sprintf(
            'mailgun://%s',
            $transportOptions['domain']
        );

        $options->set('transport.endpoint', $endpoint);

        return $endpoint;
    }
}
```

2. Define your options schema to specify the required configuration.

3. Implement the `resolveDsn()` method to build the appropriate DSN string for your service.

4. Implement the `resolveEndpoint()` method to provide a human-readable representation of the endpoint.

### Key Benefits

- Leverages existing functionality from the abstract class.
- Reduces code duplication.
- Ensures consistent behavior across strategies.
- Automatically gets error handling and envelope processing.

## Option 2: Implementing SenderStrategyInterface

For more specialized use cases, you can implement the `SenderStrategyInterface` directly.

### When to Use This Approach

- When your sending mechanism is fundamentally different from Symfony Mailer.
- When you need complete control over the sending process.
- When you want to avoid dependencies on Symfony components.
- For custom integrations with proprietary systems

### Implementation Steps

1. Create a new class that implements `SenderStrategyInterface`:

```php
<?php

declare(strict_types=1);

namespace YourNamespace\Strategy;

use Derafu\Backbone\Abstract\AbstractStrategy;
use Derafu\Backbone\Attribute\Strategy;
use Derafu\Config\Contract\OptionsInterface;
use Derafu\Mail\Component\Exchange\Worker\Sender\Strategy\Contract\SenderStrategyInterface;
use Derafu\Mail\Exception\MailException;
use Derafu\Mail\Model\Contract\PostmanInterface;
use GuzzleHttp\Client;
use Throwable;

#[Strategy(name: 'custom-api', worker: 'sender', component: 'exchange', package: 'mail')]
class CustomApiStrategy extends AbstractStrategy implements SenderStrategyInterface
{
    /**
     * Schema of the options.
     *
     * @var array<string,array>
     */
    protected array $optionsSchema = [
        'strategy' => [
            'types' => 'string',
            'default' => 'custom-api',
        ],
        'transport' => [
            'types' => 'array',
            'schema' => [
                'api_url' => [
                    'types' => 'string',
                    'required' => true,
                ],
                'api_key' => [
                    'types' => 'string',
                    'required' => true,
                ],
                // Add any other configuration options needed.
            ],
        ],
    ];

    /**
     * HTTP client for API requests.
     */
    private Client $httpClient;

    /**
     * Constructor.
     */
    public function __construct()
    {
        $this->httpClient = new Client();
    }

    /**
     * {@inheritDoc}
     */
    public function send(PostmanInterface $postman): array
    {
        $options = $this->resolveOptions($postman->getOptions());
        $transportOptions = $options->get('transport');

        $apiUrl = $transportOptions['api_url'];
        $apiKey = $transportOptions['api_key'];

        foreach ($postman->getEnvelopes() as $envelope) {
            foreach ($envelope->getMessages() as $message) {
                try {
                    // Transform the message to your API format.
                    $payload = $this->transformMessageToApiPayload($message, $envelope);

                    // Send via your custom API.
                    $response = $this->httpClient->post($apiUrl, [
                        'headers' => [
                            'Authorization' => 'Bearer ' . $apiKey,
                            'Content-Type' => 'application/json',
                        ],
                        'json' => $payload,
                    ]);

                    // Process response if needed.
                    if ($response->getStatusCode() >= 400) {
                        throw new MailException('API returned error: ' . $response->getBody());
                    }

                } catch (Throwable $e) {
                    $message->error($e);
                }
            }
        }

        return $postman->getEnvelopes();
    }

    /**
     * Transforms a message to the format expected by the API.
     *
     * @param MessageInterface $message
     * @param EnvelopeInterface $envelope
     * @return array
     */
    private function transformMessageToApiPayload($message, $envelope): array
    {
        // Implement the transformation logic for your specific API.
        // This is where you map the Message and Envelope properties
        // to whatever format your API expects.

        return [
            'from' => $this->formatAddress($message->getFrom()[0]),
            'to' => array_map([$this, 'formatAddress'], $message->getTo()),
            'subject' => $message->getSubject(),
            'text' => $message->getTextBody(),
            'html' => $message->getHtmlBody(),
            // Handle attachments, CC, BCC, etc.
        ];
    }

    /**
     * Formats an email address for the API.
     */
    private function formatAddress($address): array
    {
        return [
            'email' => $address->getAddress(),
            'name' => $address->getName(),
        ];
    }
}
```

2. Define your options schema to specify the required configuration.

3. Implement the `send()` method to handle the entire sending process.

4. Add any helper methods needed for your specific implementation.

### Key Considerations

When implementing from scratch:

- **Error Handling**: You must handle all exceptions and errors.
- **Message Processing**: You need to transform Derafu Mail messages to your API format.
- **State Management**: Consider how to track message status and handle failures.
- **Testing**: Create test cases for various scenarios and error conditions.

## Usage

Once you've created your custom strategy, you can use it by specifying its name in the Postman configuration:

```php
$postman = new Postman([
    'strategy' => 'mailgun', // Or 'custom-api'
    'transport' => [
        // Strategy-specific configuration options.
        'api_key' => 'your-api-key',
        'domain' => 'your-domain.com',
        // Other options...
    ],
]);
```

## Best Practices

1. **Error Handling**: Always catch and properly handle exceptions.
2. **Logging**: Add appropriate logging to help troubleshoot issues.
3. **Configuration Validation**: Use the options schema to validate configuration.
4. **Comprehensive Documentation**: Document your strategy's requirements.
5. **Unit Testing**: Create tests for various scenarios including error cases.

## Conclusion

Creating custom sender strategies allows you to extend Derafu Mail to work with any email service or system. Whether you extend the abstract class or implement the interface directly depends on your specific needs and how much you want to leverage the existing infrastructure.

For most API-based email services that have Symfony Transport implementations, extending `AbstractMailerStrategy` is recommended. For completely custom implementations, implementing `SenderStrategyInterface` directly gives you maximum flexibility.




---

### Custom Receiver Strategy

Creating a Custom Receiver Strategy for Derafu Mail

# Creating a Custom Receiver Strategy for Derafu Mail

This guide explains how to create custom receiver strategies for Derafu Mail. Receiver strategies allow you to implement different methods of retrieving emails beyond the default IMAP implementation.

## Understanding Receiver Strategies

A receiver strategy in Derafu Mail is responsible for connecting to mail sources and retrieving messages. The library comes with an IMAP implementation, but you might want to add support for:

- API-based email services (Gmail API, Microsoft Graph, etc.).
- Custom email storage systems.
- Database-stored emails.
- Webhook receivers for incoming emails.
- Testing/mock implementations.

## Option 1: Extending AbstractMailboxStrategy

The simplest approach is to extend the `AbstractMailboxStrategy` class, which provides reusable functionality for email retrieval scenarios that use a mailbox-like interface.

### When to Use This Approach

- When your email source follows a mailbox paradigm.
- When you can use the PHP-IMAP library or similar interfaces.
- When you need to reuse common mailbox operations.
- When your strategy follows a similar workflow to the IMAP strategy.

### Implementation Steps

1. Create a new class that extends `AbstractMailboxStrategy`:

```php
<?php

declare(strict_types=1);

namespace YourNamespace\Strategy;

use Derafu\Backbone\Attribute\Strategy;
use Derafu\Config\Contract\OptionsInterface;
use Derafu\Mail\Component\Exchange\Worker\Receiver\Strategy\Abstract\AbstractMailboxStrategy;
use Derafu\Mail\Component\Exchange\Worker\Receiver\Strategy\Contract\ReceiverStrategyInterface;
use Derafu\Mail\Model\Mailbox;
use Derafu\Mail\Model\Contract\MailboxInterface;

#[Strategy(name: 'gmail-api', worker: 'receiver', component: 'exchange', package: 'mail')]
class GmailApiStrategy extends AbstractMailboxStrategy implements ReceiverStrategyInterface
{
    /**
     * Schema of the options.
     *
     * @var array<string,array>
     */
    protected array $optionsSchema = [
        'strategy' => [
            'types' => 'string',
            'default' => 'gmail-api',
        ],
        'transport' => [
            'types' => 'array',
            'schema' => [
                'client_id' => [
                    'types' => 'string',
                    'required' => true,
                ],
                'client_secret' => [
                    'types' => 'string',
                    'required' => true,
                ],
                'refresh_token' => [
                    'types' => 'string',
                    'required' => true,
                ],
                'user_email' => [
                    'types' => 'string',
                    'required' => true,
                ],
                'label' => [
                    'types' => 'string',
                    'default' => 'INBOX',
                ],
                'dsn' => [
                    'types' => 'string',
                ],
                'endpoint' => [
                    'types' => 'string',
                ],
                'search' => [
                    'types' => 'array',
                    'schema' => [
                        'query' => [
                            'types' => 'string',
                            'default' => 'is:unread',
                        ],
                        'markAsSeen' => [
                            'types' => 'bool',
                            'default' => false,
                        ],
                        'attachmentFilters' => [
                            'types' => 'array',
                            'default' => [],
                        ],
                    ],
                ],
            ],
        ],
    ];

    /**
     * {@inheritDoc}
     */
    protected function createMailbox(OptionsInterface $options): MailboxInterface
    {
        // Instead of using the standard Mailbox, create a specialized Gmail API mailbox.
        // This could be a custom class that implements MailboxInterface.

        $transportOptions = $options->get('transport');

        // This would be a custom implementation for Gmail API.
        return new GmailApiMailbox(
            $transportOptions['client_id'],
            $transportOptions['client_secret'],
            $transportOptions['refresh_token'],
            $transportOptions['user_email'],
            $transportOptions['label'] ?? 'INBOX'
        );
    }

    /**
     * {@inheritDoc}
     */
    protected function resolveDsn(OptionsInterface $options): string
    {
        $transportOptions = $options->get('transport');

        if (!empty($transportOptions['dsn'])) {
            return $transportOptions['dsn'];
        }

        // Construct a representative DSN for Gmail API.
        $dsn = sprintf(
            'gmail-api://%s',
            $transportOptions['user_email']
        );

        $options->set('transport.dsn', $dsn);

        return $dsn;
    }

    /**
     * {@inheritDoc}
     */
    protected function resolveEndpoint(OptionsInterface $options): string
    {
        $transportOptions = $options->get('transport');

        if (!empty($transportOptions['endpoint'])) {
            return $transportOptions['endpoint'];
        }

        $endpoint = sprintf(
            'https://gmail.googleapis.com/gmail/v1/users/%s',
            $transportOptions['user_email']
        );

        $options->set('transport.endpoint', $endpoint);

        return $endpoint;
    }
}

/**
 * Custom Mailbox implementation for Gmail API.
 * This class would need to implement all methods from MailboxInterface
 * but would use the Gmail API instead of IMAP.
 */
class GmailApiMailbox implements MailboxInterface
{
    // Implement all required methods from MailboxInterface.
    // This would use Google API Client or similar to fetch emails.
}
```

2. Define your options schema to specify the required configuration.

3. Override the `createMailbox()` method to return your custom mailbox implementation.

4. Implement the `resolveDsn()` and `resolveEndpoint()` methods.

5. Create a custom mailbox class that implements `MailboxInterface` if needed.

### Key Benefits

- Leverages existing workflow and error handling.
- Preserves compatibility with the rest of the library.
- Reuses attachment filtering and other common functionality.
- Maintains consistent behavior across strategies.

## Option 2: Implementing ReceiverStrategyInterface

For more specialized use cases, you can implement the `ReceiverStrategyInterface` directly.

### When to Use This Approach

- When your receiving mechanism is fundamentally different from a mailbox model.
- When you need complete control over the receiving process.
- When you're creating a strategy for webhooks or other non-polling mechanisms.
- For custom integrations with proprietary systems.

### Implementation Steps

1. Create a new class that implements `ReceiverStrategyInterface`:

```php
<?php

declare(strict_types=1);

namespace YourNamespace\Strategy;

use Derafu\Backbone\Abstract\AbstractStrategy;
use Derafu\Backbone\Attribute\Strategy;
use Derafu\Mail\Component\Exchange\Worker\Receiver\Strategy\Contract\ReceiverStrategyInterface;
use Derafu\Mail\Exception\MailException;
use Derafu\Mail\Model\Contract\EnvelopeInterface;
use Derafu\Mail\Model\Contract\MessageInterface;
use Derafu\Mail\Model\Contract\PostmanInterface;
use Derafu\Mail\Model\Envelope;
use Derafu\Mail\Model\Message;
use Symfony\Component\Mime\Address;
use Throwable;

#[Strategy(name: 'webhook-receiver', worker: 'receiver', component: 'exchange', package: 'mail')]
class WebhookReceiverStrategy extends AbstractStrategy implements ReceiverStrategyInterface
{
    /**
     * Schema of the options.
     *
     * @var array<string,array>
     */
    protected array $optionsSchema = [
        'strategy' => [
            'types' => 'string',
            'default' => 'webhook-receiver',
        ],
        'transport' => [
            'types' => 'array',
            'schema' => [
                'webhook_data' => [
                    'types' => 'array',
                    'required' => true,
                ],
                'secret_key' => [
                    'types' => 'string',
                    'default' => '',
                ],
                // Add any other configuration options needed.
            ],
        ],
    ];

    /**
     * {@inheritDoc}
     */
    public function receive(PostmanInterface $postman): array
    {
        $options = $this->resolveOptions($postman->getOptions());
        $transportOptions = $options->get('transport');

        $webhookData = $transportOptions['webhook_data'];
        $secretKey = $transportOptions['secret_key'] ?? '';

        try {
            // Validate webhook data if a secret is configured.
            if ($secretKey && !$this->validateWebhookSignature($webhookData, $secretKey)) {
                throw new MailException('Invalid webhook signature');
            }

            // Process the webhook data to extract email information.
            $emails = $this->processWebhookData($webhookData);

            // Create envelopes and add them to the postman.
            foreach ($emails as $emailData) {
                $envelope = $this->createEnvelope($emailData);
                $postman->addEnvelope($envelope);
            }

            // Optionally acknowledge receipt to the webhook source.
            $this->acknowledgeReceipt($webhookData);

        } catch (Throwable $e) {
            throw new MailException(
                sprintf(
                    'An error occurred while processing webhook data: %s',
                    $e->getMessage()
                ),
                0,
                $e
            );
        }

        return $postman->getEnvelopes();
    }

    /**
     * Validates the webhook signature to ensure authenticity.
     *
     * @param array $webhookData
     * @param string $secretKey
     * @return bool
     */
    private function validateWebhookSignature(array $webhookData, string $secretKey): bool
    {
        // Implement signature validation logic.
        // The exact implementation depends on how your webhook source signs requests.
        return true; // Placeholder.
    }

    /**
     * Processes the webhook data to extract email information.
     *
     * @param array $webhookData
     * @return array
     */
    private function processWebhookData(array $webhookData): array
    {
        // Convert webhook data to a standardized email format.
        // This will depend entirely on the webhook format you're receiving.

        // Placeholder implementation - extract email data from webhook.
        $emails = [];

        if (isset($webhookData['emails']) && is_array($webhookData['emails'])) {
            foreach ($webhookData['emails'] as $email) {
                $emails[] = [
                    'from' => $email['sender'] ?? '',
                    'from_name' => $email['sender_name'] ?? '',
                    'to' => $email['recipient'] ?? '',
                    'to_name' => $email['recipient_name'] ?? '',
                    'subject' => $email['subject'] ?? '',
                    'text_body' => $email['plain_text'] ?? '',
                    'html_body' => $email['html'] ?? '',
                    'attachments' => $email['attachments'] ?? [],
                ];
            }
        }

        return $emails;
    }

    /**
     * Creates an envelope from email data.
     *
     * @param array $emailData
     * @return EnvelopeInterface
     */
    private function createEnvelope(array $emailData): EnvelopeInterface
    {
        // Create a sender address.
        $sender = new Address(
            $emailData['from'],
            $emailData['from_name'] ?? ''
        );

        // Create recipient addresses.
        $recipients = [
            new Address(
                $emailData['to'],
                $emailData['to_name'] ?? ''
            )
        ];

        // Create the envelope.
        $envelope = new Envelope($sender, $recipients);

        // Create and add the message.
        $message = $this->createMessage($emailData);
        $envelope->addMessage($message);

        return $envelope;
    }

    /**
     * Creates a message from email data.
     *
     * @param array $emailData
     * @return MessageInterface
     */
    private function createMessage(array $emailData): MessageInterface
    {
        // Create the message.
        $message = new Message();

        // Set basic properties
        $message->subject($emailData['subject'] ?? '');

        if (!empty($emailData['text_body'])) {
            $message->text($emailData['text_body']);
        }

        if (!empty($emailData['html_body'])) {
            $message->html($emailData['html_body']);
        }

        $message->from(new Address(
            $emailData['from'],
            $emailData['from_name'] ?? ''
        ));

        $message->to(new Address(
            $emailData['to'],
            $emailData['to_name'] ?? ''
        ));

        // Process attachments if any.
        if (!empty($emailData['attachments']) && is_array($emailData['attachments'])) {
            foreach ($emailData['attachments'] as $attachment) {
                if (isset($attachment['content'], $attachment['name'], $attachment['type'])) {
                    $content = base64_decode($attachment['content']);
                    $message->attach(
                        $content,
                        $attachment['name'],
                        $attachment['type']
                    );
                }
            }
        }

        return $message;
    }

    /**
     * Acknowledges receipt to the webhook source if needed.
     *
     * @param array $webhookData
     * @return void
     */
    private function acknowledgeReceipt(array $webhookData): void
    {
        // Some webhook providers require an acknowledgement.
        // Implement if needed for your specific case.
    }
}
```

2. Define your options schema to specify the required configuration.

3. Implement the `receive()` method to handle the entire receiving process.

4. Add helper methods for your specific implementation needs.

### Key Considerations

When implementing from scratch:

- **Error Handling**: Properly catch and handle all exceptions.
- **Data Transformation**: Carefully map external data to Derafu Mail models.
- **Security**: Validate webhook signatures or implement other security measures.
- **Consistency**: Ensure your implementation behaves consistently with other strategies.
- **Testing**: Create comprehensive tests for your implementation.

## Usage

Once you've created your custom strategy, you can use it by specifying its name in the Postman configuration:

```php
$postman = new Postman([
    'strategy' => 'gmail-api', // Or 'webhook-receiver'
    'transport' => [
        // Strategy-specific configuration options.
        'client_id' => 'your-client-id',
        'client_secret' => 'your-client-secret',
        'refresh_token' => 'your-refresh-token',
        'user_email' => 'user@example.com',
        // Other options...
    ],
]);

$receiverWorker = $exchangeComponent->getReceiverWorker();
$envelopes = $receiverWorker->receive($postman);
```

## Best Practices

1. **Error Handling**: Always catch and handle exceptions appropriately.
2. **Logging**: Add detailed logging to help troubleshoot issues.
3. **Configuration Validation**: Use the options schema to validate configuration.
4. **Rate Limiting**: Consider rate limits for API-based strategies.
5. **Pagination**: Implement proper pagination for retrieving large volumes of emails.
6. **Performance**: Be mindful of memory usage when dealing with attachments.
7. **Documentation**: Document your strategy's specific requirements and limitations.

## Conclusion

Creating custom receiver strategies allows you to extend Derafu Mail to work with any email source or system. Whether you extend the abstract class or implement the interface directly depends on your specific needs and how much you want to leverage the existing infrastructure.

For sources that follow a mailbox-like model, extending `AbstractMailboxStrategy` is recommended. For completely different mechanisms like webhooks, implementing `ReceiverStrategyInterface` directly gives you maximum flexibility.




---

## Logbook Project

PHP Logging Library

# PHP Logging Library

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/log/main)
![CI Workflow](https://github.com/derafu/log/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/log)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/log)
![Total Downloads](https://poser.pugx.org/derafu/log/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/log/d/monthly)

A flexible, PSR-3 compliant PHP logging library that leverages Monolog and add additional features while maintaining a clean and simple API.

## Features

- **PSR-3 Compatible**: Implements the PSR-3 logging interface for standardized usage.
- **In-Memory Log Storage**: Store logs in memory for retrieval during runtime.
- **Caller Information**: Automatically track which class, method, file, and line generated each log message.
- **Custom Formatting**: Enhanced line formatter that includes caller information.
- **Multiple Log Levels**: Support for all standard log levels (debug, info, notice, warning, error, critical, alert, emergency).
- **Context Support**: Add structured data to your log messages.
- **Monolog Integration**: Built on top of Monolog for robust logging capabilities.

## Installation

```bash
composer require derafu/log
```

## Basic Usage

```php
use Derafu\Log\Level;
use Derafu\Log\Service\Logger;
use Derafu\Log\Service\LogService;
use Derafu\Log\Service\LineFormatter;

// Create a logger with a line formatter.
$logger = new Logger(
    formatter: new LineFormatter()
);

// Create the log service.
$logService = new LogService($logger);

// Log messages with different levels.
$logService->logger()->debug('Debug message');
$logService->logger()->info('Info message');
$logService->logger()->warning('Warning message', ['context' => 'value']);
$logService->logger()->error('Error message', ['error_code' => 500]);

// Retrieve all logs.
$allLogs = $logService->logs();

// Retrieve only error logs.
$errorLogs = $logService->logs(Level::ERROR);

// Retrieve logs, newest first (default).
$newestFirst = $logService->logs(null, true);

// Retrieve logs, oldest first.
$oldestFirst = $logService->logs(null, false);

// Clear logs.
$logService->clear(); // Clear all logs.
$logService->clear(Level::ERROR); // Clear only error logs.

// Retrieve logs and clear them in one operation.
$logs = $logService->flush();
```

## Caller Information

One of the key features of this library is automatic tracking of the caller information. Every log includes details about which class, method, file, and line generated the log message:

```php
$logService->logger()->error('Something went wrong');

// The log will include caller information automatically.
$logs = $logService->logs();
$caller = $logs[0]->getCaller();

echo $caller; // Outputs: in /path/to/file.php on line 42, called by Namespace\Class::method()
```

## Working with Log Records

Each log record provides methods to access its data:

```php
$logs = $logService->logs();
$log = $logs[0];

// Access log data.
$level = $log->getCode();
$message = $log->getMessage();
$context = $log->getContext();
$caller = $log->getCaller();
```

## Advanced Configuration

You can customize the logger with additional handlers:

```php
use Monolog\Handler\StreamHandler;
use Monolog\Level;

// Create a logger with additional handlers.
$logger = new Logger(
    configuration: ['channel' => 'app'],
    handlers: [
        new StreamHandler('path/to/your.log', Level::Debug),
        // Add more handlers as needed.
    ],
    formatter: new LineFormatter()
);

$logService = new LogService($logger);
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## License

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).




---

## Auth Project

Derafu Auth

# Derafu Auth




---

### Introduction

Authentication and Authorization

# Derafu: Auth

PSR-15 compliant authentication and authorization library for PHP applications with Keycloak integration.

## Features

- **PSR-15 Middleware**: Standard-compliant middleware.
- **Keycloak Integration**: OAuth2/OpenID Connect.
- **Session Management**: Secure session handling.
- **Token Refresh**: Automatic token refresh.
- **Route Protection**: Flexible route-based auth.
- **CSRF Protection**: State parameter validation.

## Quick Start

### Installation

Install the package:

```bash
composer require derafu/auth
```

### Environment Variables

Configure, at the very least, the following environment variables:

```env
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_REDIRECT_URI=http://localhost/auth/callback
```

### Routes

Import the routes to your `routes.yaml`:

```yaml
imports:
    - { resource: '../vendor/derafu/auth/resources/config/auth-routes.yaml' }
```

### Services

Import the services to your `services.yaml`:

```yaml
imports:
    - { resource: '../vendor/derafu/auth/resources/config/auth-services.yaml' }
```

### Middleware

Add the middleware to your `services.yaml`:

```yaml
Psr\Http\Server\RequestHandlerInterface:
    class: Derafu\Http\Service\RequestHandler
    public: true
    arguments:
        $middlewares:
            - '@Derafu\Auth\Middleware\AuthenticationMiddleware'
```

**Note**: the `AuthenticationMiddleware` needs to be placed before the `DispatcherMiddleware`.

### Access User Information

Directly with the attribute `user` or `access_token`:

```php
$user = $request->getAttribute('user');
$accessToken = $request->getAttribute('access_token');
```

Using the `UserInterface` from the `mezzio/mezzio-authentication` package:

```php
$user = $request->getAttribute(UserInterface::class);
if ($user) {
    $identity = $user->getIdentity();
    $roles = iterator_to_array($user->getRoles());
    $email = $user->getDetail('email');
}
```




---

### Configuration

Configuration options for Derafu Auth

# Configuration

## Environment Variables

| Variable | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `KEYCLOAK_URL` | string | **Yes** | - | Keycloak server URL |
| `KEYCLOAK_CLIENT_ID` | string | **Yes** | - | OAuth2 client ID |
| `KEYCLOAK_CLIENT_SECRET` | string | **Yes** | - | OAuth2 client secret |
| `KEYCLOAK_REDIRECT_URI` | string | **Yes** | - | OAuth2 redirect URI |
| `KEYCLOAK_REALM` | string | No | `master` | Keycloak realm |
| `KEYCLOAK_SCOPES` | json | No | `["openid", "profile", "email"]` | OAuth2 scopes |
| `KEYCLOAK_PROTECTED_ROUTES` | json | No | `["/dashboard", "/profile", "/admin"]` | Protected routes |
| `KEYCLOAK_CALLBACK_ROUTE` | string | No | `/auth/callback` | Callback route |
| `KEYCLOAK_LOGOUT_ROUTE` | string | No | `/auth/logout` | Logout route |
| `KEYCLOAK_SESSION_LIFETIME` | int | No | `3600` | Session lifetime |
| `KEYCLOAK_SECURE_COOKIES` | bool | No | `false` | Secure cookies |
| `KEYCLOAK_HTTP_TIMEOUT` | int | No | `30` | HTTP timeout |
| `KEYCLOAK_HTTP_CONNECT_TIMEOUT` | int | No | `30` | HTTP connect timeout |
| `KEYCLOAK_HTTP_VERIFY` | bool | No | `false` | SSL verification |

## Required Configuration

The following parameters are **mandatory** and must be provided:

```env
# Keycloak server configuration.
KEYCLOAK_URL=https://<YOUR_KEYCLOAK_SERVER>

# OAuth2 client credentials.
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret

# OAuth2 redirect URI.
KEYCLOAK_REDIRECT_URI=https://<YOUR_APP_URL>/auth/callback
```

## Routes Configuration

```yaml
auth_callback:
    path: /auth/callback
    handler: Derafu\Auth\Controller\CallbackController::handle

```

## Services Configuration

```yaml
services:

    _defaults:
        autowire: true
        autoconfigure: true
        public: false

    Derafu\Auth\Contract\AuthConfigurationInterface:
        class: Derafu\Auth\Configuration\AuthConfiguration
        arguments:
            $config:
                keycloak_url: '%env(default::string:KEYCLOAK_URL)%'
                realm: '%env(default::string:KEYCLOAK_REALM)%'
                client_id: '%env(default::string:KEYCLOAK_CLIENT_ID)%'
                client_secret: '%env(default::string:KEYCLOAK_CLIENT_SECRET)%'
                redirect_uri: '%env(default::string:KEYCLOAK_REDIRECT_URI)%'
                scopes: '%env(default::json:KEYCLOAK_SCOPES)%'
                protected_routes: '%env(default::json:KEYCLOAK_PROTECTED_ROUTES)%'
                callback_route: '%env(default::string:KEYCLOAK_CALLBACK_ROUTE)%'
                logout_route: '%env(default::string:KEYCLOAK_LOGOUT_ROUTE)%'
                session_lifetime: '%env(default::int:KEYCLOAK_SESSION_LIFETIME)%'
                secure_cookies: '%env(default::bool:KEYCLOAK_SECURE_COOKIES)%'
                http_client_options:
                    timeout: '%env(default::int:KEYCLOAK_HTTP_TIMEOUT)%'
                    connect_timeout: '%env(default::int:KEYCLOAK_HTTP_CONNECT_TIMEOUT)%'
                    verify: '%env(default::bool:KEYCLOAK_HTTP_VERIFY)%'

    Derafu\Auth\Contract\AuthenticationProviderInterface:
        class: Derafu\Auth\Service\KeycloakAuthenticationService

    Derafu\Auth\Contract\SessionManagerInterface:
        class: Derafu\Auth\Service\SessionService

    Derafu\Auth\Contract\RouteValidatorInterface:
        class: Derafu\Auth\Validator\RouteValidator

    Derafu\Auth\Middleware\AuthenticationMiddleware: ~

    Derafu\Auth\Controller\CallbackController:
        public: true

```




---

### Route Protection

Route protection capabilities in Derafu Auth

# Route Protection

The Derafu Auth package provides route protection through a simple array-based configuration system.

## How It Works

The `RouteValidator` class determines which routes require authentication by checking if the requested path starts with any of the configured protected routes.

```php
public function requiresAuth(string $path): bool
{
    foreach ($this->config->getProtectedRoutes() as $route) {
        if (str_starts_with($path, $route)) {
            return true;
        }
    }

    return false;
}
```

## Configuration

### Environment Variable

```env
KEYCLOAK_PROTECTED_ROUTES='["/dashboard", "/profile", "/admin"]'
```

### Default Protected Routes

If not specified, the package uses these default protected routes:

```json
["/dashboard", "/profile", "/admin"]
```

## Route Protection Examples

### Basic Protection

Protect specific routes:

```env
KEYCLOAK_PROTECTED_ROUTES=["/dashboard", "/profile", "/admin"]
```

This configuration will protect:

- `/dashboard` - Exact match.
- `/dashboard/settings` - Starts with `/dashboard`.
- `/profile` - Exact match.
- `/profile/edit` - Starts with `/profile`.
- `/admin` - Exact match.
- `/admin/users` - Starts with `/admin`.

### API Protection

Protect API routes:

```env
KEYCLOAK_PROTECTED_ROUTES=["/api/v1", "/api/v2"]
```

This will protect all routes starting with `/api/v1` or `/api/v2`:

- `/api/v1/users`
- `/api/v1/users/123`
- `/api/v2/admin`
- `/api/v2/admin/settings`

### Admin Panel Protection

Protect admin panel:

```env
KEYCLOAK_PROTECTED_ROUTES=["/admin", "/moderator"]
```

This protects:

- `/admin` - Admin panel
- `/admin/users` - User management
- `/admin/settings` - Settings
- `/moderator` - Moderator panel
- `/moderator/comments` - Comment moderation

## Limitations

The current implementation has the following limitations:

1. **Prefix Matching Only**: Routes are protected using `str_starts_with()`, so `/admin` will also protect `/admin-panel` and `/administer`.

2. **No Regex Support**: The package does not support regular expressions for route matching.

3. **No Wildcard Support**: There is no support for wildcard patterns like `/admin/*`.

4. **No Negative Patterns**: Cannot exclude specific routes from protection.

5. **No Role-Based Protection**: All protected routes require the same level of authentication. But you can use authorization to protect specific routes based on the user's roles.

## Special Routes

The package automatically handles these special routes:

- **Callback Route**: Default is `/auth/callback`.
- **Logout Route**: Default is `/auth/logout`.

These routes are automatically excluded from authentication requirements.

## Custom Route Validator

You can create a custom route validator by implementing the `RouteValidatorInterface`:

```php
use Derafu\Auth\Contract\RouteValidatorInterface;

class CustomRouteValidator implements RouteValidatorInterface
{
    public function requiresAuth(string $path): bool
    {
        // Your custom logic here
        return str_starts_with($path, '/protected');
    }

    public function isCallbackPath(string $path): bool
    {
        return $path === '/auth/callback';
    }

    public function isLogoutPath(string $path): bool
    {
        return $path === '/auth/logout';
    }

    public function getProtectedRoutes(): array
    {
        return ['/protected'];
    }

    public function getCallbackRoute(): string
    {
        return '/auth/callback';
    }

    public function getLogoutRoute(): string
    {
        return '/auth/logout';
    }
}
```

Then configure it in your services:

```yaml
services:
    Derafu\Auth\Contract\RouteValidatorInterface:
        class: App\Auth\CustomRouteValidator
```




---

### Authorization

Authorization and permissions in Derafu Auth

# Authorization

Derafu Auth handles **authentication** (who you are) and helps with **authorization** (what you can do). The last one depends on the roles and permissions you set in Keycloak.

## What comes from the package?

When a user is authenticated, the package automatically provides:

- **Basic data**: `sub`, `email`, `name`, `preferred_username`, etc.
- **Roles**: Come directly from Keycloak (e.g., `user`, `admin`, `moderator`).

## What you need to implement?

### Option 1: Role-based authorization (Recommended)

**Advantages**:

- Simple to implement.
- Roles already come from Keycloak.
- No additional configuration required.

**How it works**:

1. Keycloak assigns roles to users.
2. Your application maps permissions to roles.
3. You verify if the user has the required role.

**Mapping example**:

- Permission `user:read` → Roles `user`, `admin`, `moderator`.
- Permission `user:write` → Roles `admin`, `moderator`.
- Permission `admin:access` → Only role `admin`.

### Option 2: Permission-based authorization

**Advantages**:

- More granular.
- Specific permissions per action.
- Better access control.

**Disadvantages**:

- Requires additional Keycloak configuration.
- More complex to maintain.

## Keycloak configuration for permissions

### Step 1: Create a custom scope

1. Go to **Clients** → Your Client → **Client Scopes**
2. Create a new scope called `permissions`.
3. Add it to your client.

### Step 2: Configure Token Mapper

1. In the `permissions` scope, go to **Mappers**.
2. Create a new mapper:
   - **Name**: `permissions`
   - **Mapper Type**: `User Attribute`
   - **User Attribute**: `permissions`
   - **Token Claim Name**: `permissions`
   - **Claim JSON Type**: `String`
   - **Full group path**: `false`

### Step 3: Assign permissions to users

1. Go to **Users** → Select a user → **Attributes**
2. Add the attribute:
   - **Key**: `permissions`
   - **Value**: `user:read,user:write,admin:access`

### Step 4: Configure the scope in your application

```env
KEYCLOAK_SCOPES=["openid", "profile", "email", "permissions"]
```

## How do permissions work?

### Authorization flow:

1. **User authenticates** → Keycloak generates token with permissions.
2. **Token arrives at your app** → Derafu Auth extracts the data.
3. **Your code verifies** → If the user has the required permission.
4. **Access granted/denied** → Based on the verification.

### Recommended permission structure:

```
resource:action
```

**Examples**:

- `user:read` - Read users.
- `user:write` - Create/edit users.
- `user:delete` - Delete users.
- `admin:access` - Access admin panel.
- `report:generate` - Generate reports.

## Key differences

| Aspect            | Roles         | Permissions       |
|-------------------|---------------|-------------------|
| **Configuration** | Automatic     | Requires Keycloak |
| **Granularity**   | Access groups | Specific actions  |
| **Maintenance**   | Easy          | More complex      |
| **Flexibility**   | Limited       | High              |

## Recommendation

**Start with role-based authorization** because:

- It's simpler to implement.
- No additional Keycloak configuration required.
- Sufficient for most applications.
- You can migrate to permissions later if needed.

## Summary

- **Authentication**: Handled automatically by Derafu Auth.
- **Authorization**: Implementation based on roles or permissions.
- **Roles**: Come automatically from Keycloak.
- **Permissions**: Require additional Keycloak configuration.
- **Recommendation**: Start with roles, migrate to permissions if you need more granularity.




---

### Security

Security best practices for Derafu Auth

# Security

## Environment Variables

Always use environment variables for sensitive configuration:

```env
# ✅ Good
KEYCLOAK_CLIENT_SECRET=your-secret-here

# ❌ Bad
'client_secret' => 'your-secret-here'
```

## HTTPS Configuration

Enable HTTPS in production:

```env
# Development.
KEYCLOAK_SECURE_COOKIES=false
KEYCLOAK_HTTP_VERIFY=false

# Production.
KEYCLOAK_SECURE_COOKIES=true
KEYCLOAK_HTTP_VERIFY=true
```

## Session Security

```php
// Secure session configuration.
$config = new AuthConfiguration([
    'session_lifetime' => 3600,
    'secure_cookies' => true,
]);

// Additional session security that can be set.
ini_set('session.cookie_httponly', true);
ini_set('session.cookie_samesite', 'Lax');
ini_set('session.use_strict_mode', true);
```

## CSRF Protection

The package automatically validates the `state` parameter to prevent CSRF attacks.

## Token Security

Never store tokens in client-side storage:

```php
// ✅ Good - Server-side session.
$session->set('access_token', $accessToken);

// ❌ Bad - Never expose to client.
return new JsonResponse(['token' => $accessToken]);
```

## Authorization

```php
// Validate role format.
private function isValidRole(string $role): bool
{
    return preg_match('/^[a-zA-Z0-9_]+$/', $role) === 1;
}

// Check role hierarchy.
private function hasRole(array $userRoles, string $requiredRole): bool
{
    $roleHierarchy = [
        'super_admin' => ['admin', 'user'],
        'admin' => ['user'],
    ];

    if (in_array($requiredRole, $userRoles)) {
        return true;
    }

    foreach ($userRoles as $userRole) {
        if (isset($roleHierarchy[$userRole]) &&
            in_array($requiredRole, $roleHierarchy[$userRole])) {
            return true;
        }
    }

    return false;
}
```

## Error Handling

Don't expose sensitive information in production:

```php
public function handle(ServerRequestInterface $request, Throwable $exception): ResponseInterface
{
    $isProduction = getenv('APP_ENV') === 'production';

    if ($exception instanceof AuthenticationException) {
        return new JsonResponse([
            'error' => 'Authentication failed',
            'code' => 'UNAUTHORIZED'
        ], 401);
    }

    return new JsonResponse([
        'error' => $isProduction ? 'Internal server error' : $exception->getMessage(),
        'code' => 'INTERNAL_ERROR'
    ], 500);
}
```

## Security Headers

```php
class SecurityHeadersMiddleware
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $response = $handler->handle($request);

        return $response
            ->withHeader('X-Content-Type-Options', 'nosniff')
            ->withHeader('X-Frame-Options', 'DENY')
            ->withHeader('X-XSS-Protection', '1; mode=block')
            ->withHeader('Referrer-Policy', 'strict-origin-when-cross-origin')
            ->withHeader('Content-Security-Policy', "default-src 'self'")
            ->withHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
    }
}
```

## Keycloak Security

### Client Configuration

1. **Access Type**: `confidential`.
2. **Valid Redirect URIs**: Only your application URLs.
3. **Web Origins**: Your application domain.
4. **Client Authentication**: Enabled.

### Realm Settings

1. **Password Policy**: Strong password requirements.
2. **Brute Force Detection**: Enabled.
3. **Session Timeout**: Configured appropriately.
4. **SSL Required**: `external` or `all`.




---

### Examples

Practical examples for Derafu Auth

# Examples

## Minimal Setup

```php
<?php

require_once 'vendor/autoload.php';

use Derafu\Auth\Configuration\AuthConfiguration;
use Derafu\Auth\Service\KeycloakAuthenticationService;
use Derafu\Auth\Service\SessionService;
use Derafu\Auth\Validator\RouteValidator;
use Derafu\Auth\Middleware\AuthenticationMiddleware;

$config = new AuthConfiguration([
    'keycloak_url' => 'http://localhost:8080',
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'redirect_uri' => 'http://localhost/auth/callback',
]);

$authService = new KeycloakAuthenticationService($config);
$sessionService = new SessionService($config);
$routeValidator = new RouteValidator($config);

$authMiddleware = new AuthenticationMiddleware(
    $authService,
    $sessionService,
    $routeValidator
);
```

## API Examples

### REST API with Authentication

```php
class UserApiController
{
    public function getUsers(ServerRequestInterface $request): ResponseInterface
    {
        $user = $request->getAttribute('user');

        if (!$user) {
            return new JsonResponse(['error' => 'Not authenticated'], 401);
        }

        if (!$this->isAuthorized($user, 'user:read')) {
            return new JsonResponse(['error' => 'Access denied'], 403);
        }

        $users = $this->getUserList();

        return new JsonResponse(['users' => $users]);
    }

    private function isAuthorized(array $user, string $permission): bool
    {
        $userPermissions = $user['permissions'] ?? [];

        return in_array($permission, $userPermissions);
    }
}
```

### GraphQL with Authentication

```php
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Schema;

class AuthenticatedGraphQLSchema
{
    public function createSchema(): Schema
    {
        $userType = new ObjectType([
            'name' => 'User',
            'fields' => [
                'id' => Type::string(),
                'email' => Type::string(),
                'name' => Type::string(),
                'roles' => Type::listOf(Type::string()),
            ],
        ]);

        $queryType = new ObjectType([
            'name' => 'Query',
            'fields' => [
                'me' => [
                    'type' => $userType,
                    'resolve' => function ($root, $args, $context) {
                        $user = $context['user'] ?? null;

                        if (!$user) {
                            throw new \Exception('Not authenticated');
                        }

                        return $user;
                    },
                ],
            ],
        ]);

        return new Schema([
            'query' => $queryType,
        ]);
    }
}
```

## Testing Example

```php
use PHPUnit\Framework\TestCase;
use Derafu\Auth\Middleware\AuthenticationMiddleware;

class AuthenticationMiddlewareTest extends TestCase
{
    public function testProtectedRouteRequiresAuthentication()
    {
        $config = new AuthConfiguration([
            'keycloak_url' => 'http://localhost:8080',
            'client_id' => 'test-client',
            'client_secret' => 'test-secret',
            'redirect_uri' => 'http://localhost/auth/callback',
            'protected_routes' => ['/dashboard'],
        ]);

        $authService = $this->createMock(KeycloakAuthenticationService::class);
        $sessionService = $this->createMock(SessionService::class);
        $routeValidator = new RouteValidator($config);

        $middleware = new AuthenticationMiddleware(
            $authService,
            $sessionService,
            $routeValidator
        );

        $request = $this->createMock(ServerRequestInterface::class);
        $request->method('getUri')->willReturn(new Uri('/dashboard'));

        $handler = $this->createMock(RequestHandlerInterface::class);

        $response = $middleware->process($request, $handler);

        $this->assertEquals(302, $response->getStatusCode()); // Redirect to login.
    }
}
```

## Real-World Examples

### E-commerce Application

```php
class EcommerceAuthController
{
    public function handleLogin(ServerRequestInterface $request): ResponseInterface
    {
        $user = $request->getAttribute('user');

        if (!$user) {
            return new JsonResponse(['error' => 'Not authenticated'], 401);
        }

        if (!$this->hasPermission($user, 'shop:access')) {
            return new JsonResponse(['error' => 'Access denied'], 403);
        }

        $cart = $this->getUserCart($user['sub']);

        return new JsonResponse([
            'user' => $user,
            'cart' => $cart,
            'permissions' => $user['permissions'] ?? [],
        ]);
    }

    private function hasPermission(array $user, string $permission): bool
    {
        $permissions = $user['permissions'] ?? [];

        return in_array($permission, $permissions);
    }
}
```

### Admin Panel

```php
class AdminPanelController
{
    public function handleDashboard(ServerRequestInterface $request): ResponseInterface
    {
        $user = $request->getAttribute('user');

        if (!$user) {
            return new JsonResponse(['error' => 'Not authenticated'], 401);
        }

        if (!$this->isAdmin($user)) {
            return new JsonResponse(['error' => 'Access denied'], 403);
        }

        $stats = $this->getAdminStats();

        return new JsonResponse([
            'user' => $user,
            'stats' => $stats,
        ]);
    }

    private function isAdmin(array $user): bool
    {
        $roles = $user['roles'] ?? [];

        return in_array('admin', $roles) || in_array('super_admin', $roles);
    }
}
```




---

## Cache Project

Consistent PSR-6/PSR-16 Cache Wiring Across Derafu Packages

# Consistent PSR-6/PSR-16 Cache Wiring Across Derafu Packages

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/cache/main)
![CI Workflow](https://github.com/derafu/cache/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/cache)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/cache)
![Total Downloads](https://poser.pugx.org/derafu/cache/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/cache/d/monthly)

A small, opinionated layer over [`symfony/cache`](https://symfony.com/doc/current/components/cache.html) for the *local* backends (no connection, no credentials, no network round trip) — plus a handful of things PSR-6/PSR-16 and `symfony/cache` genuinely don't provide on their own.

## Why

`symfony/cache`'s own file-based adapters (`PhpFilesAdapter`, `FilesystemAdapter`) accept a `null` directory and silently fall back to one you'd have to read the source to find. A cache backed by the filesystem that nobody can point to exactly is a cache nobody can clear with confidence — `derafu/cache`'s adapters make `$namespace` and `$directory` required instead, so that decision is never made for you.

Past that one guardrail, this package adds a handful of things PSR-6/PSR-16 and `symfony/cache` genuinely don't provide on their own: a safe way to build cache keys without hand-rolling sanitization, a stampede-safe "compute and remember" helper, and a way to inspect or clear a cache directory without needing to reconstruct whatever wrote to it.

It is **not** a general abstraction over every backend `symfony/cache` supports. PSR-6/PSR-16 already are that abstraction — building another one on top would just be indirection. See [Scope](#scope-local-only) below.

## Installation

```bash
composer require derafu/cache
```

`ext-apcu` (for `LocalCacheBackend::Apcu`) and `symfony/console` (for the bundled commands) are both entirely optional — see [`composer.json`'s `suggest`](https://github.com/derafu/cache/blob/main/composer.json).

## Scope: Local Only

`LocalCacheBackend` and `LocalCacheFactory` cover exactly the backends that need no connection, no credentials, and no network round trip: they live in this process, in shared memory on this server, or on this filesystem.

```php
enum LocalCacheBackend: string
{
    case None = 'none';           // Never caches anything (NullAdapter).
    case Memory = 'memory';       // Dies with the process (ArrayAdapter).
    case Apcu = 'apcu';           // Shared memory, survives requests (ApcuAdapter).
    case Filesystem = 'filesystem'; // Serialized files, supports objects (FilesystemAdapter).
    case PhpFiles = 'php_files';  // Plain PHP array files, OPcache-friendly (PhpFilesAdapter).
}
```

Redis, Memcached, Couchbase, PDO, and every other connection-based backend `symfony/cache` supports are deliberately out of scope — not a gap, a boundary. They have a fundamentally different construction shape (a connection or DSN, not a namespace/directory pair) and none of the "silent default" problem this package exists to close off: `RedisAdapter`/`MemcachedAdapter` already force you to pass a real connection, no `null` fallback to guard against. Building one directly from `symfony/cache` isn't a workaround, it's simply what those backends need — `$pool->clear()` (part of PSR-6 itself) already works on them the same way it works on everything else.

## `PhpFilesCache` and `FilesystemCache`

```php
use Derafu\Cache\Adapter\PhpFilesCache;
use Derafu\Cache\Adapter\FilesystemCache;

// OPcache-friendly: values must be var_export()-able (arrays/scalars, no objects).
$pool = new PhpFilesCache('my_package', '/var/cache/my_package');

// Serialized: supports arbitrary values, including objects. No OPcache benefit.
$pool = new FilesystemCache('my_package', '/var/cache/my_package');
```

Both extend the matching `symfony/cache` adapter directly, under the same name, so anyone already familiar with `symfony/cache` recognizes immediately what each one does. `$namespace` and `$directory` are both required — `$defaultLifetime` (3600 by default) is the only parameter allowed to have one, since it isn't a "where does my data live" decision.

## `LocalCacheFactory`

For the case where the backend itself is a runtime choice — from configuration, the way a per-feature `cache: memory|filesystem` setting would — rather than something you already know at the call site:

```php
use Derafu\Cache\LocalCacheFactory;
use Derafu\Cache\Enum\LocalCacheBackend;
use Symfony\Component\Cache\Adapter\ArrayAdapter;

$pool = LocalCacheFactory::pool(LocalCacheBackend::Filesystem, 'my_package', '/var/cache/my_package');

// PSR-16 instead of PSR-6 — the same pool, wrapped in Symfony's Psr16Cache bridge.
$cache = LocalCacheFactory::simple(LocalCacheBackend::Memory, 'my_package');

// Tag-aware — $item->tag([...]) on save, invalidateTags([...]) to drop a whole group at once.
$cache = LocalCacheFactory::taggedPool(LocalCacheBackend::Apcu, 'my_package');

// Several pools, fastest first, with automatic backfill on a slower-tier hit.
$pool = LocalCacheFactory::layered([new ArrayAdapter(), $filesystemPool]);
```

`$directory` is required for `Filesystem`/`PhpFiles`, ignored for `None`/`Memory`/`Apcu` — passing it for those three is harmless, omitting it for the other two throws.

`LocalCacheBackend::None` (backed by Symfony's own `NullAdapter`) is how "no caching" is expressed — not a runtime flag a consumer has to check, but a pool like any other. A decorator that always receives a `CacheItemPoolInterface` needs no special case for "caching is off": it just does nothing useful when this happens to be the pool it got.

## `Memoizer`: Compute-and-Cache Without Reinventing Stampede Protection

```php
use Derafu\Cache\Memoizer;

$memoizer = new Memoizer();

$value = $memoizer->remember($pool, 'some_key', function () {
    return expensive_computation();
}, ttl: 3600);
```

Every hand-written PSR-6 caching decorator ends up rewriting the same "is it there? no? compute it, store it, return it" dance — `getItem()` → `isHit()` → `set()` → `save()`. That naive version has no protection against a cache stampede: under concurrent access, every process that hits a cold cache computes and saves independently.

Every `symfony/cache` adapter also implements Symfony's own [`CacheInterface::get()`](https://symfony.com/doc/current/components/cache.html#basic-usage-psr-6) contract, which does the same thing with real locking — only one process computes, the rest wait for it and read the result. `Memoizer::remember()` uses that path automatically whenever the given pool supports it, and falls back to the naive dance only for a PSR-6 implementation that isn't a Symfony adapter (no locking possible without Symfony's own contract). `$ttl` means exactly what it means for `expiresAfter()` — `null` leaves the pool's default lifetime in effect, `0` means the entry never expires, a positive integer is seconds until expiration. Nothing here redefines that; a decorator that also needs a "don't even try to cache" switch should express it as its own separately-named parameter, or — more simply — accept a `LocalCacheBackend::None` pool.

## `CacheKey`: One Safe Way to Build a Key

```php
use Derafu\Cache\CacheKey;

$cacheKey = new CacheKey();

$key = $cacheKey->build('my_package', 'ExampleWorker', ['api_resource' => true]);
// "my_package.ExampleWorker.e381541fbf7da0e4036f1cc881592fce"
```

PSR-6 forbids `{}()/\@:` in keys but sanitizes nothing for you — building a safe, collision-resistant key from real context (a class name with backslashes, a filter array) is left entirely to each caller. `CacheKey::build()` normalizes each part: a string gets its forbidden characters *replaced* (never dropped — dropping them could collide `App\FooBar` with `App\Foo\Bar`, both becoming `AppFooBar`), any other scalar is used as-is, and anything else (an array, an object) is hashed. If the assembled key would exceed 250 bytes (Memcached's real limit, a safe ceiling for any backend), the whole thing collapses to the prefix plus a hash of the full key — long context never silently breaks a backend with an actual key-length limit.

`CacheKey` implements `Derafu\Cache\Contract\CacheKeyInterface` so a consumer that needs key logic driven by what's actually being cached — not just its class name — can inject its own implementation of that one-method interface instead of subclassing `CacheKey` and reaching into its private sanitizing helpers.

## `CacheDirectory`: Inspecting and Clearing by Path Alone

```php
use Derafu\Cache\CacheDirectory;

$directory = new CacheDirectory('/var/cache/my_package');

$directory->stats(); // ['count' => 42, 'totalSize' => 1048576, 'oldest' => 1700000000, 'newest' => 1700003600]
$directory->clear(); // int — how many files were deleted.
```

`stats()` is a real, new capability — neither PSR-6 nor `symfony/cache` expose a way to ask any pool how many entries it holds or how much space they use, for any backend. `clear()` is not: `CacheItemPoolInterface::clear()` is already part of PSR-6 and works fine when you have a live pool instance in hand. `CacheDirectory::clear()` exists for exactly the case where you don't — an admin command that only knows a path, not which adapter type (namespace, TTL, backend) originally wrote there.

## `CacheWarmer` and `WarmableInterface`: Warming Without a Kernel

```php
use Derafu\Cache\CacheWarmer;
use Derafu\Cache\Contract\WarmableInterface;

final class ExampleWarmable implements WarmableInterface
{
    public function warmup(): void { /* ... */ }
}

$failures = (new CacheWarmer())->warmup([$warmableA, $warmableB]);
// list<array{warmable: WarmableInterface, exception: Throwable}> — empty if everything succeeded.
```

`symfony/cache` has no warmup concept at all — only `PruneableInterface` (the opposite: removing *expired* entries). Symfony's real `CacheWarmerInterface` lives in `symfony/http-kernel`, tied to the full framework Kernel's boot lifecycle: it warms the *framework's own* caches (compiled container, routing) into a temporary location and atomically swaps them in, specifically because a half-written container cache would take the whole application down.

Warming an application-level PSR-6 cache doesn't carry that risk — if a warmable fails partway through, the next real read just recomputes that one entry. So `CacheWarmer` doesn't try to replicate the atomic swap or the Kernel's boot-order resolution: it runs each warmable in order, keeps going if one throws, and reports every failure at the end instead of stopping at the first one.

There's deliberately no bundled warmup *command*: a generic one would need to discover which `WarmableInterface` instances exist in a given application and how to construct each one — almost none will have a no-argument constructor, since a real warmable needs whatever it's warming. That discovery is exactly what a DI container is for, which this package chooses not to depend on (see [Console Commands](#console-commands-optional) below). The intended shape is a small, application-specific command that constructs the warmables it actually has and calls `(new CacheWarmer())->warmup($warmables)`.

## Console Commands (Optional)

```php
use Derafu\Cache\Console\ClearLocalCacheCommand;
use Derafu\Cache\Console\LocalCacheStatsCommand;

$application->add(new ClearLocalCacheCommand());
$application->add(new LocalCacheStatsCommand());
```

```bash
php bin/console derafu:local-cache:clear /var/cache/my_package
php bin/console derafu:local-cache:stats /var/cache/my_package
```

Both wrap `CacheDirectory` and require only a path. Named `derafu:local-cache:*`, not the more obvious `cache:clear`/`cache:stats` — that name is already taken in any real Symfony full-stack app (`symfony/framework-bundle` ships its own `cache:clear`, for the framework's own internal cache), and a generic name from a library meant to be added into someone else's `Application` is a collision waiting to happen. Still want a shorter name? Rename after construction: `(new ClearLocalCacheCommand())->setName('cache:clear-local')`.

Neither command is registered automatically — this package has no DI container of its own to register commands into. `symfony/console` is a `suggest`, not a hard requirement: Composer's autoloading is lazy, so a consumer that never references `Console\*` pays nothing for it even without `symfony/console` installed.

## Requirements

PHP 8.5+. Depends on [`symfony/cache`](https://symfony.com/doc/current/components/cache.html), `psr/cache`, and `psr/simple-cache`.




---

## Console Project

Symfony Console Integration for the Derafu Kernel

# Symfony Console Integration for the Derafu Kernel

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/console/main)
![CI Workflow](https://github.com/derafu/console/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/console)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/console)
![Total Downloads](https://poser.pugx.org/derafu/console/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/console/d/monthly)

Adds [Symfony Console](https://symfony.com/doc/current/components/console.html) command auto-discovery and execution to any [`Derafu\Kernel\MicroKernel`](https://www.derafu.dev/docs/core/kernel)-based Kernel — no per-command registration, no opinion on whether a project reuses its main Kernel or a dedicated console-only one.

## What This Package Provides

- `Derafu\Console\DependencyInjection\CommandCompilerPass`: collects every service tagged `console.command` into a `console.command_ids` container parameter.
- `Derafu\Console\ConsoleKernelTrait`: adds command auto-discovery and a `run(): int` method to any class extending `Derafu\Kernel\MicroKernel` (or providing an equivalent `getContainer(): ContainerInterface`).
- `Derafu\Console\Kernel`: a ready-to-use console Kernel for projects that do not need to compose console support into an existing Kernel.
- `Derafu\Console\Runtime`: resolves the real process environment (`APP_ENV`/`APP_DEBUG`) before any Kernel exists — see below.

This package does not depend on `derafu/http` or any HTTP-related package. It has no opinion on whether a project reuses its main application Kernel, a dedicated console-only subclass of it, or a fresh one — that decision belongs entirely to each project.

## Installation

```bash
composer require derafu/console
```

## `Runtime`: Resolving `APP_ENV`/`APP_DEBUG` Before the Kernel Exists

A Kernel's own `Derafu\Kernel\Environment::getEnv()` cannot help decide *its own* `$environment`/`$debug` constructor arguments — it's an instance method, and the instance doesn't exist yet. Something has to resolve those two values from the real process environment first.

Reading `$_ENV['APP_ENV']` directly is not reliable: `$_ENV` is only populated when the `variables_order` php.ini directive includes `E`, which is not every PHP installation's default — a stock Homebrew PHP on macOS, for example, ships with `GPCS`, without `E`. `$_SERVER` does carry real process environment variables in the CLI SAPI regardless of that setting, so `Runtime::getApplicationContext()` merges both:

```php
use Derafu\Console\Runtime;

$context = Runtime::getApplicationContext();
// ['APP_ENV' => 'prod', 'APP_DEBUG' => false, ...] — plus whatever else
// was already in $_SERVER/$_ENV.
```

Defaults to `prod`/`false` when neither is set — deliberately the *opposite* of [`derafu/http`'s `Runtime`](https://www.derafu.dev/docs/core/http), whose `dev`/`true` fallback only matters when an HTTP project has no `.env` of its own (`Derafu\Kernel\Environment::loadEnvironmentVariables()` loads one). A console tool installed via Composer and run as `bin/console` has no such file: the values this class resolves *are* the actual default a fresh install runs with, so it has to be the safe one — a stack trace should never be exposed unless `APP_DEBUG` is explicitly set.

`Runtime::run()` resolves the context, builds the Kernel through a factory, and runs it — this is the actual recommended `bin/console` entry point, not `getApplicationContext()` used by hand:

```php
// bin/console
use Derafu\Console\Kernel;
use Derafu\Console\Runtime;

require dirname(__DIR__) . '/vendor/autoload.php';

exit(Runtime::run(fn (array $context): Kernel => new Kernel(
    $context['APP_ENV'],
    (bool) $context['APP_DEBUG'],
)));
```

## Usage

### A Project With No Other Kernel (Simplest Case)

`Kernel` reads `services.yaml` from the environment's configuration directory. Any service in it whose class extends `Symfony\Component\Console\Command\Command` is discovered automatically.

```php
// bin/console
use Derafu\Console\Kernel;
use Derafu\Console\Runtime;

require dirname(__DIR__) . '/vendor/autoload.php';

exit(Runtime::run(fn (array $context): Kernel => new Kernel(
    $context['APP_ENV'],
    (bool) $context['APP_DEBUG'],
)));
```

### A Project That Already Has Its Own Kernel

Use `ConsoleKernelTrait` directly on a dedicated subclass, so the main Kernel is not forced to carry console-specific wiring it may rarely need:

```php
use Derafu\Console\ConsoleKernelTrait;

class ConsoleApplication extends Application // your project's own Kernel.
{
    use ConsoleKernelTrait;

    protected function configure(
        ContainerConfigurator $configurator,
        ContainerBuilder $container
    ): void {
        parent::configure($configurator, $container);
        $this->configureConsole($container);
    }
}
```

```php
// bin/console
use App\ConsoleApplication;
use Derafu\Console\Runtime;

require dirname(__DIR__) . '/vendor/autoload.php';

exit(Runtime::run(fn (array $context): ConsoleApplication => new ConsoleApplication(
    $context['APP_ENV'],
    (bool) $context['APP_DEBUG'],
)));
```

The same applies if the console needs to share the exact same `services.yaml` as, e.g., an HTTP Kernel: extend that Kernel instead of `Derafu\Console\Kernel` and `use ConsoleKernelTrait` the same way — see [Backbone Console](https://www.derafu.dev/docs/core/backbone-console) for a real example of this (`libredte-lib-core-console`'s `ConsoleApplication` extends its own business Kernel, not `Derafu\Console\Kernel`).

### Overriding the Application Built by `run()`

`ConsoleKernelTrait::createConsoleApplication()` builds the underlying `Symfony\Component\Console\Application` — override it to customize the name/version, or to install a `CommandLoaderInterface` (as [Backbone Console](https://www.derafu.dev/docs/core/backbone-console) does):

```php
use Symfony\Component\Console\Application as SymfonyConsoleApplication;
use Symfony\Component\DependencyInjection\ContainerInterface;

class ConsoleApplication extends Application
{
    use ConsoleKernelTrait {
        createConsoleApplication as private buildBaseConsoleApplication;
    }

    protected function createConsoleApplication(
        ContainerInterface $container
    ): SymfonyConsoleApplication {
        $application = $this->buildBaseConsoleApplication($container);

        // e.g. $application->setCommandLoader(...);

        return $application;
    }
}
```

The alias (`createConsoleApplication as private buildBaseConsoleApplication`) is required to call the trait's own implementation: a trait's methods are mixed directly into the class, not inherited through a parent class, so `parent::createConsoleApplication()` would not resolve.

### Customizing the Application Name and Version

Set these as container parameters (e.g. in `services.yaml`) and they will be picked up automatically:

```yaml
parameters:
    kernel.app_name: 'My CLI'
    kernel.app_version: '1.0.0'
```

## Requirements

PHP 8.5+. Depends on [`derafu/kernel`](https://www.derafu.dev/docs/core/kernel) and `symfony/console`.




---

## Backbone Console Project

Turn Any Backbone Operation Into a CLI Command

# Turn Any Backbone Operation Into a CLI Command

![GitHub last commit](https://img.shields.io/github/last-commit/derafu/backbone-console/main)
![CI Workflow](https://github.com/derafu/backbone-console/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/derafu/backbone-console)
![GitHub Issues](https://img.shields.io/github/issues-raw/derafu/backbone-console)
![Total Downloads](https://poser.pugx.org/derafu/backbone-console/downloads)
![Monthly Downloads](https://poser.pugx.org/derafu/backbone-console/d/monthly)

Exposes every operation a [`SafeExplorerInterface`](https://www.derafu.dev/docs/core/backbone-dispatcher) discovers as its own auto-discovered [Symfony Console](https://symfony.com/doc/current/components/console.html) command — no per-operation `Command` subclass, ever.

## Why

[Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher) already turns a string operation id and a plain array of parameters into a safe, serializable call. This package is one more transport on top of it — the same idea [Backbone API](https://www.derafu.dev/docs/core/backbone-api) is for HTTP, but for a standalone CLI process, meant to be run by hand or invoked from any other language via `exec()`/`system()`/`subprocess.run()`, not just from PHP.

A business library can expose hundreds of operations. `OperationCommandLoader` builds a `Symfony\Component\Console\Command\Command` for exactly one, on demand, only when a `bin/console` invocation actually needs it — never all of them upfront.

## Installation

```bash
composer require derafu/backbone-console
```

## Usage

Compose a Kernel with [`derafu/console`](https://www.derafu.dev/docs/core/console)'s `ConsoleKernelTrait`, and install `OperationCommandLoader` as the `CommandLoaderInterface`:

```php
use Derafu\BackboneConsole\Service\OperationCommandLoader;
use Derafu\BackboneDispatcher\Contract\SafeDispatcherInterface;
use Derafu\BackboneDispatcher\Contract\SafeExplorerInterface;
use Derafu\Console\ConsoleKernelTrait;
use Symfony\Component\Console\Application as SymfonyConsoleApplication;
use Symfony\Component\DependencyInjection\ContainerInterface;

class ConsoleApplication extends YourOwnKernel // e.g. your business library's own Kernel.
{
    use ConsoleKernelTrait {
        createConsoleApplication as private buildBaseConsoleApplication;
    }

    protected function createConsoleApplication(
        ContainerInterface $container
    ): SymfonyConsoleApplication {
        $application = $this->buildBaseConsoleApplication($container);

        $application->setCommandLoader(new OperationCommandLoader(
            $container->get(SafeExplorerInterface::class),
            $container->get(SafeDispatcherInterface::class),
        ));

        return $application;
    }
}
```

```php
// bin/console
use App\ConsoleApplication;
use Derafu\Console\Runtime;

require dirname(__DIR__) . '/vendor/autoload.php';

exit(Runtime::run(fn (array $context): ConsoleApplication => new ConsoleApplication(
    $context['APP_ENV'],
    (bool) $context['APP_DEBUG'],
)));
```

Extending your own Kernel directly (rather than `Derafu\Console\Kernel`) is deliberate whenever the console needs the exact same `services.yaml`-wired services (like `SafeExplorerInterface`/`SafeDispatcherInterface` above) as the rest of the project — see [Console](https://www.derafu.dev/docs/core/console#a-project-that-already-has-its-own-kernel).

Every discovered operation becomes its own command, named by converting its id's `.`/`::` separators to Symfony Console's own `:` convention:

```
billing.invoice.builder::build  →  billing:invoice:builder:build
```

```bash
bin/console list
bin/console help billing:invoice:builder:build
```

## The Request: One File (or STDIN), Any Format

A `Worker`'s operations can each take arbitrarily different parameters — there is no fixed set of CLI flags to define per command, only reflection (via `SafeExplorerInterface`) knows the shape at runtime. So the request is always a single JSON, YAML, or XML document, with the operation's parameters under a `"parameters"` key — the same shape an HTTP body would use:

```bash
echo '{"parameters": {"number": "F-001", "amount": 15000}}' \
    | bin/console billing:invoice:builder:build

bin/console billing:invoice:builder:build request.json
bin/console billing:invoice:builder:build request.yaml
bin/console billing:invoice:builder:build -   # "-": explicit STDIN.
```

The `input` argument is optional — omitted, or given as `-`, reads from STDIN. Format is auto-detected from content: a leading `<` is tried as XML, then JSON, then YAML (YAML is a syntactic superset of JSON, so trying it first would mean JSON is never actually detected as its own format).

Content starting with `{`/`[` is treated as an unambiguous signal that JSON was intended: if it fails to parse as JSON, that is a real, thrown error (`EX_DATAERR`, see below) rather than a silent fallback to YAML. Without this, some malformed JSON parses successfully as something else instead of failing loudly — a trailing comma (`{"a": 5,}`) is invalid JSON but valid YAML flow-style, so it used to silently reinterpret into a document simply missing whatever came after the comma. The trade-off: a hand-written top-level YAML *flow-style* document (`{a: 5}` written as YAML on purpose, not as a JSON typo) is no longer accepted — YAML's more common block style (`a: 5` on its own line) is completely unaffected.

## The Response: Same Format as the Request, or Forced With `--output`

Without `--output`, the response is written to STDOUT in the same format the request came in as — a successful one is `{"meta": {"timestamp": ..., "data_type": ...}, "data": <value>}` (the same envelope [Backbone API](https://www.derafu.dev/docs/core/backbone-api) uses, so a caller does not have to special-case which transport it is talking to); a failed one is `ProblemDetailInterface::toArray()` (see [Backbone Dispatcher](https://www.derafu.dev/docs/core/backbone-dispatcher#handling-failure-problemdetail), `extensions.timestamp`/`extensions.data_type` included there too), written to STDERR instead, alongside a resolved exit code (see below).

`--output <path>` and `--error-output <path>` write to a real file instead of STDOUT/STDERR, independently of each other — `--output` only ever applies on success, `--error-output` only ever on failure (a single invocation only ever hits one of the two branches, so they can even point at the same path without conflict). Piping with shell redirection (`>`/`2>`) already works, but conflates the structured payload with anything else the process might write; these options guarantee only the payload lands in the file:

```bash
bin/console billing:invoice:builder:build request.json --output=result.yaml
bin/console billing:invoice:builder:build request.json --error-output=problem.xml
```

The destination's own file extension (`.json`/`.yaml`/`.yml`/`.xml`) decides the *response* format, independent of the *request*'s — an unrecognized or missing extension (e.g. `.txt`) falls back to the request's format, same as omitting the option entirely. `-` is accepted explicitly for "STDOUT"/"STDERR", the same convention the `input` argument already uses.

A write failure is never silent: a missing destination directory or a permissions error is reported on the real STDERR and returns `GenericOperationCommand::EX_CANTCREAT` — never a false "success" while nothing was actually written.

## Execution Metadata: `-v`

The response payload's *shape* never depends on where it is written, only on `-v`/`--verbose` — and only for how *much* ends up in it, never whether `meta`/`data_type`/`timestamp` are there at all (they always are). Without `-v`, `meta` has just `timestamp`/`data_type`, as shown above. With it, the rest of [`ExecutionMetadata`](https://www.derafu.dev/docs/core/backbone-dispatcher#execution-metadata-executionmetadata) (`startedAt`, timing, memory, CPU, load average) is merged into that same `meta` on success, or into `extensions` on failure (next to the already-present `debug`/`context`/`throwable`) — never a new top-level key:

```bash
bin/console -v billing:invoice:builder:build request.json
```

```json
{
    "meta": {
        "timestamp": 1755500000.123456,
        "data_type": "App\\Entity\\Invoice",
        "startedAt": "2026-01-20T10:00:00+00:00",
        "finishedAt": "2026-01-20T10:00:00+00:00",
        "realTime": 0.0234,
        "userTime": 0.0198,
        "systemTime": 0.0012,
        "memoryUsed": 131072,
        "peakMemory": 4194304,
        "pid": 12345,
        "loadAverage1Min": 0.52,
        "loadAverage5Min": 0.61,
        "loadAverage15Min": 0.58
    },
    "data": { "id": "INV-001" }
}
```

## Exit Codes

`bin/console help <command>` always lists every exit code that specific command can return — the fixed ones below, plus whatever the injected `ExitCodeResolverInterface` reports via `describe()` (see next section).

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | The operation failed, and nothing more specific applies (`DefaultExitCodeResolver`'s fallback). |
| `10`–`16` | One of `derafu/backbone-dispatcher`'s own 7 generic exceptions — see below. |
| `65` (`EX_DATAERR`) | The request could not be parsed as JSON/YAML/XML. |
| `66` (`EX_NOINPUT`) | The input file does not exist or is not readable. |
| `70` (`EX_SOFTWARE`) | An unexpected internal error — a bug, not a usage or business problem. |
| `73` (`EX_CANTCREAT`) | `--output`/`--error-output` could not be created. |

`65`/`66`/`70`/`73` are [`sysexits(3)`](https://man.freebsd.org/cgi/man.cgi?query=sysexits) codes — a real BSD convention (`/usr/include/sysexits.h` on macOS/BSD), chosen because they start at `64` specifically to avoid colliding with whatever small integers other programs already use for their own exit codes. `2` (Symfony Console's own `Command::INVALID`) is reserved but currently unused by this package.

### `ExitCodeResolverInterface`: Mapping Exceptions to Codes

Every failure not caused by this command itself (a `ProblemDetailInterface`, produced by the dispatch) goes through `ExitCodeResolverInterface::resolve()`. `DefaultExitCodeResolver` — the default — already maps the 7 exceptions generic to *any* Backbone-based project, since they mean the same thing regardless of domain:

| Code | Exception |
| --- | --- |
| `10` | `OperationNotFoundException` |
| `11` | `OperationNotAllowedException` |
| `12` | `MissingParameterException` |
| `13` | `InvalidParameterTypeException` |
| `14` | `ClassNotFoundException` |
| `15` | `FromArrayMethodNotFoundException` |
| `16` | `NoDeserializerFoundException` |

A project that also wants its *own* business exceptions mapped extends `DefaultExitCodeResolver` rather than starting from nothing, layering its mapping on top via `parent::`:

```php
use Derafu\BackboneConsole\Service\DefaultExitCodeResolver;
use Derafu\BackboneDispatcher\Contract\ProblemDetailInterface;

class MyExitCodeResolver extends DefaultExitCodeResolver
{
    public function resolve(ProblemDetailInterface $problem): int
    {
        return match ($problem->getThrowable()->getClass()) {
            MyBusinessException::class => 20,
            default => parent::resolve($problem),
        };
    }

    public function describe(): array
    {
        return [MyBusinessException::class => 20] + parent::describe();
    }
}
```

Codes `>= 10` are the convention for a project's own mapping — clear of Symfony Console's `0`/`1`/`2`, `DefaultExitCodeResolver`'s own `10`–`16`, and the `64`–`78` `sysexits(3)` range this package uses internally.

## Requirements

PHP 8.5+. Depends on [`derafu/backbone-dispatcher`](https://www.derafu.dev/docs/core/backbone-dispatcher), [`derafu/console`](https://www.derafu.dev/docs/core/console), `derafu/xml`, and `symfony/console`/`symfony/yaml`.





---
Last updated on 09/09/2026