Tutorial: Build a Complete Page

Every other page in these docs explains one feature. This one puts them together. You will build the Recipe Box: a public gallery of community recipes with photos, pagination, a "save to favorites" button and a form for logged-in users to share their own recipe. By the end you will have used almost every part of the framework in a single, realistic feature, and seen where each piece belongs.

The code follows the same rules as the framework itself: PHP 8.4, strict types, and everything is written to pass PHPStan level 9.

How to use this page: follow the steps in order and you will end with a working feature. If you only need one technique, every step stands on its own and links to the full reference page for that feature.

What You Will Use

Here is every feature the Recipe Box touches, and where it shows up.

Feature	Where it appears	Reference
Controllers & dependency injection	`RecipeController`	Controllers, Container
Doctrine entities	`Recipe` (writes)	Doctrine ORM
PDO models & pagination	`RecipeCatalog` (reads)	Models, Pagination
Migrations	`CreateRecipesTable`	Console Commands
Named routes & middleware	`routes/web.php`	Routing, Middleware
Twig views, flash messages, CSRF	`views/recipes/`	Views, Security
Validation	`store()`	Validation
File uploads	`store()`	File Uploader
Image resizing & signed URLs	`imageSet()`	Image Processing
Events & listeners	`RecipePublished`	Events
`defer()`	view counter, JSON export	Deferred Tasks
Persistent queue	`EmailRecipeConfirmation`	Persistent Queue
Sessions	favorites, recently viewed	Sessions
Cache	popular recipes	Caching
Support helpers & Path	`Config`, `Fs`, `Json`, `Path`	Support Helpers, Path Helper
SEO helpers	meta tags, Schema.org, `Sluggify`	SEO Helpers
React Islands	`FavoriteButton`, `ServingScaler`	React + Rhapsody
Mailer & Logger	the queue job, a listener	Mailer, Logging

How a recipe gets published

This is the request you will build in Steps 5 to 10. Notice that each tool does a different job: some work happens inside the request, some right after it, and some in a separate process.

POST /recipes
 |- CSRF check (global middleware), then the "auth" route middleware
 |- Validator            -> are the form fields acceptable?
 |- FileUploader         -> store the photo (checked by real MIME type)
 |- Doctrine             -> persist() + flush() the Recipe entity
 |- EventDispatcher      -> RecipePublished: clear caches, write a log line   (in the request)
 |- defer()              -> rebuild the JSON export                           (after the response)
 |- QueueManager         -> EmailRecipeConfirmation                           (a worker process, retried)
 '- redirect + flash      -> GET /recipes/{slug}

Before You Start

You need a working Rhapsody application (see Installation & Setup) with APP_URL and your database settings in .env. Then run these commands once. Each one is explained in the step that uses it.

# Users table, so recipes have authors (skip if you already ran it)
php rhapsody auth:install

# React bridge for the islands in Step 11 (skip if you already ran it)
php rhapsody react:install
npm install

# Tables for the persistent queue used in Step 10
php rhapsody queue:install --migrate

Tip: Keep APP_URL set even on a local install. redirect() and route() both build addresses from APP_URL and APP_BASE_URL, and a few lines in this tutorial rely on that.

Project Layout

These are the files you will create or change. Everything else already exists in the skeleton.

app/
  Controllers/RecipeController.php      Step 6   (generated, then rewritten)
  Entities/Recipe.php                   Step 3
  Events/RecipePublished.php            Step 8   (generated, then edited)
  Jobs/EmailRecipeConfirmation.php      Step 10
  Listeners/ClearRecipeCaches.php       Step 8   (generated, then edited)
  Listeners/LogRecipeActivity.php       Step 8   (generated, then edited)
  Models/RecipeCatalog.php              Step 4   (generated, then rewritten)
  Providers/EventServiceProvider.php    Step 8   (edited)
  Services/RecipeExporter.php           Step 9
