### Clone and Install Tempest Documentation Project

Source: https://github.com/tempestphp/tempest-docs/blob/main/CONTRIBUTING.md

This snippet demonstrates the commands to clone the Tempest documentation repository, navigate into the project directory, and install project dependencies using both Composer (for PHP) and Bun (for JavaScript/TypeScript). It also shows how to start the development servers.

```shell
git clone git@github.com:tempestphp/tempest-docs.git
cd tempest-docs
composer install
bun install
bun run dev
php tempest serve
```

--------------------------------

### PHP Database Configuration File Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

An example of a PHP configuration file that instantiates MysqlConfig using environment variables for database credentials. This file returns a configuration object that Tempest can discover and use.

```php
use Tempest\Database\Config\MysqlConfig;
use function Tempest\env;

return new MysqlConfig(
    host: env('DB_HOST'),
    post: env('DB_PORT'),
    username: env('DB_USERNAME'),
    password: env('DB_PASSWORD')
);
```

--------------------------------

### Project Structure Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

This example demonstrates a flexible project structure that Tempest supports, allowing developers to organize their code according to different architectural patterns like MVC or DDD without requiring framework adjustments. It showcases a typical directory layout for a PHP project.

```txt
.                                    .
└── src                              └── app
    ├── Authors                          ├── Controllers
    │   ├── Author.php                   │   ├── AuthorController.php
    │   ├── AuthorController.php         │   └── BookController.php
    │   └── authors.view.php             ├── Models
    ├── Books                            │   ├── Author.php
    │   ├── Book.php                     │   ├── Book.php
    │   ├── BookController.php           │   └── Chapter.php
    │   ├── Chapter.php                  ├── Services
    │   └── books.view.php               │   └── PublisherGateway.php
    ├── Publishers                       └── Views
    │   └── PublisherGateway.php             ├── authors.view.php
    └── Support                              ├── books.view.php
        └── x-base.view.php                  └── x-base.view.php
```

--------------------------------

### Tempest Discovery Implementation Example (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-27-tempest-1.md

Provides an example of implementing the Discovery interface in Tempest to automatically find and register console commands. It utilizes class reflection and attribute inspection. Requires the Tempest Discovery component.

```PHP
final class ConsoleCommandDiscovery implements Discovery
{
    use IsDiscovery;

    public function __construct(
        private readonly ConsoleConfig $consoleConfig,
    ) {}

    public function discover(DiscoveryLocation $location, ClassReflector $class): void
    {
        foreach ($class->getPublicMethods() as $method) {
            if ($consoleCommand = $method->getAttribute(ConsoleCommand::class)) {
                $this->discoveryItems->add($location, [$method, $consoleCommand]);
            }
        }
    }

    public function apply(): void
    {
        foreach ($this->discoveryItems as [$method, $consoleCommand]) {
            $this->consoleConfig->addCommand($method, $consoleCommand);
        }
    }
}
```

--------------------------------

### Install View Components with Tempest CLI

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-07-29-tempest-1-5.md

This command-line interface (CLI) command allows users to install view components from the framework or third-party packages. It provides an interactive prompt to select desired components, simplifying the integration of reusable UI elements. No specific dependencies are mentioned, but it assumes the Tempest CLI is installed.

```console
./tempest install view-components

 <dim>│</dim> <em>Select which view components you want to install</em>
 <dim>│</dim> / <dim>Filter...</dim>
 <dim>│</dim> → ⋅ x-csrf-token
 <dim>│</dim>   ⋅ x-markdown
 <dim>│</dim>   ⋅ x-input
 <dim>│</dim>   ⋅ x-icon
 
<comment>…</comment>

```

--------------------------------

### Install Tempest Alpha 6

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-24-alpha-6.md

Command to create a new project using the Tempest app skeleton with the specific alpha 6 version. This is the primary method for starting a new project with this release.

```bash
composer create-project tempest/app:1.0-alpha.6 <name>
```

--------------------------------

### Implement a custom installer for package installation in PHP

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-10-31-alpha-3.md

This PHP class implements the Installer interface to define custom logic for installing package files. It uses the PublishesFiles trait to manage file publishing and can be invoked via the Tempest CLI.

```php
use Tempest\Core\Installer;
use Tempest\Core\PublishesFiles;
use function Tempest\src_path;

final readonly class AuthInstaller implements Installer
{
    use PublishesFiles;

    public function getName(): string
    {
        return 'auth';
    }

    public function install(): void
    {
        $publishFiles = [
            __DIR__ . '/User.php' => src_path('User.php'),
            __DIR__ . '/UserMigration.php' => src_path('UserMigration.php'),
            __DIR__ . '/Permission.php' => src_path('Permission.php'),
            __DIR__ . '/PermissionMigration.php' => src_path('PermissionMigration.php'),
            __DIR__ . '/UserPermission.php' => src_path('UserPermission.php'),
            __DIR__ . '/UserPermissionMigration.php' => src_path('UserPermissionMigration.php'),
        ];

        foreach ($publishFiles as $source => $destination) {
            $this->publish(
                source: $source,
                destination: $destination,
            );
        }

        $this->publishImports();
    }
}

```

