Merge branch 'beta-1'

Author: brendt

composer.lock

@@ -0,0 +1,225 @@
+---
+title: Tempest is Beta
+description: |
+    Today we release the first beta version of Tempest, the PHP framework for web and console apps that gets out of your way. It's one of the final steps towards a stable 1.0 release. We'll use this beta phase to fix bugs, and we're committed to not making any breaking changes anymore, apart from experimental features.
+author: brent
+tag: Release
+---
+
+Two years ago, Tempest started out as an educational project during one of my livestreams. Since then, we've had 56 people contribute to the framework, merged 591 pull requests, resolved 455 issues, and have written around 50k lines of code. Two contributors joined the core team and dedicated a lot of their time to help make Tempest into something real. And today, we're tagging Tempest as beta.
+
+We have to be real though: we won't get it perfect from the start. Tempest is now in beta, which means we don't plan any breaking changes to stable components anymore, but it also means we expect there to be bugs. And this puts us in an underdog position: why would anyone want to use a framework that has fewer features and likely more bugs than other frameworks? 
+
+It turns out, people _do_ see value in Tempest. It's the only reason I decided to work on it in the first place: there is a group of people who _want_ to use it, even when they are aware of its current shortcomings. There is interest in a framework that embraces modern PHP without 10 to 20 years of legacy to carry with it. There is interest in a project that dares to rethink what we've gotten used to over the years. There already is a dedicated community. People already are building with Tempest. Several core members have real use cases for Tempest and are working hard to be able to use it in their own projects as soon as possible. So while Tempest is the underdog, there already seems enough reason for people to use it today.
+
+And I don't want Tempest to remain the underdog. Getting closer to that goal requires getting more people involved. We need hackers to build websites and console applications with Tempest, we need them to run into bugs and edge cases that we haven't thought of. We need entrepreneurs to look into third-party packages, we need to learn what should be improved on our side from their experience. We need you to be involved. That's the next step for Tempest.
+
+Our commitment to you is that we're doing all we can to make Tempest the best developer experience possible. Tempest is and must stay the framework that truly gets out of your way. You need to focus on your code, not on hand-holding and guiding the framework. We're still uncertain about a handful of features and have clearly marked them as [experimental](/main/extra-topics/roadmap), with tried and tested alternatives in place. We're committed to a period of bug fixing to make sure Tempest can be trusted when we release the 1.0 version.
+
+We're committed, and I hope you're intrigued to [give Tempest a go](/main/getting-started/introduction).
+
+```
+{:hl-keyword:composer:} create-project:} tempest/app:1.0-beta.1 <name>
+```
+
+All of that being said, let's look at what's new in this first beta release!
+
+## A truly decoupled ORM
+
+A long-standing issue within Tempest was our ORM: the goal of our model classes was to be truly disconnected from the database, but they weren't really. That's changed in beta.1, where we removed the `DatabaseModel` interface. Any object with typed public properties can now be considered "a model class" by the ORM:
+
+```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 = [];
+}
+```
+
+Now that these model objects aren't tied to the database, they can receive and persistent their data from anywhere, not just a database:
+
+```php
+use function Tempest\map;
+
+$books = map($json)->collection()->to(Book::class);
+
+$json = map($books)->toJson();
+```
+
+We did decide to keep the `IsDatabaseModel` trait still, because we reckon database persistence is a very common use case:
+
+```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();
+```
+
+However, we also added a new `query()` helper function that can be used instead of the `IsDatabaseModel` trait.
+
+```php
+$data = query(Book::class)
+    ->select('title', 'index')
+    ->where('title = ?', 'Timeline Taxi')
+    ->andWhere('index <> ?', '1')
+    ->orderBy('index ASC')
+    ->all();
+```
+
+We've managed to truly decouple model classes from the persistence layer, while still making them really convenient to use. This is a great example of how Tempest gets out of your way. 
+
+An important note to make here is that our ORM is one of the few experimental components within Tempest. We acknowledge that there's more work to be done to make it even better, and there might be some future breaking changes still. It's one of the prime examples where we need the community to help us learn what should be improved, and how.
+
+## tempest/view changes
+
+We've added support for [dynamic view components](/main/essentials/views#dynamic-view-components), which allows you to render view components based on runtime data:
+
+```html
+<!-- $name = 'x-post' -->
+
+<x-component :is="$name" :title="$title" />
+```
+
+We've improved [boolean attributes](/main/essentials/views#boolean-attributes), they now also work for truthy and falsy values, as well as for custom expression attributes:
+
+```html
+<div :data-active="{$isActive}"></div>
+
+<!-- <div></div> when $isActive is falsy -->
+<!-- <div data-active></div> when $isActive is truthy -->
+```
+
+Finally, we switched from PHP's built-in DOM parser to our custom implementation. We realized that trying to parse tempest/view syntax according to the official HTML spec added more problems than it solved. After all, tempest/view syntax is a superset of HTML: it compiles to spec-compliant HTML, but in itself it is not spec-compliant.
+
+Moving to a custom parser written in PHP comes with a small performance price to pay, but our implementation is slightly more performant than [masterminds/html5](https://github.com/Masterminds/html5-php), the most popular PHP-based DOM parser, and everything our parser does is cached as well. You can [check out the implementation here](https://github.com/tempestphp/tempest-framework/tree/main/packages/view/src/Parser).
+
+## Container features
+
+We've added a new interface called `HasTag`, which allows any object to manually specify its container tag. This feature is especially useful combined with config files, and allows you to define multiple config files for multiple occasions. For example, to define multiple database connections:
+
+
+```php
+return new PostgresConfig(
+    tag: 'backup',
+    
+    // …
+);
+```
+
+```php
+use Tempest\Database\Database;
+use Tempest\Container\Tag;
+
+final readonly class BackupService
+{
+    public function __construct(
+        #[Tag('backup')]
+        private Database $database,
+    ) {}
+
+    // …
+}
+```
+
+We also added support for proxy dependencies, using PHP 8.4's new object proxies. Any dependency that might be expensive to construct, but not often used, can be injected as a proxy. As a proxy, the dependency will only get resolved when actually needed:
+
+```php
+use Tempest\Container\Proxy;
+
+final readonly class BookController
+{
+    public function __construct(
+        #[Proxy] 
+        private VerySlowClass $verySlowClass
+    ) { /* … */ }
+}
+```
+
+## Middleware discovery
+
+One thing that has felt icky for a long time was that middleware classes could not be discovered (this was the case for all HTTP, console, event bus and command bus middleware). The reason for this restriction was that in some cases, it's important to ensure middleware order: some middleware must come before other, and discovery doesn't guarantee that order. This restriction doesn't match our Tempest mindset, though: we forced all middleware to be manually configured, even though only a small number of middleware classes actually needed that flexibility.
+
+So, as of beta.1, we've added middleware discovery to make the most common case very developer-friendly, and we added the tools necessary to make sure the edge cases are covered as well.
+
+First, you can skip discovery for middleware classes entirely when needed:
+
+```php
+use Tempest\Discovery\SkipDiscovery;
+use Tempest\Router\HttpMiddleware;
+
+#[SkipDiscovery]
+final readonly class ValidateWebhook implements HttpMiddleware
+{
+    public function __invoke(Request $request, HttpMiddlewareCallable $next): Response
+    {
+        // …
+    }
+}
+```
+
+And, second, you can define middleware priority for specific classes to ensure the right order when needed:
+
+```php
+use Tempest\Core\Priority;
+
+#[Priority(Priority::HIGHEST)]
+final readonly class OverviewMiddleware implements ConsoleMiddleware
+{
+    public function __invoke(Invocation $invocation, ConsoleMiddlewareCallable $next): ExitCode|int
+    {
+        // …
+    }
+}
+```
+
+## Smaller features
+
+Finishing with a couple of smaller changes, but it's these kinds of small details that make the difference in the long run. So thanks to everyone who contributed: 
+
+- We've added a couple of new commands: `make:migration` and `container:show`
+- We've added testing utilities for our event bus
+- There's a new `Back` response class to redirect to the previous page
+- We now allow controllers to also return strings and arrays directly
+- We've added a new storage component, which is a slim wrapper around [Flysystem](https://flysystem.thephpleague.com/docs/)
+- And, [a lot more](https://github.com/tempestphp/tempest-framework/releases/tag/v1.0.0-beta.1)
+
+## In closing
+
+It's amazing to see what we've achieved in a little less than two years. Tempest has grown from being a dummy project used during livestreams, to a real framework.
+
+There's a long way to go still, but I'm confident when I see how many people are contributing to and excited about Tempest. You can follow along the beta progress on [GitHub](https://github.com/tempestphp/tempest-framework/milestone/16); and you can be part of the journey as well: [give Tempest a try](/main/getting-started/getting-started) and [join our Discord server](https://tempestphp.com/discord). 
+
+See you soon!
+
+<img class="w-[1.66em] shadow-md rounded-full" src="/tempest-logo.png" alt="Tempest" />

src/Web/Blog/articles/2025-05-08-beta-1.md

@@ -26,6 +26,7 @@ public function docsRedirect(string $path): Redirect
 
     #[Get('/docs')]
     #[Get('/documentation')]
+    #[Get('/main/framework/getting-started')]
     public function index(): Redirect
     {
         $version = Version::default();

src/Web/Documentation/ChapterController.php

@@ -16,7 +16,7 @@ Once the prerequisites are installed, you can chose your installation method. Te
 To get started with a new Tempest project, you may use {`tempest/app`} as the starting point. The `composer create-project` command will scaffold it for you:
 
 ```sh
-{:hl-keyword:composer:} create-project tempest/app {:hl-type:my-app:} --stability alpha
+{:hl-keyword:composer:} create-project tempest/app {:hl-type:my-app:} --stability beta
 {:hl-keyword:cd:} {:hl-type:my-app:}
 ```
 
@@ -48,7 +48,7 @@ You may then [run the front-end development server](../1-essentials/04-asset-bun
 If you already have a project, you can opt to install {`tempest/framework`} as a standalone package. You could do this in any project; it could already contain code, or it could be an empty project.
 
 ```sh
-{:hl-keyword:composer:} require tempest/framework:1.0-alpha.6
+{:hl-keyword:composer:} require tempest/framework:1.0-beta.1
 ```
 
 Installing Tempest this way will give you access to the Tempest console, `./vendor/bin/tempest`. Optionally, you can choose to install Tempest's entry points in your project. To do so, you may run the framework installer:

src/Web/Documentation/content/main/0-getting-started/01-getting-started.md

@@ -393,16 +393,14 @@ will allow the container to instead inject a lazy proxy.
 Since lazy proxies are transparent to the consumer you do not need to change anything else in your code.
 The primary use case for this are heavy dependencies that may or may not be used.
 
-```php
-// app/BookController.php
-
-use Tempest\Container\Tag;
+```php app/BookController.php
 use Tempest\Container\Proxy;
 
 final readonly class BookController
 {
-    public function __constructor(
-        #[Proxy] VerySlowClass $verySlowClass
+    public function __construct(
+        #[Proxy] 
+        private VerySlowClass $verySlowClass
     ) { /* … */ }
 }
 ```

src/Web/Documentation/content/main/1-essentials/01-container.md

@@ -168,6 +168,15 @@ Using an expression attribute that return a boolean variable will follow the HTM
 
 Depending on whether `$selected` evaluates to `true` or `false`, the above example may or may not render the `selected` attribute.
 
+Apart from HTMLs boolean attributes, the same syntax can be used with any expression attribute as well:
+
+```html
+<div :data-active="{$isActive}"></div>
+
+<!-- <div></div> when $isActive is falsy -->
+<!-- <div data-active></div> when $isActive is truthy -->
+```
+
 ### Control flow directives
 
 #### `:if`, `:elseif` and `:else`

src/Web/Documentation/content/main/1-essentials/03-views.md

@@ -9,7 +9,7 @@ title: Standalone
 You can install `tempest/console` like so:
 
 ```
-composer require tempest/console:1.0-alpha.6
+composer require tempest/console:1.0-beta.1
 ```
 
 And run it like so:

src/Web/Documentation/content/main/3-console/07-standalone.md

@@ -42,7 +42,7 @@
         </div>
         <button data-copy="#install-tempest-snippet" class="hidden md:flex group mt-6 md:mt-8 xl:mt-10  items-center justify-start gap-x-2 text-base font-mono relative cursor-pointer">
             <x-icon name="tabler:terminal" class="size-5 text-(--ui-primary)" />
-            <span id="install-tempest-snippet" class="text-(--ui-text-muted)">composer create-project tempest/app --stability alpha</span>
+            <span id="install-tempest-snippet" class="text-(--ui-text-muted)">composer create-project tempest/app --stability beta</span>
             <span class="ml-4 flex items-center justify-center opacity-0 group-hover:opacity-100 transition text-(--ui-text-dimmed) bg-(--ui-bg-muted) rounded border border-(--ui-border)">
                 <x-icon name="tabler:copy" class="size-5 absolute" />
                 <x-icon name="tabler:copy-check-filled" class="size-5 absolute opacity-0 group-[[data-copied]]:opacity-100 transition text-(--ui-success)" />