config/config.php                       Step 1   (edited)
db/migrations/..._create_recipes_table.php   Step 2 (generated, then edited)
resources/js/components/FavoriteButton.jsx   Step 11 (generated, then edited)
resources/js/components/ServingScaler.jsx    Step 11 (generated, then edited)
routes/web.php                          Step 5   (edited)
views/recipes/index.twig, _card.twig, show.twig, create.twig    Step 7

Step 1: Configuration

Put tunable values in configuration, not in controller code. Read them from the environment with Env inside config/config.php, where it is allowed to touch the environment, and read them everywhere else through the typed Config service.

config/config.php (add this key to the array the file returns)

'recipes' => [
    'per_page'       => Env::int('RECIPES_PER_PAGE', 9),
    'export_enabled' => Env::bool('RECIPES_EXPORT', true),
],

.env

RECIPES_PER_PAGE=9
RECIPES_EXPORT=true

Later, $this->config->int('recipes.per_page', 9) returns a real int, using dot notation to reach the nested key. If a key is missing and you gave no default, Config throws immediately instead of letting a null travel through your code.

Step 2: The Database Table

Rhapsody uses Phinx for migrations, so the same file works on MySQL, PostgreSQL, SQL Server and SQLite. Generate the file, then fill in change().

php rhapsody make:migration CreateRecipesTable

Open the new file in db/migrations/ and replace its body:

db/migrations/20261106120000_create_recipes_table.php

<?php

declare(strict_types=1);

use Phinx\Migration\AbstractMigration;

final class CreateRecipesTable extends AbstractMigration
{
    public function change(): void
    {
        $this->table('recipes')
            ->addColumn('author_id', 'string', ['limit' => 255])
            ->addColumn('title', 'string', ['limit' => 160])
            ->addColumn('slug', 'string', ['limit' => 190])
            ->addColumn('summary', 'string', ['limit' => 300])
            ->addColumn('ingredients', 'text')
            ->addColumn('steps', 'text')
            ->addColumn('servings', 'integer', ['default' => 4])
            ->addColumn('photo', 'string', ['limit' => 100, 'null' => true])
            ->addColumn('views', 'integer', ['default' => 0])
            ->addColumn('created_at', 'timestamp', ['default' => 'CURRENT_TIMESTAMP'])
            ->addIndex(['slug'], ['unique' => true])
            ->addIndex(['author_id'])
            ->create();
    }
}

Your file name will carry its own timestamp. Now create the table:

php rhapsody migrate

author_id holds the user_id of the built-in users table. We use a plain column rather than a database foreign key to keep the tutorial focused, but adding one is a good exercise.

Step 3: The Entity (Writes)

Use a Doctrine entity when you create or change data. The EntityManager tracks the object and writes only what changed. Entities live in app/Entities/, which the framework scans automatically.

app/Entities/Recipe.php

<?php

declare(strict_types=1);

namespace App\Entities;

use DateTimeImmutable;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'recipes')]
class Recipe
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[ORM\Column(name: 'author_id', type: 'string', length: 255)]
    private string $authorId;

    #[ORM\Column(type: 'string', length: 160)]
    private string $title;

    #[ORM\Column(type: 'string', length: 190, unique: true)]
    private string $slug;

    #[ORM\Column(type: 'string', length: 300)]
    private string $summary;

    #[ORM\Column(type: 'text')]
    private string $ingredients;

    #[ORM\Column(type: 'text')]
    private string $steps;

    #[ORM\Column(type: 'integer')]
    private int $servings;

    #[ORM\Column(type: 'string', length: 100, nullable: true)]
    private ?string $photo;

    #[ORM\Column(name: 'created_at', type: 'datetime_immutable')]
    private DateTimeImmutable $createdAt;

    public function __construct(
        string $authorId,
        string $title,
        string $slug,
        string $summary,
        string $ingredients,
        string $steps,
        int $servings,
        ?string $photo = null,
    ) {
        $this->authorId    = $authorId;
        $this->title       = $title;
        $this->slug        = $slug;
        $this->summary     = $summary;
        $this->ingredients = $ingredients;
        $this->steps       = $steps;
        $this->servings    = $servings;
        $this->photo       = $photo;
        $this->createdAt   = new DateTimeImmutable();
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getAuthorId(): string
    {
        return $this->authorId;
    }

    public function getTitle(): string
    {
        return $this->title;
    }

    public function getSlug(): string
    {
        return $this->slug;
    }

    public function getPhoto(): ?string
    {
        return $this->photo;
    }
}