--------------------------------

### Install Vite with Tempest CLI (Shell)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-24-alpha-6.md

Enable Vite support for your project by running the Tempest CLI installation command. This command automates the setup for Vite and optionally Tailwind CSS.

```shell
~ ./tempest install vite
```

--------------------------------

### New MigratesUp Interface Example (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-09-19-migrations-in-tempest-2.md

Demonstrates the recommended approach using the `MigratesUp` interface for creating new database tables.

```php
use Tempest\Database\MigratesUp;
use Tempest\Database\QueryStatement;
use Tempest\Database\QueryStatements\CreateTableStatement;

final class CreateStoredEventTable implements MigratesUp
{
    public string $name = '2025-01-01-create_stored_events_table';

    public function up(): QueryStatement
    {
        return CreateTableStatement::forModel(StoredEvent::class)
            ->primary()
            ->text('uuid')
            ->text('eventClass')
            ->text('payload')
            ->datetime('createdAt');
    }
}
```

--------------------------------

### Defining Console Commands with Attributes

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-16-discovery-explained.md

This PHP example illustrates defining console commands using the `#[ConsoleCommand]` attribute. Tempest generates the command definition based on the method signature.

```php
use Tempest\Console\ConsoleCommand;

final readonly class BooksCommand
{
    #[ConsoleCommand]
    public function list(): void
    {
        // ./tempest books:list
    }

    #[ConsoleCommand]
    public function info(string $name): void
    {
        // ./tempest books:info "Timeline Taxi"
    }
}
```

--------------------------------

### PHP Console Command with Middleware

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

Demonstrates applying middleware to a Tempest console command. This example shows how to use built-in middleware like ForceMiddleware and CautionMiddleware, which can add pre-execution checks or optional flags to console commands, enhancing their robustness and usability.

```php
use Tempest\Console\ConsoleCommand;
use Tempest\Console\Middleware\ForceMiddleware;
use Tempest\Console\Middleware\CautionMiddleware;

final readonly class EventsReplayCommand
{
    #[ConsoleCommand(middleware: [ForceMiddleware::class, CautionMiddleware::class])]
    public function __invoke(?string $replay = null): void
    { /* … */ }
}
```

--------------------------------

### Configure Database Driver with MysqlConfig (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-24-alpha-6.md

Simplify database configuration by implementing the `DatabaseConfig` interface. This example shows setting up MySQL connection details using `MysqlConfig`, fetching credentials from environment variables.

```php
// app/Config/database.config.php

use Tempest\Database\Config\MysqlConfig;
use function Tempest\env;

return new MysqlConfig(
    host: env('DB_HOST'),
    port: env('DB_PORT'),
    username: env('DB_USERNAME'),
    password: env('DB_PASSWORD'),
    database: env('DB_DATABASE'),
);
```

--------------------------------

### Tempest Console Application Command Example (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-27-tempest-1.md

Shows how to create and define console commands using Tempest. It demonstrates dependency injection for repositories and the use of attributes to mark methods as commands, including middleware. Requires the Tempest Console component.

```PHP
final readonly class BooksCommand
{
    use HasConsole;
    
    public function __construct(
        private BookRepository $repository,
    ) {}
    
    #[ConsoleCommand]
    public function find(): void
    {
        $book = $this->search(
            'Find your book',
            $this->repository->find(...),
        );
    }

    #[ConsoleCommand(middleware: [CautionMiddleware::class])] 
    public function delete(string $title, bool $verbose = false): void 
    { /* ... */ }
}
```

--------------------------------

### Run Vite Development Server (Shell)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-24-alpha-6.md

Start your local development server using Vite with either `bun` or `npm`. This command is typically `bun run dev` or `npm run dev`.

```shell
~ bun run dev

{:hl-comment:# or npm run dev:}
```

--------------------------------

### Tempest View Engine Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-10-31-alpha-3.md

Demonstrates the syntax for the refactored Tempest View engine, showcasing component usage, conditional rendering, loops, and content inclusion. View files are compiled and cached for improved performance.

```html
<x-base title="Home">
    <x-post :foreach="$this->posts as $post">
        {!! $post->title !!}

        <span :if="$this->showDate($post)">
            {{ $post->date }}
        </span>
        <span :else>
            -
        </span>
    </x-post>
    <div :forelse>
        <p>It's quite empty here…</p>
    </div>

    <x-footer />
</x-base>
```

--------------------------------

### PHP StoredEventConfig Registration Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

Demonstrates registering a StoredEventConfig object in the container by saving it in a file ending with .config.php. This allows the config object to be autowired into other classes.

```php
use App\StoredEvents\StoredEventConfig;

return new StoredEventConfig();
```

--------------------------------

### Install Tempest Alpha 2

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-10-02-alpha-2.md

This command installs the specific alpha 2 version of the Tempest framework using Composer. Ensure you have Composer installed and configured.

```bash
composer require tempest/framework:1.0-alpha2

```

--------------------------------

