PHP 8.1: PostgreSQL: resources migrated to \PgSql\Connection, \PgSql\Result, and \PgSql\Lob objects

All resource objects returned and accepted by functions from the PostgreSQL extension are migrated to class objects in PHP 8.1.

Note that this change only affects the PostgreSQL extension. PDO extension and the PostgreSQL database driver (pdo_pgsql) is unaffected.

Prior to PHP 8.1, PostgreSQL extension returned and accepted database connections and results as resource objects. As part of PHP's resource to object migration, these resource types are migrated to class objects. All functions that returned a resource now return class objects instead, and all functions that accepted resource objects now accept the new class object, making this migration opaque with only the caveat being how a resource object is validated and closed.

• Resource to Object Migration
  PHP is gradually phasing out all resource types with class objects, and this migration is part of the Resource to Object Migration plan.

• Extension Namespace Changes
  This migration follows the PHP's new proposed convention on using namespaces for bundled extensions.

All of the resource objects used by PostgreSQL are migrated:

• pgsql link resource objects to PgSql\Connection
• pgsql result resource objects to PgSql\Result
• pgsql large object resource objects to PgSql\Lob

PgSql\Connection

\PgSql\Connection class objects replace the former pgsql link resources, that were used as the database connection created using pg_pconnect and pg_connect functions. These functions now return a \PgSql\Connection class object.

PostgreSQL functions that accepted a pgsql link resource are also changed to accept \PgSql\Connection class objects.

PgSql\Connection class synopsis

namespace PgSql;

final class Connection {
}

PgSql\Connection class semantics

• \PgSql\Connection is declared as a final class. It is not allowed to extend it.
• pg_close function still closes the database connection passed to it.
• pg_pconnect and pg_connect functions must be used to instantiate a \PgSql\Connection object. Directly instantiating an instance using new construct is not allowed:

  new \PgSql\Connection();

  PHP Error:  Cannot directly construct PgSql\Connection, use pg_connect() or pg_pconnect() instead in ... on line ...

PgSql\Result

PgSql\Result class objects replace pgsql result resource objects that were used to contain a result from a database query, such as the return values from pg_query function.

All functions that returned pgsql result resources now return PgSql\Result class objects instead. Further, all functions that accepted a pgsql result resource as a parameter now accept PgSql\Result class objects instead.

PgSql\Result class synopsis

namespace PgSql;

final class Result {
}

PgSql\Result class semantics

• \PgSql\Result is declared as a final class. It is not allowed to extend it.
• Query functions (such as pg_query, pg_prepare, and pg_execute must be used to instantiate PgSql\Result objects. Directly instantiating an instance using new construct is not allowed:

  new \PgSql\Result();

  PHP Error:  Cannot directly construct PgSql\Result, use a dedicated function instead in ... on line ...

PgSql\Lob

pgsql large object resource objects are also replaced with objects of class PgSql\Lob.

pg_lo_open function now return PgSql\Lob instances instead of pgsql large object objects. On the other end, functions that expected parameters of pgsql large object resources expect PgSql\Lob objects.

PgSql\Lob class synopsis

namespace PgSql;

final class Lob {
}

PgSql\Lob class semantics

• \PgSql\Lob is declared as a final class. It is not allowed to extend it.
• pg_lo_open function must be used to instantiate PgSql\Lob objects; Directly instantiating an instance using new \PgSql\Connection() syntax is not allowed:

  new \PgSql\Lob();

  PHP Error:  Cannot directly construct PgSql\Lob, use pg_lo_open() instead in ... on line ...

Backwards Compatibility Impact

All functions from the PostgreSQL extension that previously returned a resource object now return a class object, and their counterpart functions also accept the same class objects.

Note that the is_resource function no longer returns true for the new class objects, and it may now be necessary to change the is_resource check with a comparison to false, or account for the new class instances as well.

- if (is_resource($pgsql_conn)) {
+ if ($pgsql_conn !== false) {

Alternately:

- if (is_resource($pgsql_conn)) {
+ if (is_resource($pgsql_conn) || $pgsql_conn instanceof \PgSql\Connection) {

---

Implementation