waffle-commons/skeleton

The official skeleton for Waffle Framework applications.

0.1.0-alpha4 2026-01-06 11:01 UTC

Requires

• php: ^8.5
• ext-yaml: *
• ext-zend-opcache: *
• waffle-commons/config: 0.1.0-alpha4
• waffle-commons/container: 0.1.0-alpha4
• waffle-commons/contracts: 0.1.0-alpha4
• waffle-commons/error-handler: 0.1.0-alpha4
• waffle-commons/http: 0.1.0-alpha4
• waffle-commons/pipeline: 0.1.0-alpha4
• waffle-commons/routing: 0.1.0-alpha4
• waffle-commons/runtime: 0.1.0-alpha4
• waffle-commons/security: 0.1.0-alpha4
• waffle-commons/utils: 0.1.0-alpha4
• waffle-commons/waffle: 0.1.0-alpha4

Requires (Dev)

• phpunit/phpunit: ^12.0

MIT

• Leslie Petrimaux

README

🦁 Waffle Skeleton

The official starting point for building robust, secure, and high-performance applications with the Waffle Ecosystem.

Welcome to the Waffle Skeleton, the official starting point for building robust, secure, and high-performance applications with the Waffle Ecosystem.

This skeleton is not just a folder structure; it is a Production-Grade Boilerplate pre-configured with:

• FrankenPHP (Caddy): Modern application server with native HTTP/3 and Early Hints support.

• Docker Multi-Stage: Optimized images for Development (with Xdebug) and Production (Immutable, <100MB).

• Zero-Config Security: Automatic secret generation and hardened defaults.

• Strict Standards: PHP 8.5+, Typed Properties, and Read-Only classes.

🚀 Installation

Prerequisites

• Docker & Docker Compose (Required)

• PHP 8.5+ & Composer (Optional, for local commands)

Create a New Project

Use Composer to create your project. This will automatically trigger the setup scripts to generate secure keys and initialize the directory structure.

composer create-project waffle-commons/skeleton my-app
cd my-app

Note: If you don't have PHP installed locally, you can use the Docker setup immediately after cloning the repository manually.

🐳 Docker Environment

Waffle is Cloud-Native by design. We provide two distinct environments managed via a single Dockerfile.

1. Development Mode (dev)

Optimized for Developer Experience (DX).

• Hot Reload: Code is mounted via volumes. Changes are reflected instantly.

• Debugging: Xdebug is installed and configured.

• Tooling: Composer is available inside the container.

Start the Dev Server:

docker compose up --build -d

Your application is now available at: 👉 https://localhost (Accept the self-signed certificate auto-generated by Caddy).

2. Production Mode (prod)

Optimized for Performance and Security.

• Immutable: No source code volumes. The code is baked into the image.

• Fast: Opcache validation is disabled, Preloading is enabled.

• Secure: Dev tools (Composer, Xdebug) are removed. Rootless execution.

Test the Production Build locally:

docker compose -f docker-compose.prod.yml up --build -d

📂 Directory Structure

A Waffle application follows a strict but simple structure:

.
├── config/                       # ⚙️ Configuration
│   ├── app.yaml                  # Main Waffle Configuration
│   └── preload.php               # Opcache Preloading Script
├── docker/                       # 🐳 Infrastructure as Code (Dockerfile, Caddyfile, PHP config)
├── public/                       # 🌍 Web Entry Point (index.php)
├── scripts/                      # 🛠️ Composer Lifecycle Scripts
├── src/                          # 🧠 Your Application Logic (Namespace: App\)
│   ├── Controller/               # HTTP Entry points
│   ├── Factory/                  # Application Factory
│   │  ├── AppKernelFactory.php   # The Kernel Factory (Dependencies)
│   ├── Service/                  # Business Logic
│   └── Kernel.php                # The Application Core (Configuration & Boot)
├── tests/                        # 🧪 PHPUnit Test Suite
└── var/                          # 📦 Temporary files (Cache, Logs, Exports, etc) - Ignored by Git

🛠️ Configuration

Environment Variables (.env)

Waffle uses vlucas/phpdotenv logic but integrated natively. When you run create-project, a .env file is automatically created from .env.example with a generated APP_SECRET.

Variable	Description
APP_ENV	dev (debug enabled) or prod (optimized).
APP_DEBUG	true displays detailed stack traces. false renders JSON errors.
APP_SECRET	32-byte Hex string used for cryptographic operations.
SERVER_NAME	The domain name used by Caddy (e.g., example.com or localhost).

Framework Config (config/app.yaml)

Waffle uses native YAML parsing (via PECL extension) for blazing-fast configuration loading.

# Main application configuration for the Waffle Framework
waffle:
  # App environment (dev, prod, test). Set via server environment variable.
  env: '%env(APP_ENV)%'
  # Debug mode. Set to false in production for security.
  debug: '%env(APP_DEBUG)%'
  security:
    level: 10
  paths:
    controllers: 'src/Controller'
    services: 'src/Service'

👩‍💻 Usage Example

1. Create a Service

Create src/Service/Greeter.php:

<?php

namespace App\Service;

readonly class Greeter
{
    public function sayHello(string $name): string
    {
        return "Welcome to Waffle, {$name}!";
    }
}

2. Create a Controller

Create src/Controller/HelloController.php. Waffle uses Attributes for routing.

<?php

namespace App\Controller;

use App\Service\Greeter;
use Psr\Http\Message\ResponseInterface;
use Waffle\Commons\Routing\Attribute\Argument;
use Waffle\Commons\Routing\Attribute\Route;
use Waffle\Core\BaseController;

class HelloController extends BaseController
{
    // Services are automatically injected (Autowiring)
    public function __construct(
        private Greeter $greeter
    ) {}

    #[Route(path: '/greet/{name}', method: 'GET')]
    public function index(string $name): ResponseInterface
    {
        $message = $this->greeter->sayHello($name);

        return $this->jsonResponse(data: [
            'message' => $message,
            'status' => 'success'
        ]);
    }
}

Go to https://localhost/greet/Developer. You should see your JSON response!

🧪 Running Tests

The skeleton comes with PHPUnit pre-configured.

# Run tests inside the Docker container
vendor/bin/phpunit

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.