### Registering Controller Actions with Routes

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-16-discovery-explained.md

This PHP snippet demonstrates how to define a controller action with a GET route using the `#[Get]` attribute. Tempest automatically discovers and registers this route.

```php
use Tempest\Router\Get;
use Tempest\View\View;

final class BookController
{
    #[Get('/books')]
    public function index(): View
    {
        // ... 
    }
}
```

--------------------------------

### Install View Components (Console Command)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-07-28-tempest-view-updates.md

This command allows users to install a selection of built-in view components or publish them into their project for customization. It hooks into third-party packages for component discovery, simplifying frontend development.

```console
./tempest install view-components

 <dim>│</dim> <em>Select which view components you want to install</em>
 <dim>│</dim> / <dim>Filter...</dim>
 <dim>│</dim> → ⋅ x-csrf-token
 <dim>│</dim>   ⋅ x-markdown
 <dim>│</dim>   ⋅ x-input
 <dim>│</dim>   ⋅ x-icon
 
<comment>…</comment>
```

--------------------------------

### Tempest View Slot Injection Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-02-02-chasing-bugs-down-rabbit-holes.md

This example demonstrates how slots are used in Tempest View. The `home.view.php` file shows how content, in this case, additional CSS styles, can be injected into a parent component's named slot (`styles`).

```php
<!-- home.view.php -->

<x-base>
    Just some normal content ending up in body

    <x-slot name="styles">
        <!-- Additional styles injected into the parent's slot: -->

        <style>
            body {
                background: red;
            }
        </style>
    </x-slot>
</x-base>
```

--------------------------------

### Install Tempest Framework Alpha 5

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-01-22-alpha-5.md

Command to install the Tempest framework version 1.0-alpha.5 using Composer. This is the primary method for adding Tempest to a project.

```bash
composer require tempest/framework:1.0-alpha.5

```

--------------------------------

### SQL Raw Database Migration

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

Shows an example of a raw SQL migration file used by Tempest. This method allows direct execution of SQL statements for database schema management, offering flexibility for complex or non-standard operations that might be cumbersome with a builder.

```sql
CREATE TABLE Publisher
(
    `id`   INTEGER,
    `name` TEXT NOT NULL
);
```

--------------------------------

### Combined MigratesUp and MigratesDown Example (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-09-19-migrations-in-tempest-2.md

Shows how to implement both `MigratesUp` and `MigratesDown` interfaces in a single migration class for scenarios requiring rollback capabilities.

```php
use Tempest\Database\MigratesUp;
use Tempest\Database\MigratesDown;
use Tempest\Database\QueryStatement;
use Tempest\Database\QueryStatements\CreateTableStatement;
use Tempest\Database\QueryStatements\DropTableStatement;

final class CreateStoredEventTable implements MigratesUp, MigratedDown
{
    public string $name = '2025-01-01-stored_events_table';

    public function up(): QueryStatement
    {
        return new CreateTableStatement('stored_events')
            ->primary()
            ->text('uuid')
            ->text('eventClass')
            ->text('payload')
            ->datetime('createdAt');
    }

    public function down(): QueryStatement
    {
        return new DropTableStatement('stored_events');
    }
}
```

--------------------------------

### PHP Database Migration Builder

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

Illustrates creating and dropping database tables using Tempest's database migration builder. This approach allows for programmatic schema management with methods for defining columns, relationships, and constraints. It also includes an example of a down method for rollback.

```php
use Tempest\Database\DatabaseMigration;
use Tempest\Database\QueryStatement;
use Tempest\Database\QueryStatements\CreateTableStatement;
use Tempest\Database\QueryStatements\DropTableStatement;

final class CreateBookTable implements DatabaseMigration
{
    public string $name = '2024-08-12_create_book_table';

    public function up(): QueryStatement|null
    {
        return new CreateTableStatement('books')
            ->primary()
            ->text('title')
            ->datetime('created_at')
            ->datetime('published_at', nullable: true)
            ->integer('author_id', unsigned: true)
            ->belongsTo('books.author_id', 'authors.id');
    }

    public function down(): QueryStatement|null
    {
        return new DropTableStatement('books');
    }
}
```

--------------------------------

### Tempest Templating Engine Example (HTML)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-27-tempest-1.md

Illustrates the use of Tempest's templating engine, which integrates seamlessly with HTML. It shows how to define base layouts, iterate over data, and conditionally display elements. Relies on Tempest's view component.

```HTML
<x-base :title="$this->seo->title">
    <ul>
        <li :foreach="$this->books as $book">
            {{ $book->title }}

            <span :if="$this->showDate($book)">
                <x-tag>
                    {{ $book->publishedAt }}
                </x-tag>
            </span>
        </li>
    </ul>
</x-base>
```

--------------------------------

### Create Tempest Project with Composer

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-05-08-beta-1.md

This command uses Composer to create a new project based on the Tempest framework. It is the standard way to initialize a new Tempest application. Ensure Composer is installed and accessible in your system's PATH.

```bash
composer create-project tempest/app <name>
```

--------------------------------

### Tempest View: x-template Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-24-alpha-6.md

