ci4

1
<?php
2

3
declare(strict_types=1);
4

5
/**
6
 * This file is part of CodeIgniter 4 framework.
7
 *
8
 * (c) CodeIgniter Foundation <admin@codeigniter.com>
9
 *
10
 * For the full copyright and license information, please view
11
 * the LICENSE file that was distributed with this source code.
12
 */
13

14
namespace CodeIgniter\Database;
15

16
/**
17
 * @template TConnection
18
 * @template TResult
19
 *
20
 * @property      false|object|resource $connID
21
 * @property-read string                $DBDriver
22
 */
23
interface ConnectionInterface
24
{
25
    /**
26
     * Initializes the database connection/settings.
27
     *
28
     * @return void
29
     */
30
    public function initialize();
31

32
    /**
33
     * Connect to the database.
34
     *
35
     * @return         false|object|resource
36
     * @phpstan-return false|TConnection
37
     */
38
    public function connect(bool $persistent = false);
39

40
    /**
41
     * Create a persistent database connection.
42
     *
43
     * @return         false|object|resource
44
     * @phpstan-return false|TConnection
45
     */
46
    public function persistentConnect();
47

48
    /**
49
     * Keep or establish the connection if no queries have been sent for
50
     * a length of time exceeding the server's idle timeout.
51
     *
52
     * @return void
53
     */
54
    public function reconnect();
55

56
    /**
57
     * Returns the actual connection object. If both a 'read' and 'write'
58
     * connection has been specified, you can pass either term in to
59
     * get that connection. If you pass either alias in and only a single
60
     * connection is present, it must return the sole connection.
61
     *
62
     * @return         false|object|resource
63
     * @phpstan-return false|TConnection
64
     */
65
    public function getConnection(?string $alias = null);
66

67
    /**
68
     * Select a specific database table to use.
69
     *
70
     * @return bool
71
     */
72
    public function setDatabase(string $databaseName);
73

74
    /**
75
     * Returns the name of the current database being used.
76
     */
77
    public function getDatabase(): string;
78

79
    /**
80
     * Returns the last error encountered by this connection.
81
     * Must return this format: ['code' => string|int, 'message' => string]
82
     * intval(code) === 0 means "no error".
83
     *
84
     * @return array<string, int|string>
85
     */
86
    public function error(): array;
87

88
    /**
89
     * The name of the platform in use (MySQLi, mssql, etc)
90
     */
91
    public function getPlatform(): string;
92

93
    /**
94
     * Returns a string containing the version of the database being used.
95
     */
96
    public function getVersion(): string;
97

98
    /**
99
     * Orchestrates a query against the database. Queries must use
100
     * Database\Statement objects to store the query and build it.
101
     * This method works with the cache.
102
     *
103
     * Should automatically handle different connections for read/write
104
     * queries if needed.
105
     *
106
     * @param array|string|null $binds
107
     *
108
     * @return         BaseResult|bool|Query
109
     * @phpstan-return BaseResult<TConnection, TResult>|bool|Query
110
     */
111
    public function query(string $sql, $binds = null);
112

113
    /**
114
     * Performs a basic query against the database. No binding or caching
115
     * is performed, nor are transactions handled. Simply takes a raw
116
     * query string and returns the database-specific result id.
117
     *
118
     * @return         false|object|resource
119
     * @phpstan-return false|TResult
120
     */
121
    public function simpleQuery(string $sql);
122

123
    /**
124
     * Returns an instance of the query builder for this connection.
125
     *
126
     * @param array|string $tableName Table name.
127
     *
128
     * @return BaseBuilder Builder.
129
     */
130
    public function table($tableName);
131

132
    /**
133
     * Returns the last query's statement object.
134
     *
135
     * @return Query
136
     */
137
    public function getLastQuery();
138

139
    /**
140
     * "Smart" Escaping
141
     *
142
     * Escapes data based on type.
143
     * Sets boolean and null types.
144
     *
145
     * @param array|bool|float|int|object|string|null $str
146
     *
147
     * @return         array|float|int|string
148
     * @phpstan-return ($str is array ? array : float|int|string)
149
     */
150
    public function escape($str);
151

152
    /**
153
     * Allows for custom calls to the database engine that are not
154
     * supported through our database layer.
155
     *
156
     * @param array ...$params
157
     *
158
     * @return array|bool|float|int|object|resource|string|null
159
     */
160
    public function callFunction(string $functionName, ...$params);
161

162
    /**
163
     * Determines if the statement is a write-type query or not.
164
     *
165
     * @param string $sql
166
     */
167
    public function isWriteType($sql): bool;
168
}
169