Lines n/a 0 / 0
Functions and Methods n/a 0 / 0
Classes and Traits n/a 0 / 0
Name Lines Functions and Methods CRAP Classes and Traits
1<?php
2
3declare(strict_types=1);
4
5namespace BlueprintAU\Radiant\Database\Connections;
6
7use BlueprintAU\Collections\Collection;
8use BlueprintAU\Radiant\Database\Query\QueryBuilder;
9
10/**
11 * The generic database connection contract — the backend that runs a
12 * structured query.
13 *
14 * Every backend (SQL, CSV, HTTP, …) implements this interface; SQL-only
15 * extras (raw SQL, transactions, schema) live on {@see SqlConnection} and
16 * throw {@see \BlueprintAU\Radiant\Database\Exceptions\UnsupportedFeatureException}
17 * on backends that can't support them.
18 *
19 * @see SqlConnection
20 * @see \BlueprintAU\Radiant\Database\Exceptions\UnsupportedFeatureException
21 */
22interface ConnectionInterface
23{
24    /**
25     * Start a fluent query against a table, bound to this connection.
26     *
27     * @param  string  $identifier
28     * @return QueryBuilder
29     */
30    public function table(string $identifier): QueryBuilder;
31
32    /**
33     * Run the query and return the matching rows.
34     *
35     * @param  QueryBuilder  $query
36     * @return Collection<int,\stdClass>
37     */
38    public function select(QueryBuilder $query): Collection;
39
40    /**
41     * Run the query and return the first selected column's values, positionally.
42     *
43     * @param  QueryBuilder  $query
44     * @return Collection<int, mixed>
45     */
46    public function selectColumn(QueryBuilder $query): Collection;
47
48    /**
49     * Run the query and yield each matching row as it arrives.
50     *
51     * Consume the generator fully (or let it be garbage collected) before
52     * running another query on the connection — an unfinished cursor may
53     * hold the statement open.
54     *
55     * @param  QueryBuilder  $query
56     * @return \Generator<int,\stdClass>
57     */
58    public function cursor(QueryBuilder $query): \Generator;
59
60    /**
61     * Insert one or more rows into the table.
62     *
63     * @param  QueryBuilder  $query
64     * @param  array<string,mixed>|list<array<string,mixed>>  $values
65     * @return int
66     */
67    public function insert(QueryBuilder $query, array $values): int;
68
69    /**
70     * Insert a single row and return its generated id.
71     *
72     * @param  QueryBuilder  $query
73     * @param  array<string,mixed>  $values
74     * @return string|int|null
75     */
76    public function insertGetId(QueryBuilder $query, array $values): string|int|null;
77
78    /**
79     * Update the rows matching the query's conditions.
80     *
81     * @param  QueryBuilder  $query
82     * @param  array<string,mixed>  $values
83     * @return int
84     */
85    public function update(QueryBuilder $query, array $values): int;
86
87    /**
88     * Delete the rows matching the query's conditions.
89     *
90     * @param  QueryBuilder  $query
91     * @return int
92     */
93    public function delete(QueryBuilder $query): int;
94    
95    /**
96     * Whether this connection has been marked dead and should be discarded
97     * by a caching layer before reuse.
98     *
99     * @return bool
100     */
101    public function isStale(): bool;
102
103    /**
104     * Mark this connection dead so a caching layer rebuilds it.
105     */
106    public function markStale(): void;
107}