Demonstrates the usage of the new `x-template` component in Tempest's view system. This component allows rendering its content directly without an extra wrapper element, simplifying template structure.

```html
<x-template :foreach="$posts as $post">
    <div>{{ $post->title }}</div>
    <span>{{ $post->description }}</span>
</x-template>
```

--------------------------------

### Laravel Route Grouping Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-11-10-route-decorators.md

Demonstrates how to define a route group with middleware and prefix in Laravel using a closure.

```php
Route::middleware([AdminMiddleware::class])
    ->prefix('/admin')
    ->group(function () {
        Route::get('/books', [BookAdminController::class, 'index']);
        Route::get('/books/{book}/show', [BookAdminController::class, 'show']);
        Route::post('/books/new', [BookAdminController::class, 'new']);
        Route::post('/books/{book}/update', [BookAdminController::class, 'update']);
        Route::delete('/books/{book}/delete', [BookAdminController::class, 'delete']);
    });
```

--------------------------------

### Example x-input View Component Source (HTML/PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-07-28-tempest-view-updates.md

Demonstrates the structure of a file-based view component in Tempest PHP. It uses PHP for logic and templating directives for dynamic content rendering, handling labels, input types, and error messages.

```html
<?php
/**
 * @var string $name
 * @var string|null $label
 * @var string|null $id
 * @var string|null $type
 * @var string|null $default
 */

use Tempest\Http\Session\Session;

use function Tempest\get;
use function Tempest\Support\str;

/** @var Session $session */
$session = get(Session::class);

$label ??= str($name)->title();
$id ??= $name;
$type ??= 'text';
$default ??= null;

$errors = $session->getErrorsFor($name);
$original = $session->getOriginalValueFor($name, $default);
?>

<div>
    <label :for="$id">{{ $label }}</label>

    <textarea :if="$type === 'textarea'" :name="$name" :id="$id">{{ $original }}</textarea>
    <input :else :type="$type" :name="$name" :id="$id" :value="$original"/>

    <div :if="$errors !== []">
        <div :foreach="$errors as $error">
            {{ $error->message() }}
        </div>
    </div>
</div>
```

--------------------------------

### Create File-Based View Components (HTML)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-24-alpha-6.md

Define reusable view components by creating PHP files in the view directory. This example shows an `x-base.view.php` component that can be used with child content.

```html
<!-- x-base.view.php -->

<html>
    <head></head>
    <body>
        <x-slot/>
    </body>
</html>
```

```html
<x-base>
  Hello World!
</x-base>
```

--------------------------------

### Tempest ORM Model and Query Example (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-27-tempest-1.md

Demonstrates the structure of a model class and how to perform database queries using Tempest's ORM. It showcases attribute-based validation and eager loading of relationships. Requires the Tempest ORM component.

```PHP
use Tempest\Validation\Rules\Length;
use App\Author;

final class Book
{
    #[Length(min: 1, max: 120)]
    public string $title;

    public ?Author $author = null;

    /** @var \App\Chapter[] */
    public array $chapters = [];
}

$book = query(Book::class)
    ->select()
    ->with('chapters', 'author')
    ->where('id = ?', $id)
    ->first();
```

--------------------------------

### Tempest ORM Repository Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-05-26-tempests-vision.md

Illustrates a 'BookRepository' for Tempest's ORM, demonstrating how to fetch a 'Book' model by its ID. It uses the `query` builder to select, join related entities ('chapters', 'author'), and filter by the ID.

```php
final class BookRepository
{
    public function findById(int $id): Book
    {
        return query(Book::class)
            ->select()
            ->with('chapters', 'author')
            ->where('id = ?', $id)
            ->first();
    }
}
```

--------------------------------

### Test Email Sending and Attachments in PHP

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-07-17-mail-component.md

Provides an example of how to test email functionality using Tempest's testing helpers. This snippet shows how to assert that an email was sent to a specific address and that a particular attachment was included, using a fluent API on the `Mailer` instance.

```php
public function test_welcome_mail()
{
    $this->mailer
        ->send(new WelcomeEmail($this->user))
        ->assertSentTo($this->user->email)
        ->assertAttached('welcome.pdf');
}
```

--------------------------------

### ORM with Database Persistence Trait (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-05-08-beta-1.md

Shows how to use the `IsDatabaseModel` trait to enable database persistence for a Book model. Includes examples of creating a new record and querying existing records with filtering, ordering, and eager loading.

```php
use Tempest\Database\IsDatabaseModel;

final class Book
{
    use IsDatabaseModel;

    // …
}

$book = Book::create(
    title: 'Timeline Taxi',
    author: $author,
    chapters: [
        new Chapter(index: 1, contents: '…'),
        new Chapter(index: 2, contents: '…'),
        new Chapter(index: 3, contents: '…'),
    ],
);

$books = Book::select()
    ->where('publishedAt > ?', new DateTimeImmutable())
    ->orderBy('title DESC')
    ->limit(10)
    ->with('author')
    ->all();

$books[0]->chapters[2]->delete();
```

