1<?php
2
3namespace Safe;
4
5use Safe\Exceptions\SqlsrvException;
6
7/**
8 * The transaction begun by sqlsrv_begin_transaction includes
9 * all statements that were executed after the call to
10 * sqlsrv_begin_transaction and before calls to
11 * sqlsrv_rollback or sqlsrv_commit.
12 * Explicit transactions should be started and committed or rolled back using
13 * these functions instead of executing SQL statements that begin and commit/roll
14 * back transactions. For more information, see
15 * SQLSRV Transactions.
16 *
17 * @param resource $conn The connection resource returned by a call to sqlsrv_connect.
18 * @throws SqlsrvException
19 *
20 */
21function sqlsrv_begin_transaction($conn): void
22{
23    error_clear_last();
24    $result = \sqlsrv_begin_transaction($conn);
25    if ($result === false) {
26        throw SqlsrvException::createFromPhpError();
27    }
28}
29
30
31/**
32 * Cancels a statement. Any results associated with the statement that have not
33 * been consumed are deleted. After sqlsrv_cancel has been
34 * called, the specified statement can be re-executed if it was created with
35 * sqlsrv_prepare. Calling sqlsrv_cancel
36 * is not necessary if all the results associated with the statement have been
37 * consumed.
38 *
39 * @param resource $stmt The statement resource to be cancelled.
40 * @throws SqlsrvException
41 *
42 */
43function sqlsrv_cancel($stmt): void
44{
45    error_clear_last();
46    $result = \sqlsrv_cancel($stmt);
47    if ($result === false) {
48        throw SqlsrvException::createFromPhpError();
49    }
50}
51
52
53/**
54 * Returns information about the client and specified connection
55 *
56 * @param resource $conn The connection about which information is returned.
57 * @return array Returns an associative array with keys described in the table below.
58 *
59 * Array returned by sqlsrv_client_info
60 *
61 *
62 *
63 * Key
64 * Description
65 *
66 *
67 *
68 *
69 * DriverDllName
70 * SQLNCLI10.DLL
71 *
72 *
73 * DriverODBCVer
74 * ODBC version (xx.yy)
75 *
76 *
77 * DriverVer
78 * SQL Server Native Client DLL version (10.5.xxx)
79 *
80 *
81 * ExtensionVer
82 * php_sqlsrv.dll version (2.0.xxx.x)
83 *
84 *
85 *
86 *
87 * @throws SqlsrvException
88 *
89 */
90function sqlsrv_client_info($conn): array
91{
92    error_clear_last();
93    $result = \sqlsrv_client_info($conn);
94    if ($result === false) {
95        throw SqlsrvException::createFromPhpError();
96    }
97    return $result;
98}
99
100
101/**
102 * Closes an open connection and releases resourses associated with the connection.
103 *
104 * @param resource $conn The connection to be closed.
105 * @throws SqlsrvException
106 *
107 */
108function sqlsrv_close($conn): void
109{
110    error_clear_last();
111    $result = \sqlsrv_close($conn);
112    if ($result === false) {
113        throw SqlsrvException::createFromPhpError();
114    }
115}
116
117
118/**
119 * Commits a transaction that was begun with sqlsrv_begin_transaction.
120 * The connection is returned to auto-commit mode after sqlsrv_commit
121 * is called. The transaction that is committed includes all statements that were
122 * executed after the call to sqlsrv_begin_transaction.
123 * Explicit transactions should be started and committed or rolled back using these
124 * functions instead of executing SQL statements that begin and commit/roll back
125 * transactions. For more information, see
126 * SQLSRV Transactions.
127 *
128 * @param resource $conn The connection on which the transaction is to be committed.
129 * @throws SqlsrvException
130 *
131 */
132function sqlsrv_commit($conn): void
133{
134    error_clear_last();
135    $result = \sqlsrv_commit($conn);
136    if ($result === false) {
137        throw SqlsrvException::createFromPhpError();
138    }
139}
140
141
142/**
143 * Changes the driver error handling and logging configurations.
144 *
145 * @param string $setting The name of the setting to set. The possible values are
146 * "WarningsReturnAsErrors", "LogSubsystems", and "LogSeverity".
147 * @param mixed $value The value of the specified setting. The following table shows possible values:
148 *
149 * Error and Logging Setting Options
150 *
151 *
152 *
153 * Setting
154 * Options
155 *
156 *
157 *
158 *
159 * WarningsReturnAsErrors
160 * 1 (TRUE) or 0 (FALSE)
161 *
162 *
163 * LogSubsystems
164 * SQLSRV_LOG_SYSTEM_ALL (-1)
165 * SQLSRV_LOG_SYSTEM_CONN (2)
166 * SQLSRV_LOG_SYSTEM_INIT (1)
167 * SQLSRV_LOG_SYSTEM_OFF (0)
168 * SQLSRV_LOG_SYSTEM_STMT (4)
169 * SQLSRV_LOG_SYSTEM_UTIL (8)
170 *
171 *
172 * LogSeverity
173 * SQLSRV_LOG_SEVERITY_ALL (-1)
174 * SQLSRV_LOG_SEVERITY_ERROR (1)
175 * SQLSRV_LOG_SEVERITY_NOTICE (4)
176 * SQLSRV_LOG_SEVERITY_WARNING (2)
177 *
178 *
179 *
180 *
181 * @throws SqlsrvException
182 *
183 */
184function sqlsrv_configure(string $setting, $value): void
185{
186    error_clear_last();
187    $result = \sqlsrv_configure($setting, $value);
188    if ($result === false) {
189        throw SqlsrvException::createFromPhpError();
190    }
191}
192
193
194/**
195 * Executes a statement prepared with sqlsrv_prepare. This
196 * function is ideal for executing a prepared statement multiple times with
197 * different parameter values.
198 *
199 * @param resource $stmt A statement resource returned by sqlsrv_prepare.
200 * @throws SqlsrvException
201 *
202 */
203function sqlsrv_execute($stmt): void
204{
205    error_clear_last();
206    $result = \sqlsrv_execute($stmt);
207    if ($result === false) {
208        throw SqlsrvException::createFromPhpError();
209    }
210}
211
212
213/**
214 * Frees all resources for the specified statement. The statement cannot be used
215 * after sqlsrv_free_stmt has been called on it. If
216 * sqlsrv_free_stmt is called on an in-progress statement
217 * that alters server state, statement execution is terminated and the statement
218 * is rolled back.
219 *
220 * @param resource $stmt The statement for which resources are freed.
221 * Note that NULL is a valid parameter value. This allows the function to be
222 * called multiple times in a script.
223 * @throws SqlsrvException
224 *
225 */
226function sqlsrv_free_stmt($stmt): void
227{
228    error_clear_last();
229    $result = \sqlsrv_free_stmt($stmt);
230    if ($result === false) {
231        throw SqlsrvException::createFromPhpError();
232    }
233}
234
235
236/**
237 * Gets field data from the currently selected row. Fields must be accessed in
238 * order. Field indices start at 0.
239 *
240 * @param resource $stmt A statement resource returned by sqlsrv_query or
241 * sqlsrv_execute.
242 * @param int $fieldIndex The index of the field to be retrieved. Field indices start at 0. Fields
243 * must be accessed in order. i.e. If you access field index 1, then field
244 * index 0 will not be available.
245 * @param int $getAsType The PHP data type for the returned field data. If this parameter is not
246 * set, the field data will be returned as its default PHP data type.
247 * For information about default PHP data types, see
248 * Default PHP Data Types
249 * in the Microsoft SQLSRV documentation.
250 * @return mixed Returns data from the specified field on success.
251 * @throws SqlsrvException
252 *
253 */
254function sqlsrv_get_field($stmt, int $fieldIndex, int $getAsType = null)
255{
256    error_clear_last();
257    if ($getAsType !== null) {
258        $result = \sqlsrv_get_field($stmt, $fieldIndex, $getAsType);
259    } else {
260        $result = \sqlsrv_get_field($stmt, $fieldIndex);
261    }
262    if ($result === false) {
263        throw SqlsrvException::createFromPhpError();
264    }
265    return $result;
266}
267
268
269/**
270 * Makes the next result of the specified statement active. Results include result
271 * sets, row counts, and output parameters.
272 *
273 * @param resource $stmt The statement on which the next result is being called.
274 * @return bool|null Returns TRUE if the next result was successfully retrieved, FALSE if an error
275 * occurred, and NULL if there are no more results to retrieve.
276 * @throws SqlsrvException
277 *
278 */
279function sqlsrv_next_result($stmt): ?bool
280{
281    error_clear_last();
282    $result = \sqlsrv_next_result($stmt);
283    if ($result === false) {
284        throw SqlsrvException::createFromPhpError();
285    }
286    return $result;
287}
288
289
290/**
291 * Retrieves the number of fields (columns) on a statement.
292 *
293 * @param resource $stmt The statement for which the number of fields is returned.
294 * sqlsrv_num_fields can be called on a statement before
295 * or after statement execution.
296 * @return int Returns the number of fields on success.
297 * @throws SqlsrvException
298 *
299 */
300function sqlsrv_num_fields($stmt): int
301{
302    error_clear_last();
303    $result = \sqlsrv_num_fields($stmt);
304    if ($result === false) {
305        throw SqlsrvException::createFromPhpError();
306    }
307    return $result;
308}
309
310
311/**
312 * Retrieves the number of rows in a result set. This function requires that the
313 * statement resource be created with a static or keyset cursor. For more information,
314 * see sqlsrv_query, sqlsrv_prepare,
315 * or Specifying a Cursor Type and Selecting Rows
316 * in the Microsoft SQLSRV documentation.
317 *
318 * @param resource $stmt The statement for which the row count is returned. The statement resource
319 * must be created with a static or keyset cursor. For more information, see
320 * sqlsrv_query, sqlsrv_prepare, or
321 * Specifying a Cursor Type and Selecting Rows
322 * in the Microsoft SQLSRV documentation.
323 * @return int Returns the number of rows retrieved on success.
324 * If a forward cursor (the default) or dynamic cursor is used, FALSE is returned.
325 * @throws SqlsrvException
326 *
327 */
328function sqlsrv_num_rows($stmt): int
329{
330    error_clear_last();
331    $result = \sqlsrv_num_rows($stmt);
332    if ($result === false) {
333        throw SqlsrvException::createFromPhpError();
334    }
335    return $result;
336}
337
338
339/**
340 * Prepares a query for execution. This function is ideal for preparing a query
341 * that will be executed multiple times with different parameter values.
342 *
343 * @param resource $conn A connection resource returned by sqlsrv_connect.
344 * @param string $sql The string that defines the query to be prepared and executed.
345 * @param array $params An array specifying parameter information when executing a parameterized
346 * query. Array elements can be any of the following:
347 *
348 * A literal value
349 * A PHP variable
350 * An array with this structure:
351 * array($value [, $direction [, $phpType [, $sqlType]]])
352 *
353 * The following table describes the elements in the array structure above:
354 * @param array $options An array specifying query property options. The supported keys are described
355 * in the following table:
356 * @return resource Returns a statement resource on success.
357 * @throws SqlsrvException
358 *
359 */
360function sqlsrv_prepare($conn, string $sql, array $params = null, array $options = null)
361{
362    error_clear_last();
363    if ($options !== null) {
364        $result = \sqlsrv_prepare($conn, $sql, $params, $options);
365    } elseif ($params !== null) {
366        $result = \sqlsrv_prepare($conn, $sql, $params);
367    } else {
368        $result = \sqlsrv_prepare($conn, $sql);
369    }
370    if ($result === false) {
371        throw SqlsrvException::createFromPhpError();
372    }
373    return $result;
374}
375
376
377/**
378 * Prepares and executes a query.
379 *
380 * @param resource $conn A connection resource returned by sqlsrv_connect.
381 * @param string $sql The string that defines the query to be prepared and executed.
382 * @param array $params An array specifying parameter information when executing a parameterized query.
383 * Array elements can be any of the following:
384 *
385 * A literal value
386 * A PHP variable
387 * An array with this structure:
388 * array($value [, $direction [, $phpType [, $sqlType]]])
389 *
390 * The following table describes the elements in the array structure above:
391 * @param array $options An array specifying query property options. The supported keys are described
392 * in the following table:
393 * @return resource Returns a statement resource on success.
394 * @throws SqlsrvException
395 *
396 */
397function sqlsrv_query($conn, string $sql, array $params = null, array $options = null)
398{
399    error_clear_last();
400    if ($options !== null) {
401        $result = \sqlsrv_query($conn, $sql, $params, $options);
402    } elseif ($params !== null) {
403        $result = \sqlsrv_query($conn, $sql, $params);
404    } else {
405        $result = \sqlsrv_query($conn, $sql);
406    }
407    if ($result === false) {
408        throw SqlsrvException::createFromPhpError();
409    }
410    return $result;
411}
412
413
414/**
415 * Rolls back a transaction that was begun with sqlsrv_begin_transaction
416 * and returns the connection to auto-commit mode.
417 *
418 * @param resource $conn The connection resource returned by a call to sqlsrv_connect.
419 * @throws SqlsrvException
420 *
421 */
422function sqlsrv_rollback($conn): void
423{
424    error_clear_last();
425    $result = \sqlsrv_rollback($conn);
426    if ($result === false) {
427        throw SqlsrvException::createFromPhpError();
428    }
429}
430