PHPackages                             waffle-commons/skeleton - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. waffle-commons/skeleton

ActiveProject[Framework](/categories/framework)

waffle-commons/skeleton
=======================

The official skeleton for Waffle Framework applications.

0.1.0-alpha4(4mo ago)01MITPHPPHP ^8.5

Since Jan 6Pushed 4mo agoCompare

[ Source](https://github.com/waffle-commons/skeleton)[ Packagist](https://packagist.org/packages/waffle-commons/skeleton)[ RSS](/packages/waffle-commons-skeleton/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (12)Versions (4)Used By (0)

[![Waffle Ecosystem Logo](https://github.com/waffle-commons/.github/raw/main/assets/logo.png)](https://github.com/waffle-commons/.github/blob/main/assets/logo.png)

🦁 Waffle Skeleton
=================

[](#-waffle-skeleton)

The official starting point for building robust, secure, and high-performance applications with the [Waffle Ecosystem](https://github.com/waffle-commons).

[![Minimum PHP Version](https://camo.githubusercontent.com/a3efcba14243fb59b4bc246efb4cca2aee6c5ae1a38ee305f736d4eabf2e96f1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e352d626c75652e737667)](https://php.net/)[![Waffle Ecosystem](https://camo.githubusercontent.com/cbf98a6990845497840b316dc95b3213d9d468eb8cd08a048f8705b39ead9f4c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f776166666c652d636f6d6d6f6e732d6f72616e6765)](https://github.com/waffle-commons)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](./LICENSE.md)

Welcome to the **Waffle Skeleton**, the official starting point for building robust, secure, and high-performance applications with the [Waffle Ecosystem](https://github.com/waffle-commons).

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

[](#-installation)

### Prerequisites

[](#prerequisites)

- **Docker** & **Docker Compose** (Required)
- **PHP 8.5+** & **Composer** (Optional, for local commands)

### Create a New Project

[](#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
--------------------

[](#-docker-environment)

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

### 1. Development Mode (dev)

[](#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**](https://localhost/) (Accept the self-signed certificate auto-generated by Caddy).

### 2. Production Mode (prod)

[](#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
---------------------

[](#-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
----------------

[](#️-configuration)

### Environment Variables (`.env`)

[](#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`.

VariableDescription`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`)

[](#framework-config-configappyaml)

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

[](#‍-usage-example)

### 1. Create a Service

[](#1-create-a-service)

Create `src/Service/Greeter.php`:

```