--------------------------------

### Homepage with Dynamic Code Blocks Loading (PHP)

Source: https://context7.com/tempestphp/tempest-docs/llms.txt

Renders a homepage that dynamically loads and displays multiple code examples from Markdown files. It uses `glob` to find Markdown files in a specific directory and `MarkdownConverter` to convert their content for display in the view. Suitable for showcasing code snippets.

```php
use App\Web\Homepage\HomeController;
use League\CommonMark\MarkdownConverter;
use Tempest\Router\Get;
use Tempest\View\View;

final readonly class HomeController
{
    public function __construct(
        private MarkdownConverter $markdown,
    ) {}

    #[Get('/')]
    public function __invoke(): View
    {
        $codeBlocks = map_with_keys(
            glob(__DIR__ . '/codeblocks/*.md'),
            fn(string $path) => yield strip_end(basename($path), '.md')
                => $this->markdown->convert(file_get_contents($path))
        );

        return view('./home.view.php', codeBlocks: $codeBlocks);
    }
}

// Directory structure:
// src/Web/Homepage/codeblocks/
//   - routing.md
//   - controllers.md
//   - views.md
//   - console.md

// Usage in view:
// <?php foreach ($codeBlocks as $name => $content): ?>
//   <div class="code-example" data-name="<?= $name ?>">
//     <?= $content ?>
//   </div>
// <?php endforeach; ?>
```

--------------------------------

### Tempest Component Definition Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-02-02-chasing-bugs-down-rabbit-holes.md

This snippet shows a custom component 'x-base' defined using Tempest's templating syntax. It includes slots for styles and a link to a favicon. This is used to illustrate how components are structured within Tempest.

```html
<x-component name="x-base">
    <html lang="en">
    <head>
        <x-slot name="styles" />
        <link rel="icon" type="image/png" sizes="32x32" href="/favicon/favicon-32x32.png"/>
    </head>
    </html>
</x-component>
```

--------------------------------

### Combining Route Attributes and Decorators (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-11-10-route-decorators.md

Demonstrates how route decorators work alongside standard route attributes in PHP. This example shows a method decorated with multiple attributes (`Admin`, `Books`, `Get`) to define its URI and behavior.

```php
<?php

use Tempest\Http\View;

final class BookAdminController
{
    #[{:hl-type:Admin:}, {:hl-type:Books:}, {:hl-type:Get:}('/{book}/show')]
    public function show(Book $book): View { /* … */ }
    
    // …
}
```

--------------------------------

### Applying Stateless Attribute to a Route (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-11-10-route-decorators.md

Example of applying the `#[Stateless]` attribute to a route handler method in PHP. This attribute prevents session-related middleware from being applied to the route, making it stateless. It's used in conjunction with other route attributes like `#[Get]`.

```php
<?php

use Tempest\Http\Response;
use Tempest\Router\Attributes\Stateless;

class ExampleController
{
    #[Stateless, {:hl-type:Get:}('/rss')]
    public function rss(): Response {}
}
```

--------------------------------

### Using the LocalFilesystem Component in PHP

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-25-alpha-4.md

Shows the basic usage of the `LocalFilesystem` component in Tempest. It demonstrates how to instantiate the filesystem and use its methods, such as `ensureDirectoryExists`, to manage directories.

```php
use Tempest\Filesystem\LocalFilesystem;

$fs = new LocalFilesystem();

$fs->ensureDirectoryExists(root_path('.cache/discovery/partial/'));

```

--------------------------------

### Define User Creation Console Command in Laravel

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-08-unfair-advantage.md

Demonstrates Laravel's console command definition using a `$signature` property for arguments and options, and a `handle` method for the command's core logic. This approach is less verbose than Symfony but requires learning Laravel's signature string syntax.

```php
<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class MakeUser extends Command
{
    protected $signature = 'make:user {email} {password} {--admin}';

    public function handle(): void
    {
        $email = $this->argument('email');
        $password = $this->argument('password');
        $isAdmin = $this->option('admin');

        // …
    }
}
```

--------------------------------

### Install Tempest alpha 3 via Composer

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-10-31-alpha-3.md

This command installs the latest alpha version of the Tempest framework using Composer. Ensure Composer is installed and accessible in your environment.

```bash
composer require tempest/framework:1.0-alpha.3
```

--------------------------------

### Install and Configure Rector for Tempest Upgrade

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-09-16-tempest-2.md

This snippet shows how to install Rector as a dev dependency and generate a default configuration file. Rector is used to automate the upgrade process to Tempest 2.0.

```shell
composer require rector/rector --dev
vendor/bin/rector
```

--------------------------------

### Tempest Route Collision Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-30-about-route-attributes.md

Shows a potential route collision in Tempest where a specific route '/books/new' could be mistakenly matched by a dynamic route '/books/{book}'. The example demonstrates how reordering routes can resolve this.

```php
final class BookAdminController
{
    #[Get('/books/{book}')]
    public function show(Book $book): Response { /* … */ } 
    
    #[Get('/books/new')]
    public function new(): Response { /* … */ } 
}
```

