packages/ztd-query-core/src/Platform/SessionFactory.php

1<?php
2
3declare(strict_types=1);
4
5namespace ZtdQuery\Platform;
6
7use ZtdQuery\Config\ZtdConfig;
8use ZtdQuery\Connection\ConnectionInterface;
9use ZtdQuery\Session;
10
11/**
12 * Factory for creating Session instances configured for a specific database platform.
13 *
14 * Each platform package provides a concrete implementation
15 * (e.g. MySqlSessionFactory, PostgresSessionFactory, SqliteSessionFactory).
16 */
17interface SessionFactory
18{
19    /**
20     * Create a Session pre-configured for the platform.
21     *
22     * The implementation MUST:
23     * - Reflect all existing table schemas from the database via SchemaReflector
24     * - Return a Session with isEnabled() === true
25     * - Return a Session with an empty ShadowStore
26     *
27     * If schema reflection fails (connection error, permission error), the implementation
28     * MUST propagate the exception. Partial schema loading is NOT permitted.
29     *
30     * @param ConnectionInterface $connection An active database connection.
31     * @param ZtdConfig $config ZTD configuration.
32     * @return Session A fully configured session.
33     * @throws \ZtdQuery\Connection\Exception\DatabaseException If schema reflection fails.
34     */
35    public function create(ConnectionInterface $connection, ZtdConfig $config): Session;
36}
37