feat(http): support database-based sessions (#1605)

Author: innocenzi

docs/1-essentials/01-routing.md

@@ -732,22 +732,48 @@ public function store(Todo $todo): Redirect
 
 ### Session configuration
 
-Currently, there's only a built-in file session driver. More drivers are to be added in the future. By default, the session will stay valid for 10 hours, which you can overwrite by creating a `session.config.php` file:
+Tempest supports file and database-based sessions, the former being the default option. Sessions can be configured by creating a `session.config.php` file, in which the expiration time and the session driver can be specified.
+
+#### File sessions
+
+When using file-based sessions, which is the default, session data will be stored in files within the specified directory, relative to `.tempest`. You may configure the path and expiration duration like so:
 
 ```php app/Config/session.config.php
-<?php
 use Tempest\Http\Session\Config\FileSessionConfig;
 use Tempest\DateTime\Duration;
 
 return new FileSessionConfig(
-    path: 'sessions', // The path is relative to the project's cache folder
+   expiration: Duration::days(30),
+   path: 'sessions',
+);
+```
+
+#### Database sessions
+
+Tempest provides a database-based session driver, particularly useful for applications that run on multiple servers, as the session data can be shared across all instances.
+
+Before using database sessions, a dedicated table is needed. Tempest provides a migration, which may be installed in your project using its installer:
+
+```sh
+./tempest install sessions:database
+```
+
+This installer will also suggest creating the configuration file that sets up database sessions, with a default expiration of 30 days:
+
+```php app/Sessions/session.config.php
+use Tempest\Http\Session\Config\DatabaseSessionConfig;
+use Tempest\DateTime\Duration;
+
+return new DatabaseSessionConfig(
     expiration: Duration::days(30),
 );
 ```
 
 ### Session cleaning
 
-Outdated sessions should occasionally be cleaned up. Tempest comes with a built-in command to do so: `tempest 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.
+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.
 
 ## Deferring tasks
 

packages/database/src/Builder/QueryBuilders/HasConvenientWhereMethods.php

@@ -393,7 +393,7 @@ public function whereLastYear(string $field): self
     }
 
     /**
-     * Adds a `WHERE` condition for records created after a specific date.
+     * Adds a `WHERE` condition for records which specified field is after a specific date.
      *
      * @return self<TModel>
      */
@@ -403,7 +403,7 @@ public function whereAfter(string $field, DateTimeInterface|string $date): self
     }
 
     /**
-     * Adds a `WHERE` condition for records created before a specific date.
+     * Adds a `WHERE` condition for records which specified field is before a specific date.
      *
      * @return self<TModel>
      */

packages/http/src/Session/CleanupSessionsCommand.php

@@ -10,8 +10,6 @@
 use Tempest\Console\Scheduler\Every;
 use Tempest\EventBus\EventBus;
 
-use function Tempest\listen;
-
 final readonly class CleanupSessionsCommand
 {
     public function __construct(
@@ -20,10 +18,7 @@ public function __construct(
         private EventBus $eventBus,
     ) {}
 
-    #[ConsoleCommand(
-        name: 'session:clean',
-        description: 'Finds and removes all expired sessions',
-    )]
+    #[ConsoleCommand(name: 'session:clean', description: 'Finds and removes all expired sessions', aliases: ['session:cleanup'])]
     #[Schedule(Every::MINUTE)]
     public function __invoke(): void
     {

packages/http/src/Session/Config/DatabaseSessionConfig.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Http\Session\Config;
+
+use Tempest\Container\Container;
+use Tempest\DateTime\Duration;
+use Tempest\Http\Session\Managers\DatabaseSessionManager;
+use Tempest\Http\Session\SessionConfig;
+
+final class DatabaseSessionConfig implements SessionConfig
+{
+    /**
+     * @param Duration $expiration Time required for a session to expire.
+     */
+    public function __construct(
+        private(set) Duration $expiration,
+    ) {}
+
+    public function createManager(Container $container): DatabaseSessionManager
+    {
+        return $container->get(DatabaseSessionManager::class);
+    }
+}

packages/http/src/Session/Config/FileSessionConfig.php

@@ -5,18 +5,17 @@
 use Tempest\Container\Container;
 use Tempest\DateTime\Duration;
 use Tempest\Http\Session\Managers\FileSessionManager;
-use Tempest\Http\Session\Resolvers\CookieSessionIdResolver;
 use Tempest\Http\Session\SessionConfig;
 
 final class FileSessionConfig implements SessionConfig
 {
+    /**
+     * @param string $path Path to the sessions storage directory, relative to the internal storage.
+     * @param Duration $expiration Time required for a session to expire.
+     */
     public function __construct(
-        /**
-         * Path to the sessions storage directory, relative to the internal storage.
-         */
-        public string $path,
-
         public Duration $expiration,
+        public string $path = 'sessions',
     ) {}
 
     public function createManager(Container $container): FileSessionManager

packages/http/src/Session/Config/session.config.php

@@ -5,5 +5,5 @@
 
 return new FileSessionConfig(
     path: 'sessions',
-    expiration: Duration::hours(10),
+    expiration: Duration::days(30),
 );

packages/http/src/Session/Installer/CreateSessionsTable.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Http\Session\Installer;
+
+use Tempest\Database\MigratesUp;
+use Tempest\Database\QueryStatement;
+use Tempest\Database\QueryStatements\CreateTableStatement;
+use Tempest\Discovery\SkipDiscovery;
+
+#[SkipDiscovery]
+final class CreateSessionsTable implements MigratesUp
+{
+    private(set) string $name = '0000-00-00_create_sessions_table';
+
+    public function up(): QueryStatement
+    {
+        return new CreateTableStatement('sessions')
+            ->primary('id')
+            ->string('session_id')
+            ->text('data')
+            ->datetime('created_at')
+            ->datetime('last_active_at')
+            ->index('session_id');
+    }
+}

packages/http/src/Session/Installer/DatabaseSessionInstaller.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Http\Session\Installer;
+
+use Tempest\Console\Console;
+use Tempest\Console\Input\ConsoleArgumentBag;
+use Tempest\Container\Container;
+use Tempest\Core\Installer;
+use Tempest\Core\PublishesFiles;
+use Tempest\Database\Migrations\MigrationManager;
+
+use function Tempest\root_path;
+use function Tempest\src_path;
+use function Tempest\Support\Namespace\to_fqcn;
+
+final class DatabaseSessionInstaller implements Installer
+{
+    use PublishesFiles;
+
+    private(set) string $name = 'sessions:database';
+
+    public function __construct(
+        private readonly MigrationManager $migrationManager,
+        private readonly Container $container,
+        private readonly Console $console,
+        private readonly ConsoleArgumentBag $consoleArgumentBag,
+    ) {}
+
+    public function install(): void
+    {
+        $migration = $this->publish(
+            source: __DIR__ . '/CreateSessionsTable.stub.php',
+            destination: src_path('Sessions/CreateSessionsTable.php'),
+        );
+
+        $this->publish(
+            source: __DIR__ . '/session.config.stub.php',
+            destination: src_path('Sessions/session.config.php'),
+        );
+
+        $this->publishImports();
+
+        if ($migration && $this->shouldMigrate()) {
+            $this->migrationManager->executeUp(
+                migration: $this->container->get(to_fqcn($migration, root: root_path())),
+            );
+        }
+    }
+
+    private function shouldMigrate(): bool
+    {
+        $argument = $this->consoleArgumentBag->get('migrate');
+
+        if ($argument === null || ! is_bool($argument->value)) {
+            return $this->console->confirm('Do you want to execute migrations?', default: false);
+        }
+
+        return (bool) $argument->value;
+    }
+}

packages/http/src/Session/Installer/session.config.stub.php

@@ -0,0 +1,9 @@
+<?php
+
+use Tempest\DateTime\Duration;
+use Tempest\Http\Session\Config\DatabaseSessionConfig;
+use Tempest\Http\Session\Models\DatabaseSession;
+
+return new DatabaseSessionConfig(
+    expiration: Duration::days(30),
+);

packages/http/src/Session/Managers/DatabaseSession.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Http\Session\Managers;
+
+use Tempest\Database\PrimaryKey;
+use Tempest\Database\Table;
+use Tempest\DateTime\DateTime;
+
+#[Table('sessions')]
+final class DatabaseSession
+{
+    public PrimaryKey $id;
+
+    public string $session_id;
+
+    public string $data;
+
+    public DateTime $created_at;
+
+    public DateTime $last_active_at;
+}