--------------------------------

### Define User Creation Console Command in Tempest

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-08-unfair-advantage.md

Presents Tempest's console command definition, leveraging PHP type hints and attributes for a concise syntax. It automatically infers arguments and options from method parameters, eliminating boilerplate configuration and relying solely on PHP knowledge.

```php
<?php

namespace App\Console\Commands;

use Tempest\Console\ConsoleCommand;
use Tempest\Console\HasConsole;

final readonly class Make
{
    use HasConsole;

    #[ConsoleCommand]
    public function user(string $email, string $password, bool $isAdmin):
    {
        // …
    }
}
```

--------------------------------

### PHP Attribute Usage for Routing in Tempest

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-05-26-tempests-vision.md

Illustrates how PHP attributes are used in the Tempest framework for defining routes, specifically for a `BookController`. The `#[Get('/books/{book}')]` attribute maps a GET request to a specific controller method.

```php
final class BookController
{
    #[Get('/books/{book}')]
    public function show(Book $book): Response { /* … */ }
}
```

--------------------------------

### PHP Property Hook Example in Tempest

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-05-26-tempests-vision.md

Demonstrates the use of property hooks in PHP within the Tempest framework, a modern PHP feature embraced by Tempest for its clean syntax and functionality. This example is part of the `DatabaseMigration` interface.

```php
interface DatabaseMigration
{
    public string $name {
        get;
    }

    public function up(): ?QueryStatement;

    public function down(): ?QueryStatement;
}
```

--------------------------------

### Define User Creation Console Command in Symfony

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-08-unfair-advantage.md

Illustrates the traditional Symfony approach to defining a console command, requiring a dedicated `configure` method for arguments and options, and an `execute` method for command logic. This method is verbose and requires knowledge of Symfony's specific API.

```php
<?php

namespace App\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(name: 'make:user')]
class MakeUserCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->addArgument('email', InputArgument::REQUIRED)
            ->addArgument('password', InputArgument::REQUIRED)
            ->addOption('admin', null, InputOption::VALUE_NONE);
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $email = $input->getArgument('email');
        $password = $input->getArgument('password');
        $isAdmin = $input->getOption('admin');

        // …

        return Command::SUCCESS;
    }
}
```

--------------------------------

### Render Code Blocks with Line Numbers and Filenames (PHP)

Source: https://context7.com/tempestphp/tempest-docs/llms.txt

Renders fenced code blocks with syntax highlighting, custom line start numbers, and optional file names. The CodeBlockRenderer extracts language, start line number, and filename from the Markdown syntax. Requires a Highlighter instance.

```php
use App\Markdown\CodeBlocks\CodeBlockRenderer;
use Tempest\Highlight\Highlighter;

// Markdown input with line numbers and file name:
$markdown = <<<'MD'
```php{42} app/Controllers/UserController.php
final readonly class UserController
{
    #[Get('/users')]
    public function index(): Response
    {
        return new Ok(['users' => []]);
    }
}
```
MD;

// The renderer extracts:
// - language: "php"
// - startAt: 42 (line numbering starts at 42)
// - filename: "app/Controllers/UserController.php"

$renderer = new CodeBlockRenderer($highlighter);
// Produces:
// <div class="code-block named-code-block">
//   <div class="code-block-name">app/Controllers/UserController.php</div>
//   <pre><code>...highlighted code starting at line 42...</code></pre>
// </div>
```

--------------------------------

### PHP HTTP Response Implementations

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

Demonstrates using specific response classes like Ok and Download from Tempest's HTTP component. These classes simplify returning different types of HTTP responses from controller actions. It also shows how to create custom response classes by implementing the Response interface.

```php
use Tempest\Http\Responses\Ok;
use Tempest\Http\Responses\Download;
use Tempest\Http\Response;

final class DownloadController
{
    #[Get('/downloads')]
    public function index(): Response
    {
        // …
        
        return new Ok(/* … */);
    }
    
    #[Get('/downloads/{id}')]
    public function download(string $id): Response
    {
        // …
        
        return new Download($path);
    }
}

use Tempest\Http\Response;
use Tempest\Http\IsResponse;

final class BookCreated implements Response
{
    use IsResponse;

    public function __construct(Book $book)
    {
        $this->setStatus( Tempest\Http\Status::CREATED);
        $this->addHeader('x-book-id', $book->id);
    }
}
```

--------------------------------

### HTML5 Spec Example: Missing Closing Head Tag

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-02-02-chasing-bugs-down-rabbit-holes.md

This snippet provides an example from the HTML5 specification demonstrating how a missing closing `</head>` tag can lead to the body content being parsed as part of the head. This behavior is relevant to understanding why custom elements in the head can cause parsing errors.

```html
<hmtl>
    <head>
        <title>Chasing Bugs down Rabbit Holes</title>
    <body>
        <h1>This is the body</h1>
    </body>
</hmtl>
```

--------------------------------

### Initialize Markdown Converter with Code Highlighting (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Homepage/codeblocks/initializer.md

