Merge branch 'main' into test-class-style-fallthrough

Author: xHeaven

.gitignore

@@ -14,6 +14,7 @@ packages/database.sqlite
 packages/database/src/database.sqlite
 src/Tempest/database.sqlite
 tests/Fixtures/database.sqlite
+tests/Fixtures/database*.sqlite
 tests/Unit/Console/test-console.log
 src/Tempest/Database/src/database.sqlite
 .env

CHANGELOG.md

@@ -2,6 +2,74 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.13.0](https://github.com/tempestphp/tempest-framework/compare/v2.12.0..2.13.0)  —  2025-12-04
+
+### 🚀 Features
+
+- **auth**: add OAuth installer (#1674) ([9c82b71](https://github.com/tempestphp/tempest-framework/commit/9c82b715b448633a704591e9b78823da28debc98))
+- **cache**: make `assertLocked` ensure that the checked lock has an expiration (#1758) ([1a2e8fb](https://github.com/tempestphp/tempest-framework/commit/1a2e8fbe90259d2bd5a8a0876d4b8fed35c5dcd7))
+- **container**: make all container properties publicly readable (#1785) ([be93ec1](https://github.com/tempestphp/tempest-framework/commit/be93ec1388ec7d253637705d4335d13a78a39f00))
+- **database**: add support for self-referencing relations (#1745) ([df2dcdc](https://github.com/tempestphp/tempest-framework/commit/df2dcdc231384d2dd359f8b621f0ae1f31a3e703))
+- **http**: add support to mark Request properties as #[SensitiveField] (#1746) ([0000c99](https://github.com/tempestphp/tempest-framework/commit/0000c99251b31d0bfa84389fb101be1560d916c3))
+
+### 🐛 Bug fixes
+
+- **auth**: correctly map user in GitHub OAuth provider (#1751) ([ad2182a](https://github.com/tempestphp/tempest-framework/commit/ad2182ac40684b78752e7f7511228688f5093c1a))
+- **auth**: pass scopes/options to auth URL builder (#1750) ([cbe54d7](https://github.com/tempestphp/tempest-framework/commit/cbe54d7f3f7e137fe43e9ad7f8837bd2f7103e9a))
+- **auth**: update outdated authenticatable import (#1752) ([5c68b96](https://github.com/tempestphp/tempest-framework/commit/5c68b968763229dfb5a78c01a80df3b1b134e6c0))
+- **cache**: support enum tags (#1756) ([678b695](https://github.com/tempestphp/tempest-framework/commit/678b69582e526e25ff545c346179bda9636f1415))
+- **cache**: add descriptions to `cache:clear` arguments (#1755) ([e324f6e](https://github.com/tempestphp/tempest-framework/commit/e324f6e767b50acd6e76e8310be12422b85e782b))
+- **command-bus**: extract uuid from pending commands when not provided (#1761) ([b787c16](https://github.com/tempestphp/tempest-framework/commit/b787c16e57f60de3bd7883944561f02fce3a661a))
+- **console**: properly normalize boolean flag names (#1762) ([c6e6867](https://github.com/tempestphp/tempest-framework/commit/c6e6867ede678b9798386bab12e1e2afaef91bc8))
+- **core**: gracefully handle missing seeders when using `db:seed` (#1759) ([450ca75](https://github.com/tempestphp/tempest-framework/commit/450ca7576c6e5a8f4f5719dd27e7d4d4a29954c9))
+- **process**: properly return exit code if missing (#1776) ([9ad1587](https://github.com/tempestphp/tempest-framework/commit/9ad158747a810db490aef43a7a6c1bcfe062d900))
+
+
+## [2.12.0](https://github.com/tempestphp/tempest-framework/compare/v2.11.0..v2.12.0)  —  2025-11-28
+
+### 🚀 Features
+
+- **eventbus**: add `#[StopsPropagation]` (#1740) ([5769ec2](https://github.com/tempestphp/tempest-framework/commit/5769ec215d96b4dbdac9a3e2fb93f97de152fca5))
+- **validation**: support nullable enums (#1739) ([a9ca8c4](https://github.com/tempestphp/tempest-framework/commit/a9ca8c4d60aca0ba4e14d0c31ce056c02415c10e))
+
+### 🐛 Bug fixes
+
+- **core**: remove php 8.5 deprecations (#1742) ([7501c1b](https://github.com/tempestphp/tempest-framework/commit/7501c1b494a2ec2e5ee27f4a8407fbdef5e484ae))
+- **support**: correct some string function oversights (#1743) ([f113128](https://github.com/tempestphp/tempest-framework/commit/f113128d71bd5fd10568f9cc07a86732f4e6a116))
+- **support**: process error message after callback in box() (#1741) ([908352a](https://github.com/tempestphp/tempest-framework/commit/908352a81969be7d4652b1c62758261b4751ee35))
+
+
+## [2.11.0](https://github.com/tempestphp/tempest-framework/compare/v2.10.0..v2.11.0)  —  2025-11-26
+
+### 🚀 Features
+
+- **core**: partial discovery loading (#1737) ([92a31c3](https://github.com/tempestphp/tempest-framework/commit/92a31c3a2ccfecbea1b0ffdf0f212af23d0b36a7))
+
+
+## [2.10.0](https://github.com/tempestphp/tempest-framework/compare/v2.9.3..v2.10.0)  —  2025-11-26
+
+### 🚀 Features
+
+- **core**: load composer dev namespaces (#1736) ([892da0c](https://github.com/tempestphp/tempest-framework/commit/892da0ce1a2b0b0b44a4b48121c4a3d7dc3e862d))
+- **database**: add ability to create a query builder from another one (#1725) ([55204a0](https://github.com/tempestphp/tempest-framework/commit/55204a05c2d69ca3376d74cb795be6fb389e28a4))
+- **tests**: support paratest (#1721) ([f5b5cd3](https://github.com/tempestphp/tempest-framework/commit/f5b5cd3f61c0d49fdeb38f97d6de861893ac4cbc))
+- **view**: fixes PHP 8.5 null offset deprecation warning (#1729) ([2349c71](https://github.com/tempestphp/tempest-framework/commit/2349c71f960f3638bed89f703d282c451b4536b8))
+
+
+## [2.9.3](https://github.com/tempestphp/tempest-framework/compare/v2.9.2..v2.9.3)  —  2025-11-20
+
+### 🐛 Bug fixes
+
+- **router**: use route registry to generate uris (#1724) ([6dc51c2](https://github.com/tempestphp/tempest-framework/commit/6dc51c29e40092379f918e6f3bd47862c2e090d1))
+
+
+## [2.9.2](https://github.com/tempestphp/tempest-framework/compare/v2.9.1..v2.9.2)  —  2025-11-19
+
+### 🐛 Bug fixes
+
+- **intl**: make pluralizer singleton (#1726) ([39b2b2d](https://github.com/tempestphp/tempest-framework/commit/39b2b2da8683a1d08b5ebabcd71f35486a85e403))
+
+
 ## [2.9.0](https://github.com/tempestphp/tempest-framework/compare/v2.8.0..v2.9.0)  —  2025-11-14
 
 ### 🚀 Features

composer.json

@@ -49,6 +49,7 @@
         "adam-paterson/oauth2-slack": "^1.1",
         "aws/aws-sdk-php": "^3.338.0",
         "azure-oss/storage-blob-flysystem": "^1.2",
+        "brianium/paratest": "^7.14",
         "carthage-software/mago": "1.0.0-beta.28",
         "depotwarehouse/oauth2-twitch": "^1.3",
         "guzzlehttp/psr7": "^2.6.1",
@@ -246,6 +247,8 @@
         "coverage": "vendor/bin/phpunit --coverage-html build/reports/html --coverage-clover build/reports/clover.xml",
         "fmt": "vendor/bin/mago fmt",
         "lint:fix": "vendor/bin/mago lint --fix --format-after-fix",
+        "style": "composer fmt && composer lint:fix",
+        "test": "composer phpunit",
         "lint": "vendor/bin/mago lint --potentially-unsafe --minimum-fail-level=note",
         "phpstan": "vendor/bin/phpstan analyse src tests --memory-limit=1G",
         "rector": "vendor/bin/rector process --no-ansi",

docs/1-essentials/01-routing.md

@@ -175,9 +175,9 @@ final class Aircraft implements Bindable
 {
     use IsDatabaseModel;
 
-    public function resolve(string $input): self
+    public static function resolve(string $input): self
     {
-        return self::find(id: $input);
+        return self::findById(id: $input);
     }
 }
 ```
@@ -193,9 +193,9 @@ final class Aircraft implements Bindable
     #[IsBindingValue]
     public string $callSign;
 
-    public function resolve(string $input): self
+    public static function resolve(string $input): self
     {
-        return self::find(id: $input);
+        return self::findById(id: $input);
     }
 }
 ```
@@ -241,7 +241,7 @@ public function docsRedirect(string $path): Redirect
 
 ## Generating URIs
 
-Tempest provides a `\Tempest\uri` function that can be used to generate a URI to a controller method. This function accepts the FQCN of the controller or a callable to a method as its first argument, and named parameters as [the rest of its arguments](https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list).
+Tempest provides a `\Tempest\Router\uri` function that can be used to generate a URI to a controller method. This function accepts the FQCN of the controller or a callable to a method as its first argument, and named parameters as [the rest of its arguments](https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list).
 
 ```php
 use function Tempest\Router\uri;
@@ -337,7 +337,7 @@ A core pattern of any web application is to access data from the current request
 
 In most situations, the data you expect to receive from a request is structured. You expect clients to send specific values, and you want them to follow specific rules.
 
-The idiomatic way to achieve this is by using request classes. They are classes with public properties that correspond to the data you want to retrieve from the request. Tempest will automatically validate these properties using PHP's type system, in addition to optional [validation attributes](../2-features/06-validation) if needed.
+The idiomatic way to achieve this is by using request classes. They are classes with public properties that correspond to the data you want to retrieve from the request. Tempest will automatically validate these properties using PHP's type system, in addition to optional [validation attributes](../2-features/03-validation) if needed.
 
 A request class must implement {`Tempest\Http\Request`} and should use the {`Tempest\Http\IsRequest`} trait, which provides the default implementation.
 
@@ -387,6 +387,33 @@ final readonly class AirportController
 The `map()` function allows mapping any data from any source into objects of your choice. You may read more about them in [their documentation](../2-features/01-mapper.md).
 :::
 
+### Sensitive fields
+
+When handling sensitive data such as passwords or tokens, you may not want these values to be stored in the session or re-displayed in forms after validation errors. You can mark request properties as sensitive using the {b`#[Tempest\Http\SensitiveField]`} attribute:
+
+```php app/ResetPasswordRequest.php
+use Tempest\Http\Request;
+use Tempest\Http\IsRequest;
+use Tempest\Http\SensitiveField;
+use Tempest\Validation\Rules\HasMinLength;
+
+final class ResetPasswordRequest implements Request
+{
+    use IsRequest;
+
+    public string $email;
+
+    #[SensitiveField]
+    #[HasMinLength(8)]
+    public string $password;
+
+    #[SensitiveField]
+    public string $password_confirmation;
+}
+```
+
+When a validation error occurs, Tempest will filter out sensitive fields from the original values stored in the session. This prevents sensitive data from being re-populated in forms after a redirect.
+
 ### Retrieving data directly
 
 For simpler use cases, you may simply retrieve a value from the body or the query parameter using the request's `get` method.
@@ -427,7 +454,7 @@ The JSON encoded header is available for when you're building APIs with Tempest.
 </x-form>
 ```
 
-`{html}<x-form>` is a view component that will automatically include the CSRF token, as well as default to sending `POST` requests. `{html}<x-input>` is a view component that renders a label, input field, and validation errors all at once. In practice, you'll likely want to make changes to these built-in view components. That's why you can run `./tempest install view-components` and select the components you want to pull into your project. You can [read more about installing view components here](/2.x/essentials/views#built-in-components).
+`{html}<x-form>` is a view component that will automatically include the CSRF token, as well as default to sending `POST` requests. `{html}<x-input>` is a view component that renders a label, input field, and validation errors all at once. In practice, you'll likely want to make changes to these built-in view components. That's why you can run `./tempest install view-components` and select the components you want to pull into your project. You can [read more about installing view components here](../1-essentials/02-views.md#built-in-components).
 
 ## Route middleware
 
@@ -919,7 +946,7 @@ return new DatabaseSessionConfig(
 
 Sessions expire based on the last activity time. This means that as long as a user is actively using your application, their session will remain valid.
 
-Outdated sessions must occasionally be cleaned up. Tempest comes with a built-in command to do so, `session:clean`. This command makes use of the [scheduler](/2.x/features/scheduling). If you have scheduling enabled, it will automatically run behind the scenes.
+Outdated sessions must occasionally be cleaned up. Tempest comes with a built-in command to do so, `session:clean`. This command makes use of the [scheduler](../2-features/11-scheduling.md). If you have scheduling enabled, it will automatically run behind the scenes.
 
 ## Deferring tasks
 

docs/1-essentials/02-views.md

@@ -502,7 +502,7 @@ This component provides a form element that will post by default and includes th
 
 ```html
 <?php
-use function \Tempest\uri;
+use function \Tempest\Router\uri;
 ?>
 
 <x-form :action="uri(StorePostController::class)">

docs/1-essentials/03-database.md

@@ -219,6 +219,10 @@ final class Book
 }
 ```
 
+:::warning
+Relation types in docblocks must always be fully qualified, and not use short class names.
+:::
+
 Tempest will infer all the information it needs to build the right queries for you. However, there might be cases where property names and type information don't map one-to-one on your database schema. In that case you can use dedicated attributes to define relations.
 
 ### Relation attributes

docs/2-features/08-events.md

@@ -159,6 +159,31 @@ final readonly class EventLoggerMiddleware implements EventBusMiddleware
 { /* … */ }
 ```
 
+## Stopping event propagation
+
+In rare cases you might want an event only to be handled by a single handler. You can use the `b{Tempest\EventBus\StopsPropagation}` attribute on both events and event handlers to achieve this:
+
+```php
+use Tempest\EventBus\StopsPropagation;
+
+#[StopsPropagation]
+final class MyEvent {}
+```
+
+```php
+use Tempest\EventBus\StopsPropagation;
+use Tempest\EventBus\EventHandler;
+
+final class MyHandler 
+{   
+    #[StopsPropagation]
+    public function handle(OtherEvent $event): void
+    {
+        // …
+    }
+}
+```
+
 ## Built-in framework events
 
 Tempest includes a few built-in events that are primarily used internally. While most applications won’t need them, you are free to listen to them if desired.

docs/2-features/17-oauth.md

@@ -12,7 +12,21 @@ This implementation is built on top of the PHP league's [OAuth client](https://g
 
 ## Getting started
 
-To get started with OAuth, you will first need to create a configuration file for your desired OAuth provider.
+Tempest provides an installer to quickly set up OAuth in your project. You can run the installer using the following command:
+
+```sh
+./tempest install auth --oauth
+```
+
+The installer will:
+- Prompt you to select one or more OAuth providers from the available options
+- Publish the necessary configuration files and controller stubs
+- Optionally add the OAuth credentials to your `.env` and `.env.example` files
+- Optionally install the required Composer dependencies for the selected providers
+
+This is the quickest way to get started with OAuth in your Tempest application.
+
+Alternatively, you can manually create a configuration file for your desired OAuth provider.
 
 Tempest provides a [different configuration object for each provider](#available-providers). For instance, if you wish to authenticate users with GitHub, you may create a `github.config.php` file returning an instance of {b`Tempest\Auth\OAuth\Config\GitHubOAuthConfig`}:
 

docs/4-internals/01-bootstrap.md

@@ -7,7 +7,7 @@ description: "Learn the steps involved in bootstrapping the framework."
 
 Here's a short summary of what booting Tempest looks like.
 
-- The entry point is either `public/index.html` or `./tempest`.
+- The entry point is either `public/index.php` or `./tempest`.
 - Tempest boots using the {b`\Tempest\Core\FrameworkKernel`}.
 - Bootstrap classes are located in the [`Tempest\Core\Kernel`](https://github.com/tempestphp/tempest-framework/tree/main/packages/core/src/Kernel) namespace.
 - First, discovery is started through the {b`\Tempest\Core\LoadDiscoveryLocations`} and {b`\Tempest\Core\LoadDiscoveryClasses`} classes.

docs/4-internals/03-view-spec.md

@@ -473,7 +473,7 @@ This component provides a form element that will post by default and includes th
 
 ```html
 <?php
-use function \Tempest\uri;
+use function \Tempest\Router\uri;
 ?>
 
 <x-form :action="uri(StorePostController::class)">