The views column from the migration is deliberately not mapped. Doctrine leaves unmapped columns alone, so a new row simply gets the database default of 0, and the view counter in Step 9 can update it with one cheap query instead of loading the whole entity.

Step 4: A Read Model (Reads)

Pages that mostly read data, such as lists, sidebars and counters, are a good fit for a plain PDO model: one explicit query, no object hydration. Generate it, then replace the contents.

php rhapsody make:model RecipeCatalog

app/Models/RecipeCatalog.php

<?php

declare(strict_types=1);

namespace App\Models;

use PDO;
use Rhapsody\Core\BaseModel;

/**
 * @phpstan-type RecipeRow array{id: int|string, title: string, slug: string, summary: string, photo: string|null, servings: int|string, views: int|string, created_at: string, author_name: string}
 * @phpstan-type RecipeDetail array{id: int|string, author_id: string, title: string, slug: string, summary: string, ingredients: string, steps: string, servings: int|string, photo: string|null, views: int|string, created_at: string, author_name: string}
 */
final class RecipeCatalog extends BaseModel
{
    private const string CARD_COLUMNS = 'r.id, r.title, r.slug, r.summary, r.photo, r.servings, r.views, r.created_at, u.name AS author_name';

    public function countAll(): int
    {
        $stmt = $this->db->prepare('SELECT COUNT(*) FROM recipes');
        $stmt->execute();
        $count = $stmt->fetchColumn();

        return is_numeric($count) ? (int) $count : 0;
    }

    /**
     * @return list<RecipeRow>
     */
    public function findPaginated(int $limit, int $offset): array
    {
        $stmt = $this->db->prepare(
            'SELECT ' . self::CARD_COLUMNS . '
               FROM recipes r
               JOIN users u ON u.user_id = r.author_id
              ORDER BY r.created_at DESC, r.id DESC
              LIMIT :limit OFFSET :offset'
        );
        $stmt->bindValue(':limit', $limit, PDO::PARAM_INT);
        $stmt->bindValue(':offset', $offset, PDO::PARAM_INT);
        $stmt->execute();

        /** @var list<RecipeRow> $rows */
        $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);

        return $rows;
    }

    /**
     * @return list<RecipeRow>
     */
    public function popular(int $limit): array
    {
        $stmt = $this->db->prepare(
            'SELECT ' . self::CARD_COLUMNS . '
               FROM recipes r
               JOIN users u ON u.user_id = r.author_id
              ORDER BY r.views DESC, r.id DESC
              LIMIT :limit'
        );
        $stmt->bindValue(':limit', $limit, PDO::PARAM_INT);
        $stmt->execute();

        /** @var list<RecipeRow> $rows */
        $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);

        return $rows;
    }

    /**
     * @return RecipeDetail|null
     */
    public function findBySlug(string $slug): ?array
    {
        $stmt = $this->db->prepare(
            'SELECT r.*, u.name AS author_name
               FROM recipes r
               JOIN users u ON u.user_id = r.author_id
              WHERE r.slug = :slug
              LIMIT 1'
        );
        $stmt->execute([':slug' => $slug]);

        /** @var RecipeDetail|false $row */
        $row = $stmt->fetch(PDO::FETCH_ASSOC);

        return $row === false ? null : $row;
    }

    public function incrementViews(int $id): void
    {
        $stmt = $this->db->prepare('UPDATE recipes SET views = views + 1 WHERE id = :id');
        $stmt->execute([':id' => $id]);
    }
}

