Merge branch 'main' into fix-process-dependency

Author: brendt

CHANGELOG.md

@@ -1,41 +1,3 @@
 ## 2.0
 
-Tempest comes with automated upgrades for most of our breaking changes, powered by [Rector](https://getrector.com/). If you prefer to manually upgrade your project, you can review the list of all breaking changes further down this document.
-
-**If you don't have Rector installed in your project, please do so:**
-
-1. `composer require rector/rector --dev` to require rector as a dev dependency
-2. Run `vendor/bin/rector` to create a default rector config file
-
-Next, update Tempest; it's important to add the `--no-scripts` flag to prevent any errors from being thrown while updating Tempest.
-
-```sh
-composer require tempest/framework:^2.0 --no-scripts
-```
-
-Then you should add the `tempest2.php` set to your Rector config file:
-
-```php
-return RectorConfig::configure()
-    // …
-    ->withSets([__DIR__ . '/vendor/tempest/framework/packages/upgrade/src/tempest2.php']);
-```
-
-Then run `vendor/bin/rector` to update all your project files. After that, run `tempest discovery:clear` and `tempest key:generate`. The `tempest key:generate` command must only be done once per environment.
-
-Finally, carefully review and test your project, and make sure to read through the list of breaking changes below:
-
-### Breaking changes
-
-- **`Tempest\Database\Id` is now called `Tempest\Database\PrimaryKey`** (https://github.com/tempestphp/tempest-framework/pull/1458)
-- **The value property of `Tempest\Database\PrimaryKey` has been renamed from `id` to `value`** (https://github.com/tempestphp/tempest-framework/pull/1458)
-- **`Tempest\CommandBus\AsyncCommand` is now called `Tempest\CommandBus\Async`** (https://github.com/tempestphp/tempest-framework/pull/1507)
-- **You cannot longer declare view components via the `<x-component name="x-my-component">` tag. All files using this syntax must remove the wrapping `<x-component` tag and instead rename the filename to `x-my-component.view.php` (https://github.com/tempestphp/tempest-framework/pull/1439)**
-- **Validation rule names were updated** (https://github.com/tempestphp/tempest-framework/pull/1444)
-- **The `DatabaseMigration` interface was split into two** (https://github.com/tempestphp/tempest-framework/pull/1513)
-- **`\Tempest\uri` and `\Tempest\is_current_uri` are both moved to the `\Tempest\Router` namespace**
-- Cookies are now encrypted by default (https://github.com/tempestphp/tempest-framework/pull/1447) and developers must run `tempest key:generate` once per environment
-- Changes in view component variable scoping rules might affect view files (https://github.com/tempestphp/tempest-framework/pull/1435)
-- The validator now requires the translator, and should always be injected instead of manually created (https://github.com/tempestphp/tempest-framework/pull/1444)
-
-The changes in **bold** are automated when you use Rector.
+Read the 2.0 upgrade guide here: [https://tempestphp.com/blog/tempest-2](https://tempestphp.com/blog/tempest-2).

UPGRADING.md

@@ -209,7 +209,7 @@ function triggerSubsplit(): void
     );
 
     if (! $response->status->isSuccessful()) {
-        throw new Exception('Failed to update branch ruleset.');
+        throw new Exception('Failed to trigger subsplit.');
     }
 }
 
@@ -425,7 +425,10 @@ try {
         handler: fn () => updateBranchProtection(enabled: true),
     );
 
-    triggerSubsplit();
+    $console->task(
+            label: 'Trigger subsplit',
+            handler: fn () => triggerSubsplit(),
+    );
 
     $console->success(sprintf(
         'Released <em>%1$s</em>. The <href="https://github.com/tempestphp/tempest-framework/releases/tag/%1$s">GitHub release</href> will be created automatically in a few seconds.',

bin/release

@@ -20,6 +20,7 @@
         "league/commonmark": "^2.7",
         "league/flysystem": "^3.29.1",
         "league/mime-type-detection": "^1.16",
+        "league/oauth2-client": "^2.8",
         "monolog/monolog": "^3.7.0",
         "nette/php-generator": "^4.1.6",
         "nikic/php-parser": "^5.3",
@@ -45,9 +46,11 @@
         "voku/portable-ascii": "^2.0.3"
     },
     "require-dev": {
+        "adam-paterson/oauth2-slack": "^1.1",
         "aws/aws-sdk-php": "^3.338.0",
         "azure-oss/storage-blob-flysystem": "^1.2",
-        "carthage-software/mago": "^1.0.0-beta.16",
+        "carthage-software/mago": "1.0.0-beta.24",
+        "depotwarehouse/oauth2-twitch": "^1.3",
         "guzzlehttp/psr7": "^2.6.1",
         "league/flysystem-aws-s3-v3": "^3.25.1",
         "league/flysystem-ftp": "^3.25.1",
@@ -57,23 +60,34 @@
         "league/flysystem-read-only": "^3.25.1",
         "league/flysystem-sftp-v3": "^3.25.1",
         "league/flysystem-ziparchive": "^3.25.1",
+        "league/oauth2-facebook": "^2.0",
+        "league/oauth2-github": "^3.1",
+        "league/oauth2-google": "^4.0",
+        "league/oauth2-instagram": "^3.0",
+        "league/oauth2-linkedin": "^5.1",
         "masterminds/html5": "^2.9",
         "microsoft/azure-storage-blob": "^1.5",
         "mikey179/vfsstream": "^2.0@dev",
         "nesbot/carbon": "^3.8",
         "nyholm/psr7": "^1.8",
+        "patrickbussmann/oauth2-apple": "^0.3",
         "phpat/phpat": "^0.11.0",
         "phpbench/phpbench": "84.x-dev",
         "phpstan/phpstan": "^2.0",
         "phpunit/phpunit": "^12.2.3",
         "predis/predis": "^3.0.0",
+        "riskio/oauth2-auth0": "^2.4",
+        "smolblog/oauth2-twitter": "^1.0",
         "spatie/phpunit-snapshot-assertions": "^5.1.8",
         "spaze/phpstan-disallowed-calls": "^4.0",
+        "stevenmaguire/oauth2-microsoft": "^2.2",
         "symfony/amazon-mailer": "^7.2.0",
         "symfony/postmark-mailer": "^7.2.6",
         "symplify/monorepo-builder": "^11.2",
         "tempest/blade": "dev-main",
-        "twig/twig": "^3.16"
+        "thenetworg/oauth2-azure": "^2.2",
+        "twig/twig": "^3.16",
+        "wohali/oauth2-discord-new": "^1.2"
     },
     "replace": {
         "tempest/auth": "self.version",
@@ -179,13 +193,15 @@
             "packages/support/src/Regex/functions.php",
             "packages/support/src/Str/constants.php",
             "packages/support/src/Str/functions.php",
+            "packages/support/src/Uri/functions.php",
             "packages/support/src/functions.php",
             "packages/view/src/functions.php",
             "packages/vite/src/functions.php"
         ]
     },
     "autoload-dev": {
         "psr-4": {
+            "Tempest\\Auth\\Tests\\": "packages/auth/tests",
             "Tempest\\Cache\\Tests\\": "packages/cache/tests",
             "Tempest\\Clock\\Tests\\": "packages/clock/tests",
             "Tempest\\CommandBus\\Tests\\": "packages/command-bus/tests",

bun.lock

@@ -26,15 +26,13 @@ The benefit of starting from scratch like Tempest did is having a clean slate. T
 Just to name a couple of examples, Tempest uses property hooks:
 
 ```php
-interface DatabaseMigration
+interface MigratesUp
 {
     public string $name {
         get;
     }
 
-    public function up(): ?QueryStatement;
-
-    public function down(): ?QueryStatement;
+    public function up(): QueryStatement;
 }
 ```
 

composer.json

@@ -243,7 +243,7 @@ To create a view component, create a `.view.php` file that starts with `x-`. The
 
 ### Using view components
 
-All views may include a views components. In order to do so, you may simply use a component's name as a tag, including the `x-` prefix:
+All views may include a view component. In order to do so, you may simply use a component's name as a tag, including the `x-` prefix:
 
 ```html app/home.view.php
 <x-base :title="$this->post->title">
@@ -253,7 +253,7 @@ All views may include a views components. In order to do so, you may simply use
 </x-base>
 ```
 
-The example above demonstrates how to pass data to a component using an [expression attribute](#expression-attributes), as well as how pass elements as children if that component where the `<x-slot />` tag is used.
+The example above demonstrates how to pass data to a component using an [expression attribute](#expression-attributes), as well as how to pass elements as children if that component where the `<x-slot />` tag is used.
 
 ### Attributes in components
 
@@ -301,7 +301,7 @@ Similarly, the `id` attribute will always replace an existing `id` attribute on
 
 An `$attributes` variable is accessible within view components. This variable is an array that contains all attributes passed to the component, except expression attributes.
 
-Note that attributes names use `{txt}kebab-case`.
+Note that attribute names use `{txt}kebab-case`.
 
 ```html x-badge.view.php
 <span class="px-2 py-1 rounded-md text-sm bg-gray-100 text-gray-900">
@@ -348,7 +348,7 @@ A view component's slot can define a default value, which will be used when a vi
 
 ### Named slots
 
-When a single slot is not enough, names can be attached to them. When using a component with named slot, you may use the `<x-slot>` tag with a `name` attribute to render content in a named outlet:
+When a single slot is not enough, names can be attached to them. When using a component with a named slot, you may use the `<x-slot>` tag with a `name` attribute to render content in a named outlet:
 
 ```html x-base.view.php
 <html lang="en">
@@ -544,7 +544,7 @@ Iconify has a large collection of icon sets, which you may browse using the [Ic
 
 Tempest has built-in support for [Vite](https://vite.dev/), the most popular front-end development server and build tool. You may read more about [asset bundling](../2-features/05-asset-bundling.md) in the dedicated documentation.
 
-This component simply inject registered entrypoints where it is called.
+This component simply injects registered entrypoints where it is called.
 
 ```html x-base.view.php
 <html lang="en">

docs/0-getting-started/01-introduction.md

@@ -452,17 +452,16 @@ When you're persisting objects to the database, you'll need table to store its d
 
 Thanks to [discovery](../4-internals/02-discovery), `.sql` files and classes implementing the {b`Tempest\Database\DatabaseMigration`} interface are automatically registered as migrations, which means they can be stored anywhere.
 
-```php app/CreateBookTable.php
-use Tempest\Database\DatabaseMigration;
+```php
+use Tempest\Database\MigratesUp;
 use Tempest\Database\QueryStatement;
 use Tempest\Database\QueryStatements\CreateTableStatement;
-use Tempest\Database\QueryStatements\DropTableStatement;
 
-final class CreateBookTable implements DatabaseMigration
+final class CreateBookTable implements MigratesUp
 {
     public string $name = '2024-08-12_create_book_table';
 
-    public function up(): QueryStatement|null
+    public function up(): QueryStatement
     {
         return new CreateTableStatement('books')
             ->primary()
@@ -471,11 +470,6 @@ final class CreateBookTable implements DatabaseMigration
             ->datetime('published_at', nullable: true)
             ->belongsTo('books.author_id', 'authors.id');
     }
-
-    public function down(): QueryStatement|null
-    {
-        return new DropTableStatement('books');
-    }
 }
 ```
 
@@ -493,6 +487,26 @@ The file name of `{txt}.sql` migrations and the `{txt}{:hl-type:$name:}` propert
 
 Note that when using migration classes combined with query statements, Tempest will take care of the SQL dialect for you, there's support for MySQL, Postgresql, and SQLite. When using raw sql files, you'll have to pick a hard-coded SQL dialect, depending on your database requirements.
 
+### Up- and down migrations
+
+Tempest's recommendation is to only use up-migrations, which move the database's schema forward. There is also the option to create down-migrations, migrations that can roll back the schema of the database to a previous state. Dealing with down migrations is tricky, though, especially in production environments. That's why you need to explicitly implement another interface to do so: {`Tempest\Database\MigratesDown`}.
+
+```php
+use Tempest\Database\MigratesDown;
+use Tempest\Database\QueryStatement;
+use Tempest\Database\QueryStatements\DropTableStatement;
+
+final class CreateBookTable implements MigratesDown
+{
+    public string $name = '2024-08-12_drop_book_table';
+
+    public function down(): QueryStatement
+    {
+        return new DropTableStatement('books');
+    }
+}
+```
+
 ### Applying migrations
 
 A few [console commands](../3-console/02-building-console-commands) are provided to work with migrations. They are used to apply, rollback, or erase and re-apply them. When deploying your application to production, you should use the `php tempest migrate:up` to apply the latest migrations.
@@ -501,7 +515,7 @@ A few [console commands](../3-console/02-building-console-commands) are provided
 {:hl-comment:# Applies migrations that have not been run in the current environment:}
 ./tempest migrate:up
 
-{:hl-comment:# Rolls back every migration:}
+{:hl-comment:# Execute the down migrations:}
 ./tempest migrate:down
 
 {:hl-comment:# Drops all tables and rerun migrate:up:}

docs/1-essentials/02-views.md

@@ -335,7 +335,7 @@ final readonly class BookController
 
 While constructor injection is almost always the preferred way to go, Tempest also offers the ability to inject values straight into properties, without them being requested by the constructor.
 
-You may mark any property—public, protected, or private—with the `#[Inject]` attribute. Whenever a class instance is resolved via the container, its properties marked for injection will be provided the right value.
+You may mark any property—public, protected, or private—with the `#[Inject]` attribute. Whenever a class instance is resolved via the container, its properties marked for injection will be provided the right value. Tagged singletons may also be injected using the optional `tag` parameter of the `#[Inject]` attribute.
 
 ```php Tempest/Console/src/HasConsole.php
 use Tempest\Container\Inject;
@@ -386,6 +386,50 @@ class MyCommand
 
 For these edge cases, it's nicer to make the trait self-contained without having to rely on constructor injection. That's why injected properties are supported.
 
+## Decorators
+
+The container supports the [decorator pattern](https://refactoring.guru/design-patterns/decorator), which allows you to wrap objects and add new behavior to them at runtime without changing their structure. This is particularly useful for adding cross-cutting concerns like logging, caching, validation, or authentication.
+
+To create a decorator, you need to:
+
+1. Use the {b`#[Tempest\Container\Decorates]`} attribute on your decorator class
+2. Implement the same interface as the class you're decorating
+3. Accept the decorated object as a constructor parameter
+
+```php app/Cache/CacheRepository.php
+use Tempest\Container\Decorates;
+
+#[Decorates(Repository::class)]
+final readonly class CacheRepository implements Repository
+{
+    public function __construct(
+        private Repository $repository,
+        private Cache $cache,
+    ) {}
+
+    public function findById(int $id): ?Book
+    {
+        return $this->cache->resolve(
+            key: "book.{$id}",
+            callback: fn () => $this->repository->find($id)
+        );
+    }
+
+    public function save(Book $book): Book
+    {
+        $this->cache->delete("book.{$book->id}");
+
+        return $this->repository->save($book);
+    }
+}
+```
+
+When you request the `Repository` from the container, Tempest will automatically wrap the original implementation with your decorator. The decorated object (the original `Repository`) is injected into the decorator's constructor.
+
+:::info
+Decorators are discovered automatically through Tempest's [discovery](../4-internals/02-discovery.md), so you don't need to manually register them.
+:::
+
 ## Proxy loading
 
 The container supports lazy loading of dependencies using the `#[Proxy]` attribute. Using this attribute on a property (that has `#[Inject]`) or a constructor parameter