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