The @phpstan-type lines describe the exact shape of a row, so the rest of the code (and PHPStan) knows which keys exist. Every value that came from a visitor is bound as a parameter, never concatenated into the SQL.

Portability: LIMIT :limit OFFSET :offset works on MySQL, PostgreSQL and SQLite. SQL Server uses ORDER BY ... OFFSET :offset ROWS FETCH NEXT :limit ROWS ONLY instead. If you target SQL Server, swap that clause in the two paginated queries.

Step 5: Named Routes

Give every route a name and refer to it by name from then on. Links keep working if you ever change a URL, or install the site in a subdirectory.

routes/web.php (add these lines)

<?php

use App\Controllers\RecipeController;
use Rhapsody\Core\Routing\Router;

Router::get('/recipes', [RecipeController::class, 'index'])->name('recipes.index');

// Static paths go BEFORE the {slug} wildcard: the first matching route wins,
// so /recipes/new would otherwise be read as a recipe called "new".
Router::get('/recipes/new', [RecipeController::class, 'create'])
    ->name('recipes.create')
    ->middleware('auth');
Router::post('/recipes', [RecipeController::class, 'store'])
    ->name('recipes.store')
    ->middleware('auth');

Router::get('/recipes/{slug}', [RecipeController::class, 'show'])->name('recipes.show');
Router::post('/recipes/{id}/favorite', [RecipeController::class, 'favorite'])->name('recipes.favorite');

The router passes the Request to every action first, then the route parameters in order: show(Request $request, string $slug).
->middleware('auth') uses the key from config/config.php. Visitors who are not logged in are sent to /login before your controller runs.
CSRF protection is global middleware, so every POST here is checked automatically. You only have to send the token (Steps 7 and 11).
If you use the route cache, run php rhapsody route:clear after adding routes, or the new URLs will 404.

Step 6: The Controller

Generate the file, then replace its contents with the code below. The class is built in six parts; they all belong in the same file, in this order.

php rhapsody make:controller RecipeController

6.1 Dependencies

Type-hint what you need in the constructor and the container supplies it. BaseController already gives you $this->twig, $this->cache and $this->schema, so only add what is specific to this controller.

app/Controllers/RecipeController.php

<?php

declare(strict_types=1);

namespace App\Controllers;

use App\Entities\Recipe;
use App\Events\RecipePublished;
use App\Jobs\EmailRecipeConfirmation;
use App\Models\RecipeCatalog;
use App\Services\RecipeExporter;
use Doctrine\ORM\EntityManager;
use Rhapsody\Core\BaseController;
use Rhapsody\Core\Events\EventDispatcher;
use Rhapsody\Core\Exceptions\HttpException;
use Rhapsody\Core\FileUploader;
use Rhapsody\Core\Helpers\ImageSigner;
use Rhapsody\Core\Helpers\Path;
use Rhapsody\Core\Pagination;
use Rhapsody\Core\Queue\QueueManager;
use Rhapsody\Core\Request;
use Rhapsody\Core\Response;
use Rhapsody\Core\Routing\Router;
use Rhapsody\Core\SEO\Sluggify;
use Rhapsody\Core\Session;
use Rhapsody\Core\Support\Config;
use Rhapsody\Core\Validator;
use Twig\Environment;

/**
 * @phpstan-import-type RecipeRow from RecipeCatalog
 */
final class RecipeController extends BaseController
{
    public function __construct(
        Environment $twig,
        private readonly EntityManager $em,
        private readonly RecipeCatalog $catalog,
        private readonly RecipeExporter $exporter,
        private readonly Validator $validator,
        private readonly EventDispatcher $events,
        private readonly QueueManager $queue,
        private readonly Config $config,
    ) {
        parent::__construct($twig);
    }

6.2 The list page

This action combines pagination, typed configuration, the cache, and per-page SEO metadata. Request::int() always returns an integer, so a visitor typing ?page=abc simply gets page 1.