1<?php 2 3namespace Safe; 4 5use Safe\Exceptions\PgsqlException; 6 7/** 8 * pg_cancel_query cancels an asynchronous query sent with 9 * pg_send_query, pg_send_query_params 10 * or pg_send_execute. You cannot cancel a query executed using 11 * pg_query. 12 * 13 * @param resource $connection PostgreSQL database connection resource. 14 * @throws PgsqlException 15 * 16 */ 17function pg_cancel_query($connection): void 18{ 19 error_clear_last(); 20 $result = \pg_cancel_query($connection); 21 if ($result === false) { 22 throw PgsqlException::createFromPhpError(); 23 } 24} 25 26 27/** 28 * PostgreSQL supports automatic character set conversion between 29 * server and client for certain character sets. 30 * pg_client_encoding returns the client 31 * encoding as a string. The returned string will be one of the 32 * standard PostgreSQL encoding identifiers. 33 * 34 * @param resource $connection PostgreSQL database connection resource. When 35 * connection is not present, the default connection 36 * is used. The default connection is the last connection made by 37 * pg_connect or pg_pconnect. 38 * @return string The client encoding. 39 * @throws PgsqlException 40 * 41 */ 42function pg_client_encoding($connection = null): string 43{ 44 error_clear_last(); 45 if ($connection !== null) { 46 $result = \pg_client_encoding($connection); 47 } else { 48 $result = \pg_client_encoding(); 49 } 50 if ($result === false) { 51 throw PgsqlException::createFromPhpError(); 52 } 53 return $result; 54} 55 56 57/** 58 * pg_close closes the non-persistent 59 * connection to a PostgreSQL database associated with the given 60 * connection resource. 61 * 62 * If there is open large object resource on the connection, do not 63 * close the connection before closing all large object resources. 64 * 65 * @param resource $connection PostgreSQL database connection resource. When 66 * connection is not present, the default connection 67 * is used. The default connection is the last connection made by 68 * pg_connect or pg_pconnect. 69 * @throws PgsqlException 70 * 71 */ 72function pg_close($connection = null): void 73{ 74 error_clear_last(); 75 if ($connection !== null) { 76 $result = \pg_close($connection); 77 } else { 78 $result = \pg_close(); 79 } 80 if ($result === false) { 81 throw PgsqlException::createFromPhpError(); 82 } 83} 84 85 86/** 87 * pg_connect opens a connection to a 88 * PostgreSQL database specified by the 89 * connection_string. 90 * 91 * If a second call is made to pg_connect with 92 * the same connection_string as an existing connection, the 93 * existing connection will be returned unless you pass 94 * PGSQL_CONNECT_FORCE_NEW as 95 * connect_type. 96 * 97 * The old syntax with multiple parameters 98 * $conn = pg_connect("host", "port", "options", "tty", "dbname") 99 * has been deprecated. 100 * 101 * @param string $connection_string The connection_string can be empty to use all default parameters, or it 102 * can contain one or more parameter settings separated by whitespace. 103 * Each parameter setting is in the form keyword = value. Spaces around 104 * the equal sign are optional. To write an empty value or a value 105 * containing spaces, surround it with single quotes, e.g., keyword = 106 * 'a value'. Single quotes and backslashes within the value must be 107 * escaped with a backslash, i.e., \' and \\. 108 * 109 * The currently recognized parameter keywords are: 110 * host, hostaddr, port, 111 * dbname (defaults to value of user), 112 * user, 113 * password, connect_timeout, 114 * options, tty (ignored), sslmode, 115 * requiressl (deprecated in favor of sslmode), and 116 * service. Which of these arguments exist depends 117 * on your PostgreSQL version. 118 * 119 * The options parameter can be used to set command line parameters 120 * to be invoked by the server. 121 * @param int $connect_type If PGSQL_CONNECT_FORCE_NEW is passed, then a new connection 122 * is created, even if the connection_string is identical to 123 * an existing connection. 124 * 125 * If PGSQL_CONNECT_ASYNC is given, then the 126 * connection is established asynchronously. The state of the connection 127 * can then be checked via pg_connect_poll or 128 * pg_connection_status. 129 * @return resource PostgreSQL connection resource on success, FALSE on failure. 130 * @throws PgsqlException 131 * 132 */ 133function pg_connect(string $connection_string, int $connect_type = null) 134{ 135 error_clear_last(); 136 if ($connect_type !== null) { 137 $result = \pg_connect($connection_string, $connect_type); 138 } else { 139 $result = \pg_connect($connection_string); 140 } 141 if ($result === false) { 142 throw PgsqlException::createFromPhpError(); 143 } 144 return $result; 145} 146 147 148/** 149 * pg_connection_reset resets the connection. 150 * It is useful for error recovery. 151 * 152 * @param resource $connection PostgreSQL database connection resource. 153 * @throws PgsqlException 154 * 155 */ 156function pg_connection_reset($connection): void 157{ 158 error_clear_last(); 159 $result = \pg_connection_reset($connection); 160 if ($result === false) { 161 throw PgsqlException::createFromPhpError(); 162 } 163} 164 165 166/** 167 * pg_convert checks and converts the values in 168 * assoc_array into suitable values for use in an SQL 169 * statement. Precondition for pg_convert is the 170 * existence of a table table_name which has at least 171 * as many columns as assoc_array has elements. The 172 * fieldnames in table_name must match the indices in 173 * assoc_array and the corresponding datatypes must be 174 * compatible. Returns an array with the converted values on success, FALSE 175 * otherwise. 176 * 177 * @param resource $connection PostgreSQL database connection resource. 178 * @param string $table_name Name of the table against which to convert types. 179 * @param array $assoc_array Data to be converted. 180 * @param int $options Any number of PGSQL_CONV_IGNORE_DEFAULT, 181 * PGSQL_CONV_FORCE_NULL or 182 * PGSQL_CONV_IGNORE_NOT_NULL, combined. 183 * @return array An array of converted values. 184 * @throws PgsqlException 185 * 186 */ 187function pg_convert($connection, string $table_name, array $assoc_array, int $options = 0): array 188{ 189 error_clear_last(); 190 $result = \pg_convert($connection, $table_name, $assoc_array, $options); 191 if ($result === false) { 192 throw PgsqlException::createFromPhpError(); 193 } 194 return $result; 195} 196 197 198/** 199 * pg_copy_from inserts records into a table from 200 * rows. It issues a COPY FROM SQL command 201 * internally to insert records. 202 * 203 * @param resource $connection PostgreSQL database connection resource. 204 * @param string $table_name Name of the table into which to copy the rows. 205 * @param array $rows An array of data to be copied into table_name. 206 * Each value in rows becomes a row in table_name. 207 * Each value in rows should be a delimited string of the values 208 * to insert into each field. Values should be linefeed terminated. 209 * @param string $delimiter The token that separates values for each field in each element of 210 * rows. Default is TAB. 211 * @param string $null_as How SQL NULL values are represented in the 212 * rows. Default is \N ("\\N"). 213 * @throws PgsqlException 214 * 215 */ 216function pg_copy_from($connection, string $table_name, array $rows, string $delimiter = null, string $null_as = null): void 217{ 218 error_clear_last(); 219 if ($null_as !== null) { 220 $result = \pg_copy_from($connection, $table_name, $rows, $delimiter, $null_as); 221 } elseif ($delimiter !== null) { 222 $result = \pg_copy_from($connection, $table_name, $rows, $delimiter); 223 } else { 224 $result = \pg_copy_from($connection, $table_name, $rows); 225 } 226 if ($result === false) { 227 throw PgsqlException::createFromPhpError(); 228 } 229} 230 231 232/** 233 * pg_copy_to copies a table to an array. It 234 * issues COPY TO SQL command internally to 235 * retrieve records. 236 * 237 * @param resource $connection PostgreSQL database connection resource. 238 * @param string $table_name Name of the table from which to copy the data into rows. 239 * @param string $delimiter The token that separates values for each field in each element of 240 * rows. Default is TAB. 241 * @param string $null_as How SQL NULL values are represented in the 242 * rows. Default is \N ("\\N"). 243 * @return array An array with one element for each line of COPY data. 244 * It returns FALSE on failure. 245 * @throws PgsqlException 246 * 247 */ 248function pg_copy_to($connection, string $table_name, string $delimiter = null, string $null_as = null): array 249{ 250 error_clear_last(); 251 if ($null_as !== null) { 252 $result = \pg_copy_to($connection, $table_name, $delimiter, $null_as); 253 } elseif ($delimiter !== null) { 254 $result = \pg_copy_to($connection, $table_name, $delimiter); 255 } else { 256 $result = \pg_copy_to($connection, $table_name); 257 } 258 if ($result === false) { 259 throw PgsqlException::createFromPhpError(); 260 } 261 return $result; 262} 263 264 265/** 266 * pg_dbname returns the name of the database 267 * that the given PostgreSQL connection 268 * resource. 269 * 270 * @param resource $connection PostgreSQL database connection resource. When 271 * connection is not present, the default connection 272 * is used. The default connection is the last connection made by 273 * pg_connect or pg_pconnect. 274 * @return string A string containing the name of the database the 275 * connection is to. 276 * @throws PgsqlException 277 * 278 */ 279function pg_dbname($connection = null): string 280{ 281 error_clear_last(); 282 if ($connection !== null) { 283 $result = \pg_dbname($connection); 284 } else { 285 $result = \pg_dbname(); 286 } 287 if ($result === false) { 288 throw PgsqlException::createFromPhpError(); 289 } 290 return $result; 291} 292 293 294/** 295 * pg_delete deletes records from a table 296 * specified by the keys and values 297 * in assoc_array. If options 298 * is specified, pg_convert is applied 299 * to assoc_array with the specified options. 300 * 301 * If options is specified, 302 * pg_convert is applied to 303 * assoc_array with the specified flags. 304 * 305 * By default pg_delete passes raw values. Values 306 * must be escaped or PGSQL_DML_ESCAPE option must be 307 * specified. PGSQL_DML_ESCAPE quotes and escapes 308 * parameters/identifiers. Therefore, table/column names became case 309 * sensitive. 310 * 311 * Note that neither escape nor prepared query can protect LIKE query, 312 * JSON, Array, Regex, etc. These parameters should be handled 313 * according to their contexts. i.e. Escape/validate values. 314 * 315 * @param resource $connection PostgreSQL database connection resource. 316 * @param string $table_name Name of the table from which to delete rows. 317 * @param array $assoc_array An array whose keys are field names in the table table_name, 318 * and whose values are the values of those fields that are to be deleted. 319 * @param int $options Any number of PGSQL_CONV_FORCE_NULL, 320 * PGSQL_DML_NO_CONV, 321 * PGSQL_DML_ESCAPE, 322 * PGSQL_DML_EXEC, 323 * PGSQL_DML_ASYNC or 324 * PGSQL_DML_STRING combined. If PGSQL_DML_STRING is part of the 325 * options then query string is returned. When PGSQL_DML_NO_CONV 326 * or PGSQL_DML_ESCAPE is set, it does not call pg_convert internally. 327 * @return mixed Returns TRUE on success. Returns string if PGSQL_DML_STRING is passed 328 * via options. 329 * @throws PgsqlException 330 * 331 */ 332function pg_delete($connection, string $table_name, array $assoc_array, int $options = PGSQL_DML_EXEC) 333{ 334 error_clear_last(); 335 $result = \pg_delete($connection, $table_name, $assoc_array, $options); 336 if ($result === false) { 337 throw PgsqlException::createFromPhpError(); 338 } 339 return $result; 340} 341 342 343/** 344 * pg_end_copy syncs the PostgreSQL frontend 345 * (usually a web server process) with the PostgreSQL server after 346 * doing a copy operation performed by 347 * pg_put_line. pg_end_copy 348 * must be issued, otherwise the PostgreSQL server may get out of 349 * sync with the frontend and will report an error. 350 * 351 * @param resource $connection PostgreSQL database connection resource. When 352 * connection is not present, the default connection 353 * is used. The default connection is the last connection made by 354 * pg_connect or pg_pconnect. 355 * @throws PgsqlException 356 * 357 */ 358function pg_end_copy($connection = null): void 359{ 360 error_clear_last(); 361 if ($connection !== null) { 362 $result = \pg_end_copy($connection); 363 } else { 364 $result = \pg_end_copy(); 365 } 366 if ($result === false) { 367 throw PgsqlException::createFromPhpError(); 368 } 369} 370 371 372/** 373 * Sends a request to execute a prepared statement with given parameters, and 374 * waits for the result. 375 * 376 * pg_execute is like pg_query_params, 377 * but the command to be executed is 378 * specified by naming a previously-prepared statement, instead of giving a 379 * query string. This feature allows commands that will be used repeatedly to 380 * be parsed and planned just once, rather than each time they are executed. 381 * The statement must have been prepared previously in the current session. 382 * pg_execute is supported only against PostgreSQL 7.4 or 383 * higher connections; it will fail when using earlier versions. 384 * 385 * The parameters are identical to pg_query_params, except that the name of a 386 * prepared statement is given instead of a query string. 387 * 388 * @param resource $connection PostgreSQL database connection resource. When 389 * connection is not present, the default connection 390 * is used. The default connection is the last connection made by 391 * pg_connect or pg_pconnect. 392 * @param string $stmtname The name of the prepared statement to execute. if 393 * "" is specified, then the unnamed statement is executed. The name must have 394 * been previously prepared using pg_prepare, 395 * pg_send_prepare or a PREPARE SQL 396 * command. 397 * @param array $params An array of parameter values to substitute for the $1, $2, etc. placeholders 398 * in the original prepared query string. The number of elements in the array 399 * must match the number of placeholders. 400 * 401 * Elements are converted to strings by calling this function. 402 * @return resource A query result resource on success. 403 * @throws PgsqlException 404 * 405 */ 406function pg_execute($connection = null, string $stmtname = null, array $params = null) 407{ 408 error_clear_last(); 409 if ($params !== null) { 410 $result = \pg_execute($connection, $stmtname, $params); 411 } elseif ($stmtname !== null) { 412 $result = \pg_execute($connection, $stmtname); 413 } elseif ($connection !== null) { 414 $result = \pg_execute($connection); 415 } else { 416 $result = \pg_execute(); 417 } 418 if ($result === false) { 419 throw PgsqlException::createFromPhpError(); 420 } 421 return $result; 422} 423 424 425/** 426 * pg_field_name returns the name of the field 427 * occupying the given field_number in the 428 * given PostgreSQL result resource. Field 429 * numbering starts from 0. 430 * 431 * @param resource $result PostgreSQL query result resource, returned by pg_query, 432 * pg_query_params or pg_execute 433 * (among others). 434 * @param int $field_number Field number, starting from 0. 435 * @return string The field name. 436 * @throws PgsqlException 437 * 438 */ 439function pg_field_name($result, int $field_number): string 440{ 441 error_clear_last(); 442 $result = \pg_field_name($result, $field_number); 443 if ($result === false) { 444 throw PgsqlException::createFromPhpError(); 445 } 446 return $result; 447} 448 449 450/** 451 * pg_field_table returns the name of the table that field 452 * belongs to, or the table's oid if oid_only is TRUE. 453 * 454 * @param resource $result PostgreSQL query result resource, returned by pg_query, 455 * pg_query_params or pg_execute 456 * (among others). 457 * @param int $field_number Field number, starting from 0. 458 * @param bool $oid_only By default the tables name that field belongs to is returned but 459 * if oid_only is set to TRUE, then the 460 * oid will instead be returned. 461 * @return mixed On success either the fields table name or oid. Or, FALSE on failure. 462 * @throws PgsqlException 463 * 464 */ 465function pg_field_table($result, int $field_number, bool $oid_only = false) 466{ 467 error_clear_last(); 468 $result = \pg_field_table($result, $field_number, $oid_only); 469 if ($result === false) { 470 throw PgsqlException::createFromPhpError(); 471 } 472 return $result; 473} 474 475 476/** 477 * pg_field_type returns a string containing the 478 * base type name of the given field_number in the 479 * given PostgreSQL result resource. 480 * 481 * @param resource $result PostgreSQL query result resource, returned by pg_query, 482 * pg_query_params or pg_execute 483 * (among others). 484 * @param int $field_number Field number, starting from 0. 485 * @return string A string containing the base name of the field's type. 486 * @throws PgsqlException 487 * 488 */ 489function pg_field_type($result, int $field_number): string 490{ 491 error_clear_last(); 492 $result = \pg_field_type($result, $field_number); 493 if ($result === false) { 494 throw PgsqlException::createFromPhpError(); 495 } 496 return $result; 497} 498 499 500/** 501 * pg_flush flushes any outbound query data waiting to be 502 * sent on the connection. 503 * 504 * @param resource $connection PostgreSQL database connection resource. 505 * @return mixed Returns TRUE if the flush was successful or no data was waiting to be 506 * flushed, 0 if part of the pending data was flushed but 507 * more remains. 508 * @throws PgsqlException 509 * 510 */ 511function pg_flush($connection) 512{ 513 error_clear_last(); 514 $result = \pg_flush($connection); 515 if ($result === false) { 516 throw PgsqlException::createFromPhpError(); 517 } 518 return $result; 519} 520 521 522/** 523 * pg_free_result frees the memory and data associated with the 524 * specified PostgreSQL query result resource. 525 * 526 * This function need only be called if memory 527 * consumption during script execution is a problem. Otherwise, all result memory will 528 * be automatically freed when the script ends. 529 * 530 * @param resource $result PostgreSQL query result resource, returned by pg_query, 531 * pg_query_params or pg_execute 532 * (among others). 533 * @throws PgsqlException 534 * 535 */ 536function pg_free_result($result): void 537{ 538 error_clear_last(); 539 $result = \pg_free_result($result); 540 if ($result === false) { 541 throw PgsqlException::createFromPhpError(); 542 } 543} 544 545 546/** 547 * pg_host returns the host name of the given 548 * PostgreSQL connection resource is 549 * connected to. 550 * 551 * @param resource $connection PostgreSQL database connection resource. When 552 * connection is not present, the default connection 553 * is used. The default connection is the last connection made by 554 * pg_connect or pg_pconnect. 555 * @return string A string containing the name of the host the 556 * connection is to. 557 * @throws PgsqlException 558 * 559 */ 560function pg_host($connection = null): string 561{ 562 error_clear_last(); 563 if ($connection !== null) { 564 $result = \pg_host($connection); 565 } else { 566 $result = \pg_host(); 567 } 568 if ($result === false) { 569 throw PgsqlException::createFromPhpError(); 570 } 571 return $result; 572} 573 574 575/** 576 * pg_insert inserts the values 577 * of assoc_array into the table specified 578 * by table_name. If options 579 * is specified, pg_convert is applied 580 * to assoc_array with the specified options. 581 * 582 * If options is specified, 583 * pg_convert is applied to 584 * assoc_array with the specified flags. 585 * 586 * By default pg_insert passes raw values. Values 587 * must be escaped or PGSQL_DML_ESCAPE option must be 588 * specified. PGSQL_DML_ESCAPE quotes and escapes 589 * parameters/identifiers. Therefore, table/column names became case 590 * sensitive. 591 * 592 * Note that neither escape nor prepared query can protect LIKE query, 593 * JSON, Array, Regex, etc. These parameters should be handled 594 * according to their contexts. i.e. Escape/validate values. 595 * 596 * @param resource $connection PostgreSQL database connection resource. 597 * @param string $table_name Name of the table into which to insert rows. The table table_name must at least 598 * have as many columns as assoc_array has elements. 599 * @param array $assoc_array An array whose keys are field names in the table table_name, 600 * and whose values are the values of those fields that are to be inserted. 601 * @param int $options Any number of PGSQL_CONV_OPTS, 602 * PGSQL_DML_NO_CONV, 603 * PGSQL_DML_ESCAPE, 604 * PGSQL_DML_EXEC, 605 * PGSQL_DML_ASYNC or 606 * PGSQL_DML_STRING combined. If PGSQL_DML_STRING is part of the 607 * options then query string is returned. When PGSQL_DML_NO_CONV 608 * or PGSQL_DML_ESCAPE is set, it does not call pg_convert internally. 609 * @return mixed Returns the connection resource on success. Returns string if PGSQL_DML_STRING is passed 610 * via options. 611 * @throws PgsqlException 612 * 613 */ 614function pg_insert($connection, string $table_name, array $assoc_array, int $options = PGSQL_DML_EXEC) 615{ 616 error_clear_last(); 617 $result = \pg_insert($connection, $table_name, $assoc_array, $options); 618 if ($result === false) { 619 throw PgsqlException::createFromPhpError(); 620 } 621 return $result; 622} 623 624 625/** 626 * pg_last_error returns the last error message 627 * for a given connection. 628 * 629 * Error messages may be overwritten by internal PostgreSQL (libpq) 630 * function calls. It may not return an appropriate error message if 631 * multiple errors occur inside a PostgreSQL module function. 632 * 633 * Use pg_result_error, pg_result_error_field, 634 * pg_result_status and 635 * pg_connection_status for better error handling. 636 * 637 * @param resource $connection PostgreSQL database connection resource. When 638 * connection is not present, the default connection 639 * is used. The default connection is the last connection made by 640 * pg_connect or pg_pconnect. 641 * @return string A string containing the last error message on the 642 * given connection. 643 * @throws PgsqlException 644 * 645 */ 646function pg_last_error($connection = null): string 647{ 648 error_clear_last(); 649 if ($connection !== null) { 650 $result = \pg_last_error($connection); 651 } else { 652 $result = \pg_last_error(); 653 } 654 if ($result === false) { 655 throw PgsqlException::createFromPhpError(); 656 } 657 return $result; 658} 659 660 661/** 662 * pg_last_notice returns the last notice 663 * message from the PostgreSQL server on the specified 664 * connection. The PostgreSQL server sends notice 665 * messages in several cases, for instance when creating a SERIAL 666 * column in a table. 667 * 668 * With pg_last_notice, you can avoid issuing useless 669 * queries by checking whether or not the notice is related to your transaction. 670 * 671 * Notice message tracking can be set to optional by setting 1 for 672 * pgsql.ignore_notice in php.ini. 673 * 674 * Notice message logging can be set to optional by setting 0 for 675 * pgsql.log_notice in php.ini. 676 * Unless pgsql.ignore_notice is set 677 * to 0, notice message cannot be logged. 678 * 679 * @param resource $connection PostgreSQL database connection resource. 680 * @param int $option One of PGSQL_NOTICE_LAST (to return last notice), 681 * PGSQL_NOTICE_ALL (to return all notices), 682 * or PGSQL_NOTICE_CLEAR (to clear notices). 683 * @return string A string containing the last notice on the 684 * given connection with 685 * PGSQL_NOTICE_LAST, 686 * an array with PGSQL_NOTICE_ALL, 687 * a boolean with PGSQL_NOTICE_CLEAR. 688 * @throws PgsqlException 689 * 690 */ 691function pg_last_notice($connection, int $option = PGSQL_NOTICE_LAST): string 692{ 693 error_clear_last(); 694 $result = \pg_last_notice($connection, $option); 695 if ($result === false) { 696 throw PgsqlException::createFromPhpError(); 697 } 698 return $result; 699} 700 701 702/** 703 * pg_last_oid is used to retrieve the 704 * OID assigned to an inserted row. 705 * 706 * OID field became an optional field from PostgreSQL 7.2 and will 707 * not be present by default in PostgreSQL 8.1. When the 708 * OID field is not present in a table, the programmer must use 709 * pg_result_status to check for successful 710 * insertion. 711 * 712 * To get the value of a SERIAL field in an inserted 713 * row, it is necessary to use the PostgreSQL CURRVAL 714 * function, naming the sequence whose last value is required. If the 715 * name of the sequence is unknown, the pg_get_serial_sequence 716 * PostgreSQL 8.0 function is necessary. 717 * 718 * PostgreSQL 8.1 has a function LASTVAL that returns 719 * the value of the most recently used sequence in the session. This avoids 720 * the need for naming the sequence, table or column altogether. 721 * 722 * @param resource $result PostgreSQL query result resource, returned by pg_query, 723 * pg_query_params or pg_execute 724 * (among others). 725 * @return string A string containing the OID assigned to the most recently inserted 726 * row in the specified connection or 727 * no available OID. 728 * @throws PgsqlException 729 * 730 */ 731function pg_last_oid($result): string 732{ 733 error_clear_last(); 734 $result = \pg_last_oid($result); 735 if ($result === false) { 736 throw PgsqlException::createFromPhpError(); 737 } 738 return $result; 739} 740 741 742/** 743 * pg_lo_close closes a large 744 * object. large_object is a resource for the 745 * large object from pg_lo_open. 746 * 747 * To use the large object interface, it is necessary to 748 * enclose it within a transaction block. 749 * 750 * @param resource $large_object PostgreSQL large object (LOB) resource, returned by pg_lo_open. 751 * @throws PgsqlException 752 * 753 */ 754function pg_lo_close($large_object): void 755{ 756 error_clear_last(); 757 $result = \pg_lo_close($large_object); 758 if ($result === false) { 759 throw PgsqlException::createFromPhpError(); 760 } 761} 762 763 764/** 765 * pg_lo_export takes a large object in a 766 * PostgreSQL database and saves its contents to a file on the local 767 * filesystem. 768 * 769 * To use the large object interface, it is necessary to 770 * enclose it within a transaction block. 771 * 772 * @param resource $connection PostgreSQL database connection resource. When 773 * connection is not present, the default connection 774 * is used. The default connection is the last connection made by 775 * pg_connect or pg_pconnect. 776 * @param int $oid The OID of the large object in the database. 777 * @param string $pathname The full path and file name of the file in which to write the 778 * large object on the client filesystem. 779 * @throws PgsqlException 780 * 781 */ 782function pg_lo_export($connection = null, int $oid = null, string $pathname = null): void 783{ 784 error_clear_last(); 785 if ($pathname !== null) { 786 $result = \pg_lo_export($connection, $oid, $pathname); 787 } elseif ($oid !== null) { 788 $result = \pg_lo_export($connection, $oid); 789 } elseif ($connection !== null) { 790 $result = \pg_lo_export($connection); 791 } else { 792 $result = \pg_lo_export(); 793 } 794 if ($result === false) { 795 throw PgsqlException::createFromPhpError(); 796 } 797} 798 799 800/** 801 * pg_lo_import creates a new large object 802 * in the database using a file on the filesystem as its data 803 * source. 804 * 805 * To use the large object interface, it is necessary to 806 * enclose it within a transaction block. 807 * 808 * @param resource $connection PostgreSQL database connection resource. When 809 * connection is not present, the default connection 810 * is used. The default connection is the last connection made by 811 * pg_connect or pg_pconnect. 812 * @param string $pathname The full path and file name of the file on the client 813 * filesystem from which to read the large object data. 814 * @param mixed $object_id If an object_id is given the function 815 * will try to create a large object with this id, else a free 816 * object id is assigned by the server. The parameter 817 * was added in PHP 5.3 and relies on functionality that first 818 * appeared in PostgreSQL 8.1. 819 * @return int The OID of the newly created large object. 820 * @throws PgsqlException 821 * 822 */ 823function pg_lo_import($connection = null, string $pathname = null, $object_id = null): int 824{ 825 error_clear_last(); 826 if ($object_id !== null) { 827 $result = \pg_lo_import($connection, $pathname, $object_id); 828 } elseif ($pathname !== null) { 829 $result = \pg_lo_import($connection, $pathname); 830 } elseif ($connection !== null) { 831 $result = \pg_lo_import($connection); 832 } else { 833 $result = \pg_lo_import(); 834 } 835 if ($result === false) { 836 throw PgsqlException::createFromPhpError(); 837 } 838 return $result; 839} 840 841 842/** 843 * pg_lo_open opens a large object in the database 844 * and returns large object resource so that it can be manipulated. 845 * 846 * To use the large object interface, it is necessary to 847 * enclose it within a transaction block. 848 * 849 * @param resource $connection PostgreSQL database connection resource. When 850 * connection is not present, the default connection 851 * is used. The default connection is the last connection made by 852 * pg_connect or pg_pconnect. 853 * @param int $oid The OID of the large object in the database. 854 * @param string $mode Can be either "r" for read-only, "w" for write only or "rw" for read and 855 * write. 856 * @return resource A large object resource. 857 * @throws PgsqlException 858 * 859 */ 860function pg_lo_open($connection, int $oid, string $mode) 861{ 862 error_clear_last(); 863 $result = \pg_lo_open($connection, $oid, $mode); 864 if ($result === false) { 865 throw PgsqlException::createFromPhpError(); 866 } 867 return $result; 868} 869 870 871/** 872 * pg_lo_read_all reads a large object and passes 873 * it straight through to the browser after sending all pending 874 * headers. Mainly intended for sending binary data like images or 875 * sound. 876 * 877 * To use the large object interface, it is necessary to 878 * enclose it within a transaction block. 879 * 880 * @param resource $large_object PostgreSQL large object (LOB) resource, returned by pg_lo_open. 881 * @return int Number of bytes read. 882 * @throws PgsqlException 883 * 884 */ 885function pg_lo_read_all($large_object): int 886{ 887 error_clear_last(); 888 $result = \pg_lo_read_all($large_object); 889 if ($result === false) { 890 throw PgsqlException::createFromPhpError(); 891 } 892 return $result; 893} 894 895 896/** 897 * pg_lo_read reads at most 898 * len bytes from a large object and 899 * returns it as a string. 900 * 901 * To use the large object interface, it is necessary to 902 * enclose it within a transaction block. 903 * 904 * @param resource $large_object PostgreSQL large object (LOB) resource, returned by pg_lo_open. 905 * @param int $len An optional maximum number of bytes to return. 906 * @return string A string containing len bytes from the 907 * large object. 908 * @throws PgsqlException 909 * 910 */ 911function pg_lo_read($large_object, int $len = 8192): string 912{ 913 error_clear_last(); 914 $result = \pg_lo_read($large_object, $len); 915 if ($result === false) { 916 throw PgsqlException::createFromPhpError(); 917 } 918 return $result; 919} 920 921 922/** 923 * pg_lo_seek seeks a position within a large object 924 * resource. 925 * 926 * To use the large object interface, it is necessary to 927 * enclose it within a transaction block. 928 * 929 * @param resource $large_object PostgreSQL large object (LOB) resource, returned by pg_lo_open. 930 * @param int $offset The number of bytes to seek. 931 * @param int $whence One of the constants PGSQL_SEEK_SET (seek from object start), 932 * PGSQL_SEEK_CUR (seek from current position) 933 * or PGSQL_SEEK_END (seek from object end) . 934 * @throws PgsqlException 935 * 936 */ 937function pg_lo_seek($large_object, int $offset, int $whence = PGSQL_SEEK_CUR): void 938{ 939 error_clear_last(); 940 $result = \pg_lo_seek($large_object, $offset, $whence); 941 if ($result === false) { 942 throw PgsqlException::createFromPhpError(); 943 } 944} 945 946 947/** 948 * pg_lo_truncate truncates a large object 949 * resource. 950 * 951 * To use the large object interface, it is necessary to 952 * enclose it within a transaction block. 953 * 954 * @param resource $large_object PostgreSQL large object (LOB) resource, returned by pg_lo_open. 955 * @param int $size The number of bytes to truncate. 956 * @throws PgsqlException 957 * 958 */ 959function pg_lo_truncate($large_object, int $size): void 960{ 961 error_clear_last(); 962 $result = \pg_lo_truncate($large_object, $size); 963 if ($result === false) { 964 throw PgsqlException::createFromPhpError(); 965 } 966} 967 968 969/** 970 * pg_lo_unlink deletes a large object with the 971 * oid. Returns TRUE on success. 972 * 973 * To use the large object interface, it is necessary to 974 * enclose it within a transaction block. 975 * 976 * @param resource $connection PostgreSQL database connection resource. When 977 * connection is not present, the default connection 978 * is used. The default connection is the last connection made by 979 * pg_connect or pg_pconnect. 980 * @param int $oid The OID of the large object in the database. 981 * @throws PgsqlException 982 * 983 */ 984function pg_lo_unlink($connection, int $oid): void 985{ 986 error_clear_last(); 987 $result = \pg_lo_unlink($connection, $oid); 988 if ($result === false) { 989 throw PgsqlException::createFromPhpError(); 990 } 991} 992 993 994/** 995 * pg_lo_write writes data into a large object 996 * at the current seek position. 997 * 998 * To use the large object interface, it is necessary to 999 * enclose it within a transaction block. 1000 * 1001 * @param resource $large_object PostgreSQL large object (LOB) resource, returned by pg_lo_open. 1002 * @param string $data The data to be written to the large object. If len is 1003 * specified and is less than the length of data, only 1004 * len bytes will be written. 1005 * @param int $len An optional maximum number of bytes to write. Must be greater than zero 1006 * and no greater than the length of data. Defaults to 1007 * the length of data. 1008 * @return int The number of bytes written to the large object. 1009 * @throws PgsqlException 1010 * 1011 */ 1012function pg_lo_write($large_object, string $data, int $len = null): int 1013{ 1014 error_clear_last(); 1015 if ($len !== null) { 1016 $result = \pg_lo_write($large_object, $data, $len); 1017 } else { 1018 $result = \pg_lo_write($large_object, $data); 1019 } 1020 if ($result === false) { 1021 throw PgsqlException::createFromPhpError(); 1022 } 1023 return $result; 1024} 1025 1026 1027/** 1028 * pg_meta_data returns table definition for 1029 * table_name as an array. 1030 * 1031 * @param resource $connection PostgreSQL database connection resource. 1032 * @param string $table_name The name of the table. 1033 * @param bool $extended Flag for returning extended meta data. Default to FALSE. 1034 * @return array An array of the table definition. 1035 * @throws PgsqlException 1036 * 1037 */ 1038function pg_meta_data($connection, string $table_name, bool $extended = false): array 1039{ 1040 error_clear_last(); 1041 $result = \pg_meta_data($connection, $table_name, $extended); 1042 if ($result === false) { 1043 throw PgsqlException::createFromPhpError(); 1044 } 1045 return $result; 1046} 1047 1048 1049/** 1050 * pg_options will return a string containing 1051 * the options specified on the given PostgreSQL 1052 * connection resource. 1053 * 1054 * @param resource $connection PostgreSQL database connection resource. When 1055 * connection is not present, the default connection 1056 * is used. The default connection is the last connection made by 1057 * pg_connect or pg_pconnect. 1058 * @return string A string containing the connection 1059 * options. 1060 * @throws PgsqlException 1061 * 1062 */ 1063function pg_options($connection = null): string 1064{ 1065 error_clear_last(); 1066 if ($connection !== null) { 1067 $result = \pg_options($connection); 1068 } else { 1069 $result = \pg_options(); 1070 } 1071 if ($result === false) { 1072 throw PgsqlException::createFromPhpError(); 1073 } 1074 return $result; 1075} 1076 1077 1078/** 1079 * Looks up a current parameter setting of the server. 1080 * 1081 * Certain parameter values are reported by the server automatically at 1082 * connection startup or whenever their values change. pg_parameter_status can be 1083 * used to interrogate these settings. It returns the current value of a 1084 * parameter if known, or FALSE if the parameter is not known. 1085 * 1086 * Parameters reported as of PostgreSQL 8.0 include server_version, 1087 * server_encoding, client_encoding, 1088 * is_superuser, session_authorization, 1089 * DateStyle, TimeZone, and integer_datetimes. 1090 * (server_encoding, TimeZone, and 1091 * integer_datetimes were not reported by releases before 8.0.) Note that 1092 * server_version, server_encoding and integer_datetimes 1093 * cannot change after PostgreSQL startup. 1094 * 1095 * PostgreSQL 7.3 or lower servers do not report parameter settings, 1096 * pg_parameter_status 1097 * includes logic to obtain values for server_version and 1098 * client_encoding 1099 * anyway. Applications are encouraged to use pg_parameter_status rather than ad 1100 * hoc code to determine these values. 1101 * 1102 * @param resource $connection PostgreSQL database connection resource. When 1103 * connection is not present, the default connection 1104 * is used. The default connection is the last connection made by 1105 * pg_connect or pg_pconnect. 1106 * @param string $param_name Possible param_name values include server_version, 1107 * server_encoding, client_encoding, 1108 * is_superuser, session_authorization, 1109 * DateStyle, TimeZone, and 1110 * integer_datetimes. Note that this value is case-sensitive. 1111 * @return string A string containing the value of the parameter, FALSE on failure or invalid 1112 * param_name. 1113 * @throws PgsqlException 1114 * 1115 */ 1116function pg_parameter_status($connection = null, string $param_name = null): string 1117{ 1118 error_clear_last(); 1119 if ($param_name !== null) { 1120 $result = \pg_parameter_status($connection, $param_name); 1121 } elseif ($connection !== null) { 1122 $result = \pg_parameter_status($connection); 1123 } else { 1124 $result = \pg_parameter_status(); 1125 } 1126 if ($result === false) { 1127 throw PgsqlException::createFromPhpError(); 1128 } 1129 return $result; 1130} 1131 1132 1133/** 1134 * pg_pconnect opens a connection to a 1135 * PostgreSQL database. It returns a connection resource that is 1136 * needed by other PostgreSQL functions. 1137 * 1138 * If a second call is made to pg_pconnect with 1139 * the same connection_string as an existing connection, the 1140 * existing connection will be returned unless you pass 1141 * PGSQL_CONNECT_FORCE_NEW as 1142 * connect_type. 1143 * 1144 * To enable persistent connection, the pgsql.allow_persistent 1145 * php.ini directive must be set to "On" (which is the default). 1146 * The maximum number of persistent connection can be defined with the pgsql.max_persistent 1147 * php.ini directive (defaults to -1 for no limit). The total number 1148 * of connections can be set with the pgsql.max_links 1149 * php.ini directive. 1150 * 1151 * pg_close will not close persistent links 1152 * generated by pg_pconnect. 1153 * 1154 * @param string $connection_string The connection_string can be empty to use all default parameters, or it 1155 * can contain one or more parameter settings separated by whitespace. 1156 * Each parameter setting is in the form keyword = value. Spaces around 1157 * the equal sign are optional. To write an empty value or a value 1158 * containing spaces, surround it with single quotes, e.g., keyword = 1159 * 'a value'. Single quotes and backslashes within the value must be 1160 * escaped with a backslash, i.e., \' and \\. 1161 * 1162 * The currently recognized parameter keywords are: 1163 * host, hostaddr, port, 1164 * dbname, user, 1165 * password, connect_timeout, 1166 * options, tty (ignored), sslmode, 1167 * requiressl (deprecated in favor of sslmode), and 1168 * service. Which of these arguments exist depends 1169 * on your PostgreSQL version. 1170 * @param int $connect_type If PGSQL_CONNECT_FORCE_NEW is passed, then a new connection 1171 * is created, even if the connection_string is identical to 1172 * an existing connection. 1173 * @return resource PostgreSQL connection resource on success, FALSE on failure. 1174 * @throws PgsqlException 1175 * 1176 */ 1177function pg_pconnect(string $connection_string, int $connect_type = null) 1178{ 1179 error_clear_last(); 1180 if ($connect_type !== null) { 1181 $result = \pg_pconnect($connection_string, $connect_type); 1182 } else { 1183 $result = \pg_pconnect($connection_string); 1184 } 1185 if ($result === false) { 1186 throw PgsqlException::createFromPhpError(); 1187 } 1188 return $result; 1189} 1190 1191 1192/** 1193 * pg_ping pings a database connection and tries to 1194 * reconnect it if it is broken. 1195 * 1196 * @param resource $connection PostgreSQL database connection resource. When 1197 * connection is not present, the default connection 1198 * is used. The default connection is the last connection made by 1199 * pg_connect or pg_pconnect. 1200 * @throws PgsqlException 1201 * 1202 */ 1203function pg_ping($connection = null): void 1204{ 1205 error_clear_last(); 1206 if ($connection !== null) { 1207 $result = \pg_ping($connection); 1208 } else { 1209 $result = \pg_ping(); 1210 } 1211 if ($result === false) { 1212 throw PgsqlException::createFromPhpError(); 1213 } 1214} 1215 1216 1217/** 1218 * pg_port returns the port number that the 1219 * given PostgreSQL connection resource is 1220 * connected to. 1221 * 1222 * @param resource $connection PostgreSQL database connection resource. When 1223 * connection is not present, the default connection 1224 * is used. The default connection is the last connection made by 1225 * pg_connect or pg_pconnect. 1226 * @return int An int containing the port number of the database 1227 * server the connection is to. 1228 * @throws PgsqlException 1229 * 1230 */ 1231function pg_port($connection = null): int 1232{ 1233 error_clear_last(); 1234 if ($connection !== null) { 1235 $result = \pg_port($connection); 1236 } else { 1237 $result = \pg_port(); 1238 } 1239 if ($result === false) { 1240 throw PgsqlException::createFromPhpError(); 1241 } 1242 return $result; 1243} 1244 1245 1246/** 1247 * pg_prepare creates a prepared statement for later execution with 1248 * pg_execute or pg_send_execute. 1249 * This feature allows commands that will be used repeatedly to 1250 * be parsed and planned just once, rather than each time they are executed. 1251 * pg_prepare is supported only against PostgreSQL 7.4 or 1252 * higher connections; it will fail when using earlier versions. 1253 * 1254 * The function creates a prepared statement named stmtname from the query 1255 * string, which must contain a single SQL command. stmtname may be "" to 1256 * create an unnamed statement, in which case any pre-existing unnamed 1257 * statement is automatically replaced; otherwise it is an error if the 1258 * statement name is already defined in the current session. If any parameters 1259 * are used, they are referred to in the query as $1, $2, etc. 1260 * 1261 * Prepared statements for use with pg_prepare can also be created by 1262 * executing SQL PREPARE statements. (But pg_prepare is more flexible since it 1263 * does not require parameter types to be pre-specified.) Also, although there 1264 * is no PHP function for deleting a prepared statement, the SQL DEALLOCATE 1265 * statement can be used for that purpose. 1266 * 1267 * @param resource $connection PostgreSQL database connection resource. When 1268 * connection is not present, the default connection 1269 * is used. The default connection is the last connection made by 1270 * pg_connect or pg_pconnect. 1271 * @param string $stmtname The name to give the prepared statement. Must be unique per-connection. If 1272 * "" is specified, then an unnamed statement is created, overwriting any 1273 * previously defined unnamed statement. 1274 * @param string $query The parameterized SQL statement. Must contain only a single statement. 1275 * (multiple statements separated by semi-colons are not allowed.) If any parameters 1276 * are used, they are referred to as $1, $2, etc. 1277 * @return resource A query result resource on success. 1278 * @throws PgsqlException 1279 * 1280 */ 1281function pg_prepare($connection = null, string $stmtname = null, string $query = null) 1282{ 1283 error_clear_last(); 1284 if ($query !== null) { 1285 $result = \pg_prepare($connection, $stmtname, $query); 1286 } elseif ($stmtname !== null) { 1287 $result = \pg_prepare($connection, $stmtname); 1288 } elseif ($connection !== null) { 1289 $result = \pg_prepare($connection); 1290 } else { 1291 $result = \pg_prepare(); 1292 } 1293 if ($result === false) { 1294 throw PgsqlException::createFromPhpError(); 1295 } 1296 return $result; 1297} 1298 1299 1300/** 1301 * pg_put_line sends a NULL-terminated string 1302 * to the PostgreSQL backend server. This is needed in conjunction 1303 * with PostgreSQL's COPY FROM command. 1304 * 1305 * COPY is a high-speed data loading interface 1306 * supported by PostgreSQL. Data is passed in without being parsed, 1307 * and in a single transaction. 1308 * 1309 * An alternative to using raw pg_put_line commands 1310 * is to use pg_copy_from. This is a far simpler 1311 * interface. 1312 * 1313 * @param resource $connection PostgreSQL database connection resource. When 1314 * connection is not present, the default connection 1315 * is used. The default connection is the last connection made by 1316 * pg_connect or pg_pconnect. 1317 * @param string $data A line of text to be sent directly to the PostgreSQL backend. A NULL 1318 * terminator is added automatically. 1319 * @throws PgsqlException 1320 * 1321 */ 1322function pg_put_line($connection = null, string $data = null): void 1323{ 1324 error_clear_last(); 1325 if ($data !== null) { 1326 $result = \pg_put_line($connection, $data); 1327 } elseif ($connection !== null) { 1328 $result = \pg_put_line($connection); 1329 } else { 1330 $result = \pg_put_line(); 1331 } 1332 if ($result === false) { 1333 throw PgsqlException::createFromPhpError(); 1334 } 1335} 1336 1337 1338/** 1339 * Submits a command to the server and waits for the result, with the ability 1340 * to pass parameters separately from the SQL command text. 1341 * 1342 * pg_query_params is like pg_query, 1343 * but offers additional functionality: parameter 1344 * values can be specified separately from the command string proper. 1345 * pg_query_params is supported only against PostgreSQL 7.4 or 1346 * higher connections; it will fail when using earlier versions. 1347 * 1348 * If parameters are used, they are referred to in the 1349 * query string as $1, $2, etc. The same parameter may 1350 * appear more than once in the query; the same value 1351 * will be used in that case. params specifies the 1352 * actual values of the parameters. A NULL value in this array means the 1353 * corresponding parameter is SQL NULL. 1354 * 1355 * The primary advantage of pg_query_params over pg_query 1356 * is that parameter values 1357 * may be separated from the query string, thus avoiding the need for tedious 1358 * and error-prone quoting and escaping. Unlike pg_query, 1359 * pg_query_params allows at 1360 * most one SQL command in the given string. (There can be semicolons in it, 1361 * but not more than one nonempty command.) 1362 * 1363 * @param resource $connection PostgreSQL database connection resource. When 1364 * connection is not present, the default connection 1365 * is used. The default connection is the last connection made by 1366 * pg_connect or pg_pconnect. 1367 * @param string $query The parameterized SQL statement. Must contain only a single statement. 1368 * (multiple statements separated by semi-colons are not allowed.) If any parameters 1369 * are used, they are referred to as $1, $2, etc. 1370 * 1371 * User-supplied values should always be passed as parameters, not 1372 * interpolated into the query string, where they form possible 1373 * SQL injection 1374 * attack vectors and introduce bugs when handling data containing quotes. 1375 * If for some reason you cannot use a parameter, ensure that interpolated 1376 * values are properly escaped. 1377 * @param array $params An array of parameter values to substitute for the $1, $2, etc. placeholders 1378 * in the original prepared query string. The number of elements in the array 1379 * must match the number of placeholders. 1380 * 1381 * Values intended for bytea fields are not supported as 1382 * parameters. Use pg_escape_bytea instead, or use the 1383 * large object functions. 1384 * @return resource A query result resource on success. 1385 * @throws PgsqlException 1386 * 1387 */ 1388function pg_query_params($connection = null, string $query = null, array $params = null) 1389{ 1390 error_clear_last(); 1391 if ($params !== null) { 1392 $result = \pg_query_params($connection, $query, $params); 1393 } elseif ($query !== null) { 1394 $result = \pg_query_params($connection, $query); 1395 } elseif ($connection !== null) { 1396 $result = \pg_query_params($connection); 1397 } else { 1398 $result = \pg_query_params(); 1399 } 1400 if ($result === false) { 1401 throw PgsqlException::createFromPhpError(); 1402 } 1403 return $result; 1404} 1405 1406 1407/** 1408 * pg_query executes the query 1409 * on the specified database connection. 1410 * pg_query_params should be preferred 1411 * in most cases. 1412 * 1413 * If an error occurs, and FALSE is returned, details of the error can 1414 * be retrieved using the pg_last_error 1415 * function if the connection is valid. 1416 * 1417 * 1418 * 1419 * Although connection can be omitted, it 1420 * is not recommended, since it can be the cause of hard to find 1421 * bugs in scripts. 1422 * 1423 * 1424 * 1425 * @param resource $connection PostgreSQL database connection resource. When 1426 * connection is not present, the default connection 1427 * is used. The default connection is the last connection made by 1428 * pg_connect or pg_pconnect. 1429 * @param string $query The SQL statement or statements to be executed. When multiple statements are passed to the function, 1430 * they are automatically executed as one transaction, unless there are explicit BEGIN/COMMIT commands 1431 * included in the query string. However, using multiple transactions in one function call is not recommended. 1432 * 1433 * String interpolation of user-supplied data is extremely dangerous and is 1434 * likely to lead to SQL 1435 * injection vulnerabilities. In most cases 1436 * pg_query_params should be preferred, passing 1437 * user-supplied values as parameters rather than substituting them into 1438 * the query string. 1439 * 1440 * Any user-supplied data substituted directly into a query string should 1441 * be properly escaped. 1442 * @return resource A query result resource on success. 1443 * @throws PgsqlException 1444 * 1445 */ 1446function pg_query($connection = null, string $query = null) 1447{ 1448 error_clear_last(); 1449 if ($query !== null) { 1450 $result = \pg_query($connection, $query); 1451 } elseif ($connection !== null) { 1452 $result = \pg_query($connection); 1453 } else { 1454 $result = \pg_query(); 1455 } 1456 if ($result === false) { 1457 throw PgsqlException::createFromPhpError(); 1458 } 1459 return $result; 1460} 1461 1462 1463/** 1464 * pg_result_error_field returns one of the detailed error message 1465 * fields associated with result resource. It is only available 1466 * against a PostgreSQL 7.4 or above server. The error field is specified by 1467 * the fieldcode. 1468 * 1469 * Because pg_query and pg_query_params return FALSE if the query fails, 1470 * you must use pg_send_query and 1471 * pg_get_result to get the result handle. 1472 * 1473 * If you need to get additional error information from failed pg_query queries, 1474 * use pg_set_error_verbosity and pg_last_error 1475 * and then parse the result. 1476 * 1477 * @param resource $result A PostgreSQL query result resource from a previously executed 1478 * statement. 1479 * @param int $fieldcode Possible fieldcode values are: PGSQL_DIAG_SEVERITY, 1480 * PGSQL_DIAG_SQLSTATE, PGSQL_DIAG_MESSAGE_PRIMARY, 1481 * PGSQL_DIAG_MESSAGE_DETAIL, 1482 * PGSQL_DIAG_MESSAGE_HINT, PGSQL_DIAG_STATEMENT_POSITION, 1483 * PGSQL_DIAG_INTERNAL_POSITION (PostgreSQL 8.0+ only), 1484 * PGSQL_DIAG_INTERNAL_QUERY (PostgreSQL 8.0+ only), 1485 * PGSQL_DIAG_CONTEXT, PGSQL_DIAG_SOURCE_FILE, 1486 * PGSQL_DIAG_SOURCE_LINE or 1487 * PGSQL_DIAG_SOURCE_FUNCTION. 1488 * @return string|null A string containing the contents of the error field, NULL if the field does not exist. 1489 * @throws PgsqlException 1490 * 1491 */ 1492function pg_result_error_field($result, int $fieldcode): ?string 1493{ 1494 error_clear_last(); 1495 $result = \pg_result_error_field($result, $fieldcode); 1496 if ($result === false) { 1497 throw PgsqlException::createFromPhpError(); 1498 } 1499 return $result; 1500} 1501 1502 1503/** 1504 * pg_result_seek sets the internal row offset in 1505 * a result resource. 1506 * 1507 * @param resource $result PostgreSQL query result resource, returned by pg_query, 1508 * pg_query_params or pg_execute 1509 * (among others). 1510 * @param int $offset Row to move the internal offset to in the result resource. 1511 * Rows are numbered starting from zero. 1512 * @throws PgsqlException 1513 * 1514 */ 1515function pg_result_seek($result, int $offset): void 1516{ 1517 error_clear_last(); 1518 $result = \pg_result_seek($result, $offset); 1519 if ($result === false) { 1520 throw PgsqlException::createFromPhpError(); 1521 } 1522} 1523 1524 1525/** 1526 * pg_select selects records specified by 1527 * assoc_array which has 1528 * field=>value. For a successful query, it returns an 1529 * array containing all records and fields that match the condition 1530 * specified by assoc_array. 1531 * 1532 * If options is specified, 1533 * pg_convert is applied to 1534 * assoc_array with the specified flags. 1535 * 1536 * By default pg_select passes raw values. Values 1537 * must be escaped or PGSQL_DML_ESCAPE option must be 1538 * specified. PGSQL_DML_ESCAPE quotes and escapes 1539 * parameters/identifiers. Therefore, table/column names became case 1540 * sensitive. 1541 * 1542 * Note that neither escape nor prepared query can protect LIKE query, 1543 * JSON, Array, Regex, etc. These parameters should be handled 1544 * according to their contexts. i.e. Escape/validate values. 1545 * 1546 * @param resource $connection PostgreSQL database connection resource. 1547 * @param string $table_name Name of the table from which to select rows. 1548 * @param array $assoc_array An array whose keys are field names in the table table_name, 1549 * and whose values are the conditions that a row must meet to be retrieved. 1550 * @param int $options Any number of PGSQL_CONV_FORCE_NULL, 1551 * PGSQL_DML_NO_CONV, 1552 * PGSQL_DML_ESCAPE, 1553 * PGSQL_DML_EXEC, 1554 * PGSQL_DML_ASYNC or 1555 * PGSQL_DML_STRING combined. If PGSQL_DML_STRING is part of the 1556 * options then query string is returned. When PGSQL_DML_NO_CONV 1557 * or PGSQL_DML_ESCAPE is set, it does not call pg_convert internally. 1558 * @param int $result_type 1559 * @return mixed Returns TRUE on success. Returns string if PGSQL_DML_STRING is passed 1560 * via options. 1561 * @throws PgsqlException 1562 * 1563 */ 1564function pg_select($connection, string $table_name, array $assoc_array, int $options = PGSQL_DML_EXEC, int $result_type = PGSQL_ASSOC) 1565{ 1566 error_clear_last(); 1567 $result = \pg_select($connection, $table_name, $assoc_array, $options, $result_type); 1568 if ($result === false) { 1569 throw PgsqlException::createFromPhpError(); 1570 } 1571 return $result; 1572} 1573 1574 1575/** 1576 * Sends a request to execute a prepared statement with given parameters, 1577 * without waiting for the result(s). 1578 * 1579 * This is similar to pg_send_query_params, but the command to be executed is specified 1580 * by naming a previously-prepared statement, instead of giving a query string. The 1581 * function's parameters are handled identically to pg_execute. 1582 * Like pg_execute, it will not work on pre-7.4 versions of 1583 * PostgreSQL. 1584 * 1585 * @param resource $connection PostgreSQL database connection resource. When 1586 * connection is not present, the default connection 1587 * is used. The default connection is the last connection made by 1588 * pg_connect or pg_pconnect. 1589 * @param string $stmtname The name of the prepared statement to execute. if 1590 * "" is specified, then the unnamed statement is executed. The name must have 1591 * been previously prepared using pg_prepare, 1592 * pg_send_prepare or a PREPARE SQL 1593 * command. 1594 * @param array $params An array of parameter values to substitute for the $1, $2, etc. placeholders 1595 * in the original prepared query string. The number of elements in the array 1596 * must match the number of placeholders. 1597 * @throws PgsqlException 1598 * 1599 */ 1600function pg_send_execute($connection, string $stmtname, array $params): void 1601{ 1602 error_clear_last(); 1603 $result = \pg_send_execute($connection, $stmtname, $params); 1604 if ($result === false) { 1605 throw PgsqlException::createFromPhpError(); 1606 } 1607} 1608 1609 1610/** 1611 * Sends a request to create a prepared statement with the given parameters, 1612 * without waiting for completion. 1613 * 1614 * This is an asynchronous version of pg_prepare: it returns TRUE if it was able to 1615 * dispatch the request, and FALSE if not. After a successful call, call 1616 * pg_get_result to determine whether the server successfully created the 1617 * prepared statement. The function's parameters are handled identically to 1618 * pg_prepare. Like pg_prepare, it will not work 1619 * on pre-7.4 versions of PostgreSQL. 1620 * 1621 * @param resource $connection PostgreSQL database connection resource. When 1622 * connection is not present, the default connection 1623 * is used. The default connection is the last connection made by 1624 * pg_connect or pg_pconnect. 1625 * @param string $stmtname The name to give the prepared statement. Must be unique per-connection. If 1626 * "" is specified, then an unnamed statement is created, overwriting any 1627 * previously defined unnamed statement. 1628 * @param string $query The parameterized SQL statement. Must contain only a single statement. 1629 * (multiple statements separated by semi-colons are not allowed.) If any parameters 1630 * are used, they are referred to as $1, $2, etc. 1631 * @throws PgsqlException 1632 * 1633 */ 1634function pg_send_prepare($connection, string $stmtname, string $query): void 1635{ 1636 error_clear_last(); 1637 $result = \pg_send_prepare($connection, $stmtname, $query); 1638 if ($result === false) { 1639 throw PgsqlException::createFromPhpError(); 1640 } 1641} 1642 1643 1644/** 1645 * Submits a command and separate parameters to the server without 1646 * waiting for the result(s). 1647 * 1648 * This is equivalent to pg_send_query except that query 1649 * parameters can be specified separately from the 1650 * query string. The function's parameters are 1651 * handled identically to pg_query_params. Like 1652 * pg_query_params, it will not work on pre-7.4 PostgreSQL 1653 * connections, and it allows only one command in the query string. 1654 * 1655 * @param resource $connection PostgreSQL database connection resource. 1656 * @param string $query The parameterized SQL statement. Must contain only a single statement. 1657 * (multiple statements separated by semi-colons are not allowed.) If any parameters 1658 * are used, they are referred to as $1, $2, etc. 1659 * @param array $params An array of parameter values to substitute for the $1, $2, etc. placeholders 1660 * in the original prepared query string. The number of elements in the array 1661 * must match the number of placeholders. 1662 * @throws PgsqlException 1663 * 1664 */ 1665function pg_send_query_params($connection, string $query, array $params): void 1666{ 1667 error_clear_last(); 1668 $result = \pg_send_query_params($connection, $query, $params); 1669 if ($result === false) { 1670 throw PgsqlException::createFromPhpError(); 1671 } 1672} 1673 1674 1675/** 1676 * pg_send_query sends a query or queries asynchronously to the 1677 * connection. Unlike 1678 * pg_query, it can send multiple queries at once to 1679 * PostgreSQL and get the results one by one using 1680 * pg_get_result. 1681 * 1682 * Script execution is not blocked while the queries are executing. Use 1683 * pg_connection_busy to check if the connection is 1684 * busy (i.e. the query is executing). Queries may be cancelled using 1685 * pg_cancel_query. 1686 * 1687 * Although the user can send multiple queries at once, multiple queries 1688 * cannot be sent over a busy connection. If a query is sent while 1689 * the connection is busy, it waits until the last query is finished and 1690 * discards all its results. 1691 * 1692 * @param resource $connection PostgreSQL database connection resource. 1693 * @param string $query The SQL statement or statements to be executed. 1694 * 1695 * Data inside the query should be properly escaped. 1696 * @throws PgsqlException 1697 * 1698 */ 1699function pg_send_query($connection, string $query): void 1700{ 1701 error_clear_last(); 1702 $result = \pg_send_query($connection, $query); 1703 if ($result === false) { 1704 throw PgsqlException::createFromPhpError(); 1705 } 1706} 1707 1708 1709/** 1710 * pg_socket returns a read only resource 1711 * corresponding to the socket underlying the given PostgreSQL connection. 1712 * 1713 * @param resource $connection PostgreSQL database connection resource. 1714 * @return resource A socket resource on success. 1715 * @throws PgsqlException 1716 * 1717 */ 1718function pg_socket($connection) 1719{ 1720 error_clear_last(); 1721 $result = \pg_socket($connection); 1722 if ($result === false) { 1723 throw PgsqlException::createFromPhpError(); 1724 } 1725 return $result; 1726} 1727 1728 1729/** 1730 * pg_trace enables tracing of the PostgreSQL 1731 * frontend/backend communication to a file. To fully understand the results, 1732 * one needs to be familiar with the internals of PostgreSQL 1733 * communication protocol. 1734 * 1735 * For those who are not, it can still be 1736 * useful for tracing errors in queries sent to the server, you 1737 * could do for example grep '^To backend' 1738 * trace.log and see what queries actually were sent to the 1739 * PostgreSQL server. For more information, refer to the 1740 * PostgreSQL Documentation. 1741 * 1742 * @param string $pathname The full path and file name of the file in which to write the 1743 * trace log. Same as in fopen. 1744 * @param string $mode An optional file access mode, same as for fopen. 1745 * @param resource $connection PostgreSQL database connection resource. When 1746 * connection is not present, the default connection 1747 * is used. The default connection is the last connection made by 1748 * pg_connect or pg_pconnect. 1749 * @throws PgsqlException 1750 * 1751 */ 1752function pg_trace(string $pathname, string $mode = "w", $connection = null): void 1753{ 1754 error_clear_last(); 1755 if ($connection !== null) { 1756 $result = \pg_trace($pathname, $mode, $connection); 1757 } else { 1758 $result = \pg_trace($pathname, $mode); 1759 } 1760 if ($result === false) { 1761 throw PgsqlException::createFromPhpError(); 1762 } 1763} 1764 1765 1766/** 1767 * pg_tty returns the TTY name that server 1768 * side debugging output is sent to on the given PostgreSQL 1769 * connection resource. 1770 * 1771 * @param resource $connection PostgreSQL database connection resource. When 1772 * connection is not present, the default connection 1773 * is used. The default connection is the last connection made by 1774 * pg_connect or pg_pconnect. 1775 * @return string A string containing the debug TTY of 1776 * the connection. 1777 * @throws PgsqlException 1778 * 1779 */ 1780function pg_tty($connection = null): string 1781{ 1782 error_clear_last(); 1783 if ($connection !== null) { 1784 $result = \pg_tty($connection); 1785 } else { 1786 $result = \pg_tty(); 1787 } 1788 if ($result === false) { 1789 throw PgsqlException::createFromPhpError(); 1790 } 1791 return $result; 1792} 1793 1794 1795/** 1796 * pg_update updates records that matches 1797 * condition with data. If 1798 * options is specified, 1799 * pg_convert is applied to 1800 * data with specified options. 1801 * 1802 * pg_update updates records specified by 1803 * assoc_array which has 1804 * field=>value. 1805 * 1806 * If options is specified, 1807 * pg_convert is applied to 1808 * assoc_array with the specified flags. 1809 * 1810 * By default pg_update passes raw values. Values 1811 * must be escaped or PGSQL_DML_ESCAPE option must be 1812 * specified. PGSQL_DML_ESCAPE quotes and escapes 1813 * parameters/identifiers. Therefore, table/column names became case 1814 * sensitive. 1815 * 1816 * Note that neither escape nor prepared query can protect LIKE query, 1817 * JSON, Array, Regex, etc. These parameters should be handled 1818 * according to their contexts. i.e. Escape/validate values. 1819 * 1820 * @param resource $connection PostgreSQL database connection resource. 1821 * @param string $table_name Name of the table into which to update rows. 1822 * @param array $data An array whose keys are field names in the table table_name, 1823 * and whose values are what matched rows are to be updated to. 1824 * @param array $condition An array whose keys are field names in the table table_name, 1825 * and whose values are the conditions that a row must meet to be updated. 1826 * @param int $options Any number of PGSQL_CONV_FORCE_NULL, 1827 * PGSQL_DML_NO_CONV, 1828 * PGSQL_DML_ESCAPE, 1829 * PGSQL_DML_EXEC, 1830 * PGSQL_DML_ASYNC or 1831 * PGSQL_DML_STRING combined. If PGSQL_DML_STRING is part of the 1832 * options then query string is returned. When PGSQL_DML_NO_CONV 1833 * or PGSQL_DML_ESCAPE is set, it does not call pg_convert internally. 1834 * @return mixed Returns TRUE on success. Returns string if PGSQL_DML_STRING is passed 1835 * via options. 1836 * @throws PgsqlException 1837 * 1838 */ 1839function pg_update($connection, string $table_name, array $data, array $condition, int $options = PGSQL_DML_EXEC) 1840{ 1841 error_clear_last(); 1842 $result = \pg_update($connection, $table_name, $data, $condition, $options); 1843 if ($result === false) { 1844 throw PgsqlException::createFromPhpError(); 1845 } 1846 return $result; 1847} 1848 1849 1850/** 1851 * pg_version returns an array with the client, protocol 1852 * and server version. Protocol and server versions are only available if PHP 1853 * was compiled with PostgreSQL 7.4 or later. 1854 * 1855 * For more detailed server information, use pg_parameter_status. 1856 * 1857 * @param resource $connection PostgreSQL database connection resource. When 1858 * connection is not present, the default connection 1859 * is used. The default connection is the last connection made by 1860 * pg_connect or pg_pconnect. 1861 * @return array Returns an array with client, protocol 1862 * and server keys and values (if available) or invalid connection. 1863 * @throws PgsqlException 1864 * 1865 */ 1866function pg_version($connection = null): array 1867{ 1868 error_clear_last(); 1869 if ($connection !== null) { 1870 $result = \pg_version($connection); 1871 } else { 1872 $result = \pg_version(); 1873 } 1874 if ($result === false) { 1875 throw PgsqlException::createFromPhpError(); 1876 } 1877 return $result; 1878} 1879