Lines 100.00% 12 / 12
Functions and Methods 100.00% 12 / 12
Classes and Traits 100.00% 1 / 1
Name Lines Functions and Methods CRAP Classes and Traits
Database 100.00% 12 / 12 100.00% 12 / 12 12 100.00% 1 / 1
 setManager 100.00% 1 / 1 100.00% 1 / 1 1
 manager 100.00% 1 / 1 100.00% 1 / 1 1
 hasManager 100.00% 1 / 1 100.00% 1 / 1 1
 clearManager 100.00% 1 / 1 100.00% 1 / 1 1
 connection 100.00% 1 / 1 100.00% 1 / 1 1
 sqlConnection 100.00% 1 / 1 100.00% 1 / 1 1
 usingConnection 100.00% 1 / 1 100.00% 1 / 1 1
 useConnection 100.00% 1 / 1 100.00% 1 / 1 1
 table 100.00% 1 / 1 100.00% 1 / 1 1
 select 100.00% 1 / 1 100.00% 1 / 1 1
 statement 100.00% 1 / 1 100.00% 1 / 1 1
 affectingStatement 100.00% 1 / 1 100.00% 1 / 1 1
1<?php
2
3declare(strict_types=1);
4
5namespace BlueprintAU\Radiant;
6
7use BlueprintAU\Collections\Collection;
8use BlueprintAU\Radiant\Database\Connections\ConnectionInterface;
9use BlueprintAU\Radiant\Database\Connections\SqlConnection;
10use BlueprintAU\Radiant\Database\DatabaseManager;
11use BlueprintAU\Radiant\Database\Exceptions\UnsupportedFeatureException;
12use BlueprintAU\Radiant\Database\Query\QueryBuilder;
13
14/**
15 * Static facade over the active {@see DatabaseManager}.
16 *
17 * Provides a global, convenient entry point for the most common database
18 * operations — connections, fluent queries, and raw SQL — without having
19 * to thread a manager instance through your code. The manager is injected
20 * once via {@see setManager()} (typically at application bootstrap) and
21 * every static call delegates to it.
22 *
23 * SQL-only operations ({@see select()}, {@see statement()} and
24 * {@see affectingStatement()}) require the active connection to be a
25 * {@see SqlConnection}; anything else throws an
26 * {@see UnsupportedFeatureException}.
27 */
28final class Database
29{
30    /**
31     * The injected manager backing every static call.
32     *
33     * @var ?DatabaseManager
34     */
35    private static ?DatabaseManager $manager = null;
36
37    /**
38     * Inject the manager that backs every static call.
39     *
40     * @param  DatabaseManager  $manager
41     */
42    public static function setManager(DatabaseManager $manager): void
43    {
44        self::$manager = $manager;
45    }
46
47    /**
48     * The injected manager, or fail when none was set.
49     *
50     * @return DatabaseManager
51     * @throws \RuntimeException
52     */
53    public static function manager(): DatabaseManager
54    {
55        return self::$manager ?? throw new \RuntimeException('Database manager not set.');
56    }
57
58    /**
59     * Whether a manager has been injected into the facade.
60     *
61     * @return bool
62     */
63    public static function hasManager(): bool
64    {
65        return self::$manager !== null;
66    }
67
68    /**
69     * Clear the injected manager.
70     */
71    public static function clearManager(): void
72    {
73        self::$manager = null;
74    }
75
76    /**
77     * Get a connection by name, building and caching it on first use.
78     *
79     * @param  string|null  $name
80     * @return ConnectionInterface
81     */
82    public static function connection(?string $name = null): ConnectionInterface
83    {
84        return self::manager()->connection($name);
85    }
86
87    /**
88     * The active connection, narrowed to a SQL connection.
89     *
90     * @param  string|null  $name
91     * @return SqlConnection
92     * @throws UnsupportedFeatureException
93     */
94    public static function sqlConnection(?string $name = null): SqlConnection
95    {
96        return self::manager()->sqlConnection($name);
97    }
98
99    /**
100     * Run a callback with a different active connection, restoring the
101     * previous one afterwards.
102     *
103     * @template T
104     * @param  string  $name
105     * @param  \Closure(): T  $callback
106     * @return T
107     */
108    public static function usingConnection(string $name, \Closure $callback): mixed
109    {
110        return self::manager()->usingConnection($name, $callback);
111    }
112
113    /**
114     * Make a named connection the active one, persistently.
115     *
116     * @param  string  $name
117     */
118    public static function useConnection(string $name): void
119    {
120        self::manager()->useConnection($name);
121    }
122
123    /**
124     * Start a fluent query against a table on the active connection.
125     *
126     * @param  string  $name
127     * @return QueryBuilder
128     */
129    public static function table(string $name): QueryBuilder
130    {
131        return self::connection()->table($name);
132    }
133
134    /**
135     * Run a raw SQL query and return every matching row as an object.
136     *
137     * @param  string  $query
138     * @param  array<string|int, mixed>  $args
139     * @return Collection<int,\stdClass>
140     */
141    public static function select(string $query, array $args = []): Collection
142    {
143        return self::sqlConnection()->selectSql($query, $args);
144    }
145
146    /**
147     * Run a raw SQL statement that returns no result set.
148     *
149     * @param  string  $query
150     * @param  array<string|int, mixed>  $args
151     */
152    public static function statement(string $query, array $args = []): void
153    {
154        self::sqlConnection()->statement($query, $args);
155    }
156
157    /**
158     * Run a raw SQL statement and return how many rows it affected.
159     *
160     * @param  string  $query
161     * @param  array<string|int, mixed>  $args
162     * @return int
163     */
164    public static function affectingStatement(string $query, array $args = []): int
165    {
166        return self::sqlConnection()->affectingStatement($query, $args);
167    }
168}