Tempest Framework Documentation

Tempest is a modern PHP framework designed to be lightweight, powerful, and unobtrusive. It aims to provide a 'sweet spot' between the robustness of Symfony and the eloquence of Laravel by embracing modern PHP features and staying close to vanilla PHP.

Key characteristics include:

• Modern PHP First: Uses features like property hooks, attributes, and proxy objects.
• Unopinionated Structure: Does not force a specific project structure (MVC, DDD, Hexagonal, etc.); it works with your existing organization out of the box.
• Discovery-Driven: Uses a 'Discovery' mechanism to automatically handle routing, console commands, view components, event listeners, and more without manual configuration.
• Extensible: Almost any part of the framework can be replaced by implementing an interface and registering it in the container.

Discovery is Tempest's mechanism for automatically locating application components like controller actions, event handlers, and console commands without manual registration. It scans the codebase and uses composer metadata to include both your application code and package dependencies. Tempest determines the purpose of code by analyzing file names, attributes, interfaces, and return types.

final readonly class HomeController
{
    #[Get(uri: '/home')]
    public function __invoke(): View
    {
        return view('home.view.php');
    }
}

You can prevent Tempest from automatically discovering specific classes using two methods:

1. Attribute-based: Mark a class with the #[Tempest\Discovery\SkipDiscovery] attribute. This is useful for classes you want to use internally or publish via an installer, but don't want Tempest to automatically register.
2. Composer-based: Use the extra.tempest.ignore array in composer.json to exclude specific file paths. This is recommended when dealing with optional dependencies to prevent Reflection errors when those dependencies are missing.

use Tempest\Discovery\SkipDiscovery;

#[SkipDiscovery]
final readonly class UserMigration implements Migration
{
    // …
}

{
	"extra": {
		"tempest": {
			"ignore": [
				"src/OptionalDependency.php"
			]
		}
	}
}

Events in Tempest are used to decouple components. You can define them in two ways:

1. Data Classes: Best for events that need to carry specific payload information. It is recommended to use final readonly classes with no logic.
2. Enumerations: Best for simple state changes where no extra data is required. This is highly recommended for a better developer experience.

Events can be any scalar value, but classes and enums are the standard.

// Data class approach
final readonly class AircraftRegistered
{
    public function __construct(
        public string $registration,
    ) {}
}

// Enumeration approach
enum AircraftLifecycle
{
    case REGISTERED;
    case RETIRED;
}

Tempest uses PHP attributes to define routes directly on controller methods. This allows for clean, declarative routing without separate configuration files.

Example of a controller using #[Get] and #[Post] attributes:

final class BookController
{
    #[Get('/books/{book}')]
    public function show(Book $book): Response
    {
        return new Ok($book);
    }

    #[Post('/books')]
    public function store(CreateBookRequest $request): Response
    {
        $book = map($request)->to(Book::class)->save();

        return new Redirect([self::class, 'show'], book: $book->id);
    }

    // …
}

Tempest uses MessageFormat 2.0 for localization. You can override default validation messages by providing translation files (e.g., validation.en.yml).

To use a specific translation key for a property instead of the default rule-based key, apply the #[\Tempest\Validation\TranslationKey] attribute to the property. This changes the lookup path from validation_error.{rule} to validation_error.{rule}.{your_key}.

final class Book {
    #[Rules\HasLength(min: 5, max: 50)]
    #[TranslationKey('book_management.book_title')]
    public string $title;
}

// The validator will look for the key:
// validation_error.has_length.book_management.book_title

Tempest implements the MessageFormat 2.0 specification. This allows for advanced syntax including variables, pluralization, and custom formatting functions.

Example YAML syntax using a variable and a datetime function with a pattern parameter:

today:
  Today is {$today :datetime pattern=|yyyy/MM/dd|}