This snippet demonstrates the initialization of a MarkdownConverter using the MarkdownInitializer class. It configures a Highlighter with a CssTheme and a TempestViewLanguage, then sets up an Environment with a CodeBlockRenderer that utilizes the highlighter. This ensures code blocks within Markdown are properly rendered with syntax highlighting.

```php
final readonly class MarkdownInitializer implements Initializer
{
    #[Singleton]
    public function initialize(Container $container): MarkdownConverter
    {
        $highlighter = new Highlighter(new CssTheme())
            ->addLanguage(new TempestViewLanguage());
        
        $environment = new Environment()
            ->addRenderer(Code::class, new CodeBlockRenderer($highlighter));

        return new MarkdownConverter($environment);
    }
}
```

--------------------------------

### Define a Controller for Blog Posts (PHP)

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-08-static-websites-with-tempest.md

This PHP code defines a controller with two actions: `index` to display all blog posts and `show` to display a single blog post by its slug. It uses Tempest's routing attributes (`#[Get]`) and returns a `View` or `Response`. Dependencies include `BlogRepository` and `View`.

```php
final readonly class BlogController
{
    #[Get('/blog')]
    public function index(BlogRepository $repository): View
    {
        $posts = $repository->all();

        return view(__DIR__ . '/blog_index.view.php', posts: $posts);
    }

    #[Get('/blog/{slug}')]
    public function show(string $slug, BlogRepository $repository): Response|View
    {
        $post = $repository->find($slug);

        return view(__DIR__ . '/blog_show.view.php', post: $post);
    }
}
```

--------------------------------

### Creating a Controller with Tempest CLI

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-25-alpha-4.md

Demonstrates the usage of the `make:controller` command in Tempest to scaffold a new controller. The command prompts for the file location and confirms successful creation.

```console
~ ./tempest make:controller FooController
<h2>Where do you want to save the file "FooController"?</h2> app/FooController.php
<success>Controller successfully created at "app/FooController.php".</success>

```

--------------------------------

### PHP Console Command with Arguments

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-06-29-ten-tempest-tips.md

Demonstrates defining console command arguments through method signature. The EventsReplayCommand class uses type hinting and optional parameters to define its arguments, enabling automatic parsing by Tempest.

```php
final readonly class EventsReplayCommand
{
    // …

    #[ConsoleCommand]
    public function __invoke(?string $replay = null, bool $force = false): void
    { /* … */ }
}

// ./tempest events:replay PackageDownloadsPerDayProjector --force
```

--------------------------------

### GitHub API Integration - Get Stargazers Count

Source: https://context7.com/tempestphp/tempest-docs/llms.txt

Fetches and caches the stargazer count for the tempestphp/tempest-framework GitHub repository. It uses caching and environment variables for fallback.

```APIDOC
## GET /stargazers - GitHub Stargazers Count

### Description
Fetches the stargazer count for the `tempestphp/tempest-framework` GitHub repository. It utilizes caching to improve performance and supports an environment variable (`TEMPEST_BUILD_STARGAZERS`) for direct value injection during builds. Returns the count in a human-readable format or null if unavailable.

### Method
GET

### Endpoint
`/stargazers` (This is a conceptual endpoint derived from the usage of `GetStargazersCount` class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
`GET /stargazers`

### Response
#### Success Response (200)
- **stargazers** (string|null) - A human-readable string representing the stargazer count (e.g., "1.2k") or null if the count could not be retrieved.

#### Response Example
```json
{
  "stargazers": "1.2k"
}
```
Or
```json
{
  "stargazers": null
}
```
```

--------------------------------

### Laravel Route Grouping Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-30-about-route-attributes.md

Demonstrates route grouping in Laravel using middleware and prefix configuration within a group function. This allows for shared configurations across multiple routes.

```php
Route::middleware([AdminMiddleware::class])
    ->prefix('/admin')
    ->group(function () {
        Route::get('/books', [BookAdminController::class, 'index'])
        Route::get('/books/{book}/show', [BookAdminController::class, 'show'])
        Route::post('/books/new', [BookAdminController::class, 'new'])
        Route::post('/books/{book}/update', [BookAdminController::class, 'update'])
        Route::delete('/books/{book}/delete', [BookAdminController::class, 'delete'])
    });
```

--------------------------------

### Handle Package Status Check in Tempest with Exit Codes

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-08-unfair-advantage.md

Shows how to define a console command in Tempest that returns an enumerated `ExitCode`. This approach provides a clearer and more type-safe way to handle command exit statuses compared to integer return values used in other frameworks.

```php
<?php

namespace App\Console\Commands;

use Tempest\Console\ConsoleCommand;
use Tempest\Console\HasConsole;
use Tempest\Console\ExitCode;

final readonly class Package
{
    use HasConsole;

    #[ConsoleCommand]
    public function all(): ExitCode
    {
        if (! $this->hasBeenSetup()) {
            return ExitCode::ERROR;
        }

        // …

        return ExitCode::SUCCESS;
    }

    private function hasBeenSetup(): bool
    {
        // Placeholder for actual setup check
        return true;
    }
}
```

--------------------------------

