Setting up a database connection

The entrance point to the “wrapper” functionality of this package is sad_spirit\pg_wrapper\Connection class. It represents the connection to a database, encapsulates the native \PgSql\Connection object, and contains methods to execute queries and manage transactions.

Instances of other wrapper-related classes like PreparedStatement and Result are normally created via methods of Connection.

Establishing connection

Constructor of Connection accepts a connection string suitable for pg_connect() / underlying PQconnectdb:

use sad_spirit\pg_wrapper\Connection;

// whitespace-separated keyword=value pairs
$connection = new Connection('host=localhost port=5432 dbname=postgres');
// URI format
$another    = new Connection('postgresql://localhost:5432/postgres');

Connecting is lazy by default: creating the Connection object will not immediately establish a connection to the database, it will only be established once it is needed (e.g. $connection->execute() is called).

Note

Connection is established automatically only once. If an explicit disconnect() is performed, it will require an explicit connect() to re-establish the connection.

You can request an eager connection if you pass false as a second argument to the constructor:

use sad_spirit\pg_wrapper\Connection;

$connection = new Connection('host=localhost port=5432 dbname=postgres', false);
var_dump($connection->isConnected());

will output

bool(true)

The connection will be automatically closed once Connection object is destroyed.

Connection-related methods

The following additional methods of Connection help with the connection handling

connect(): $this

Explicitly connects to the database. Throws ConnectionException if connection fails or if the connected server reports an unsupported version.

disconnect(): $this

Disconnects from the database.

isConnected(): bool

Checks whether the connection was established and is still usable (uses pg_connection_status() for the latter check).

getNative(): \PgSql\Connection

returns the native object that represents the connection starting with PHP 8.1 (a resource was used before that version), this will call connect() in lazy connection scenario.

getConnectionId(): string

Returns a unique identifier for the connection. The identifier is based on connection string and is used by converters\CachedTypeOIDMapper as cache key prefix for types metadata. May be used for manual cache invalidation as well.

getLastError(): ?string

Returns the last error message for this connection, null if none present.

Configuration methods

You can additionally configure Connection by passing custom TypeConverterFactory and Psr\Cache\CacheItemPoolInterface implementations to appropriate methods.

setTypeConverterFactory(TypeConverterFactory $factory): $this

Sets the factory object for converters to and from PostgreSQL representation.

getTypeConverterFactory(): TypeConverterFactory

Returns the factory object for converters to and from PostgreSQL representation. If one was not set explicitly by the previous method, sets and returns an instance of a default factory.

A helper method is also available

getTypeConverter(mixed $type): TypeConverter

Returns type converter for the given. This is a shorthand for $this->getTypeConverterFactory()->getConverterForTypeSpecification($type) and accepts the same parameter.

Tip

Using an instance of StubTypeConverterFactory will effectively disable type conversion.

setMetadataCache(Psr\Cache\CacheItemPoolInterface $cache): $this

Sets the DB metadata cache. The above interface is defined in PSR-6, use any compatible implementation.

getMetadataCache(): Psr\Cache\CacheItemPoolInterface

Returns the DB metadata cache

Within pg_wrapper package this cache is used by converters\CachedTypeOIDMapper to store type information loaded from database. It may be also used by other packages depending on pg_wrapper to store additional metadata, e.g. sad_spirit/pg_gateway uses that to store metadata of accesses tables.

Note

It is highly recommended to use the cache in production to prevent database metadata lookups on each page request.