### Symfony Route Attributes Example

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-11-10-route-decorators.md

Shows Symfony's approach to defining routes using attributes directly on controller classes and methods, including route naming and method specification.

```php
use Symfony\Component\Routing\Annotation\Route;

#[Route('/admin/books', name: 'admin_books_')]
class BookAdminController extends AbstractController
{
    #[Route('/', name: 'index')]
    public function index(): Response { /* ... */ } 
    
    #[Route('/{book}/show')]
    public function show(Book $book): Response { /* ... */ } 
    
    #[Route('/new', methods: ['POST'])]
    public function new(): Response { /* ... */ } 
    
    #[Route('/{book}/update', methods: ['POST'])]
    public function update(): Response { /* ... */ } 
    
    #[Route('/{book}/delete', methods: ['DELETE'])]
    public function delete(): Response { /* ... */ }
}
```

--------------------------------

### Display Loaded Configuration with `config:show` Command

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-25-alpha-4.md

The `config:show` command displays all loaded configuration files in JSON format. This is useful for debugging and potential IDE integrations. It outputs the configuration structure, including file paths and their corresponding settings.

```bash
~ ./tempest config:show
```

```json
{
    "…/vendor/tempest/framework/src/Tempest/Log/src/Config/logs.config.php": {
        "@type": "Tempest\Log\LogConfig",
        "channels": [],
        "prefix": "tempest",
        "debugLogPath": null,
        "serverLogPath": null
    },
    "…/vendor/tempest/framework/src/Tempest/Auth/src/Config/auth.config.php": {
        "@type": "Tempest\Auth\AuthConfig",
        "authenticatorClass": "Tempest\Auth\SessionAuthenticator",
        "userModelClass": "Tempest\Auth\Install\User"
    },
    {:hl-comment:// …:}
}
```

--------------------------------

### PHP Container Configuration for Custom View Renderer in Tempest

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-05-26-tempests-vision.md

Demonstrates how to replace a default framework component with a custom implementation in Tempest. This example shows how to configure the container to use a custom `ViewRenderer`.

```php
use Tempest\View\ViewRenderer;

$container->singleton(ViewRenderer::class, $myCustomViewRenderer);
```

--------------------------------

### PHP Route Discovery Implementation

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2025-03-16-discovery-explained.md

This snippet demonstrates a PHP implementation for discovering and configuring routes within the Tempest framework. It involves processing route attributes and applying configuration changes if modifications are detected. Dependencies include DiscoveredRoute, RouteAttribute, and the configurator instance.

```php
use Tempest\Routing\DiscoveredRoute;
use Tempest\Routing\RouteAttribute;

// ... other code ...

$route = DiscoveredRoute::fromRoute($routeAttribute, $method);
$this->configurator->addRoute($route);
        }

        if ($this->configurator->isDirty()) {
            $this->routeConfig->apply($this->configurator->toRouteConfig());
        }
    }
}
```

--------------------------------

### Apply Middleware to a Console Command in Tempest

Source: https://github.com/tempestphp/tempest-docs/blob/main/src/Web/Blog/articles/2024-11-08-unfair-advantage.md

Demonstrates the use of middleware in Tempest console commands, similar to HTTP middleware. The `CautionMiddleware` is applied via the `middleware` option in the `#[ConsoleCommand]` attribute, executing before the command's main logic.

```php
<?php

namespace App\Console\Commands;

use Tempest\Console\ConsoleCommand;
use Tempest\Console\HasConsole;
use Tempest\Console\Middleware\CautionMiddleware;

final readonly class Make
{
    use HasConsole;

    #[ConsoleCommand(
        middleware: [CautionMiddleware::class]
    )]
    public function user(string $email, string $password, bool $isAdmin):
    {
        // …
    }
}
```

--------------------------------

### GET /:version/:category/:slug - Documentation Content Retrieval

Source: https://context7.com/tempestphp/tempest-docs/llms.txt

Retrieves documentation content based on version, category, and slug. Handles versioning and redirects to the latest version if the specified version is not found or the content is hidden.

```APIDOC
## GET /{version}/{category}/{slug}

### Description
Retrieves documentation content based on version, category, and slug. It supports automatic redirects to the latest version if the specified version is not found or the content is hidden. Content is expected to be in markdown format within `src/Web/Documentation/content/{version}/{category}/{slug}.md`.

### Method
GET

### Endpoint
`/{version}/{category}/{slug}`

### Parameters
#### Path Parameters
- **version** (string) - Required - The documentation version (e.g., '1.0' or 'current').
- **category** (string) - Required - The category of the documentation (e.g., 'essentials').
- **slug** (string) - Required - The specific documentation page identifier (e.g., 'views').

#### Query Parameters
None

#### Request Body
None

### Request Example
`GET /1.0/essentials/views`

### Response
#### Success Response (200)
Returns a `View` object containing the rendered documentation page.

#### Response Example
(HTML content of the documentation page)

#### Error Responses
- **NotFound** (404) - If the version is invalid.
- **Redirect** (302) - If the chapter is not found or hidden.
```