The package now requires PHP 8.2+. BC breaks are possible due to new language features being used, please consult the upgrade instructions.
- Tested on PHP 8.4 and Postgres 17
- Types data and error codes updated for Postgres 17.
- Classes representing complex PostgreSQL types contain native
public readonly
properties rather than magic ones. - When parsing database values, consistently follow Postgres 17 in what is considered a whitespace character:
space,
\r
,\n
,\t
,\v
,\f
. - SQL error codes are represented by cases of
SqlState
enum instead ofServerException
class constants. - Added typehints for arguments and return values where not previously possible: e.g.
int|string
for methods dealing with OID values andint|string
for methods ofResult
accepting field name / index.
Features deprecated in 2.x releases were removed, see the upgrade instructions for the full list.
- An exception message for invalid array bounds in
ArrayConverter
got these bounds mixed. - Proper casing of native
PgSql
namespace.
2.5.0 - 2024-09-12
converters\datetime\IntervalConverter::output()
could incorrectly format the passedfloat
-typed value.$block
property oftypes\Tid
class no longer has anint
typehint: as was the case with OIDs, block number is an unsigned 32-bit integer and may be out of range of PHP's signedint
type on 32-bit builds.
- Getters / issers methods of classes representing complex PostgreSQL types. Use corresponding magic properties,
these will be reimplemented as native
public readonly
properties in the next major version. Specifically,types\Circle
:getCenter()
->$center
,getRadius()
->$radius
;types\Line
:getA()
->$A
,getB()
->$B
,getC()
->$C
;types\Path
:isOpen()
->$open
;types\Point
:getX()
->$x
,getY()
->$y
;types\Box
andtypes\LineSegment
:getStart()
->$start
,getEnd()
->$end
,types\Range
:getLower()
->$lower
,getUpper()
->$upper
,isLowerInclusive()
->$lowerInclusive
,isUpperInclusive()
->$upperInclusive
,isEmpty()
->$empty
;types\Tid
:getBlock()
->$block
,getTuple()
->$tuple
.
types\ReadOnlyProperties
trait used to implement the above magic readonly properties, as migration to native ones is planned.converters\BaseConverter::getStrspn()
method that is no longer used in the package.
2.4.1 - 2024-06-19
IntegerVectorConverter
forint2vector
andoidvector
types used in system catalogs
- String representations of arrays which include dimensions (e.g.
[0:0]={1}
) are now supported (see issue #12). An exception will be thrown if the structure of the resultant array does not match specified dimensions. If a lower bound is specified for a dimension, the keys in PHP array will start with that:'[5:5]={1}'
will be converted to[5 => 1]
. - Arrays of elements that have a delimiter other than comma are supported. In particular,
converting from / to
box[]
type, which uses semicolon, is possible. Converters for custom types having a non-comma delimiter may implement the newCustomArrayDelimiter
interface.
2.4.0 - 2024-05-20
A major update for PreparedStatement
's API, multiple renames.
$resultTypes
argument forConnection::prepare()
andPreparedStatement::__construct()
that will be passed on toResult
instances returned by the createdPreparedStatement
instance.- In
PreparedStatement
class:setResultTypes(array $resultTypes)
method used to configure$resultTypes
for returnedResult
instances.setParameterType(int $parameterNumber, mixed $type)
method that allows to specify the type for a parameter separately from the value.setNumberOfParameters(int $numberOfParameters)
method that sets the number of parameters used in the query. If specified, this will be used to validate the$parameterNumber
arguments given to various methods and keys in parameter values array.executeParams(array $params)
method that will execute the prepared statement using only the values from the given$params
array. An exception will be thrown if any parameter values were previously bound.fetchParameterTypes(bool $overrideExistingTypes = false)
method that will fetch types for statement parameters from the DB. It will also set the correct number of parameters.- Static
setAutoFetchParameterTypes(bool $autoFetch)
/getAutoFetchParameterTypes(): bool
static methods that trigger automatically fetching the above data inPreparedStatement
's constructor. This behaviour is currently disabled by default. - Destructor that deallocates the prepared statement.
Result::getTableOID($fieldIndex)
method that exposes the result ofpg_field_table()
- Tested on PHP 8.3
ResultSet
class, useResult
instead.Connection::checkRollbackNotNeeded()
method, useConnection::assertRollbackNotNeeded()
instead.- Method names mentioning
resource
, as pgsql extension in PHP 8.1+ no longer uses resources:Connection::getResource()
--Connection::getNative()
should be used instead,Result::getResource()
--Result::getNative()
,Result::createFromResultResource()
--Result::createFromReturnValue()
.
- In
PreparedStatement
class:- Passing
$params
toexecute()
method, use the newPreparedStatement::executeParams()
- Passing
$resultTypes
toexecute()
method. Use the constructor orsetResultTypes()
method to set these. - Not specifying types for parameters is deprecated for
bindValue()
/bindParam()
and will result in an exception for the newexecuteParams()
.
- Passing
PreparedStatement::execute()
mapped bound values to query parameters in the order ofbindValue()
/bindParam()
calls, essentially ignoring the parameter numbers.
2.3.0 - 2023-09-15
A stable release following release of Postgres 16. No code changes since beta.
2.3.0-beta - 2023-08-30
Updated for Postgres 16.
When connected to Postgres 16+, output()
method of numeric type converters will accept non-decimal integer literals
and numeric literals with underscores for digit separators, allowing to use those as query parameter values.
2.2.0 - 2023-05-12
- Code that deals with loading type data from DB / cache and mapping type names to type OIDs was extracted
from
DefaultTypeConverterFactory
into a newCachedTypeOIDMapper
class implementing a newTypeOIDMapper
interface.DefaultTypeConverterFactory
accepts an implementation of that interface viasetOIDMapper()
method, defaulting to the old implementation.
setCompositeTypesCaching()
andgetCompositeTypesCaching()
methods ofDefaultTypeConverterFactory
. While they will continue to work if an instance ofCachedTypeOIDMapper
is used by the factory for OID mapping, their usage should be switched to the same methods ofCachedTypeOIDMapper
instance:// before $factory->setCompositeTypesCaching(true); // after $factory->getOIDMapper()->setCompositeTypesCaching(true);
2.1.1 - 2023-05-10
- Added forgotten
declare(strict_types=1)
to the files containing PHP classes - Added annotations to
ResultSet
that prevent psalm from triggering errors when iterating / getting offsets, see psalm issue #9698
2.1.0 - 2023-04-10
- Classes that represent complex Postgres types now implement
\JsonSerializable
interface (see request #11). SQL_JSON_ITEM_CANNOT_BE_CAST_TO_TARGET_TYPE
error code added in Postgres 15- Tested on PHP 8.2 and Postgres 15
2.0.0 - 2021-12-31
Updated static analyzers, no code changes.
2.0.0-beta - 2021-11-18
Updated for Postgres 14 and PHP 8.1. The major version is incremented due to a few BC breaks.
- Methods working with OIDs (e.g.
TypeConverterFactory::getConverterForTypeOID()
) no longer haveint
typehints: OIDs are unsigned 32-bit integers and may be out of range of PHP's signedint
type on 32-bit builds. converters\ConnectionAware
interface now defines asetConnection()
method accepting an instance ofConnection
instead ofsetConnectionResource()
method accepting an underlying resource. This was done to prevent the need for boilerplate code checking whether the passed value is a resource (before PHP 8.1) or an instance of\Pgsql\Connection
(PHP 8.1+) in implementations ofConnectionAware
.ServerException::fromConnection()
now accepts an instance ofConnection
rather than an underlying resource, this was done mostly for the same reasons as above.ConnectionException
extendsServerException
so that it is now possible to specifySQLSTATE
error code for it (e.g.ServerException::ADMIN_SHUTDOWN
).
- As
pgsql
functions in PHP 8.1 now return and accept objects instead of resources, added checks for these objects alongsideis_resource
checks for earlier PHP versions. - Full support for multirange types added in Postgres 14, with
types\Multirange
and its descendants to represent the values on PHP side andconverters\containers\MultiRangeConverter
to transform the values to and from DB string representation. - New error code defined in Postgres 14.
- Support for infinite values in
NumericConverter
(numeric type in Postgres 14 allows these). Connection::getLastError()
method.
Missing bounds in range types are always marked as exclusive, this follows PostgreSQL's behaviour.
1.0.0 - 2021-06-26
ResultSet
caches the last fetched row: e.g. accessing $result[0]['field2']
after $result[0]['field1']
will no longer cause an additional pg_fetch_array()
call with subsequent type conversions
DefaultTypeConverterFactory
no longer registers converters for obsolete abstime
and reltime
types, those were
removed in Postgres 12
1.0.0-beta.4 - 2021-02-15
- Objects representing Postgres types are now immutable.
ResultSet::current()
andResultSet::offsetGet()
will returnnull
rather thanfalse
for non-existent offsets.Connection::execute()
,Connection::executeParams()
,PreparedStatement::execute()
will now consistently returnResultSet
instead ofResultSet|int|bool
. Number of affected rows for DML queries is available via newResultSet::getAffectedRows()
method.ext-pgsql
is a suggested dependency rather than required, so that type converters may be used with e.g. PDO
- Tested and supported on PHP 8
- Static analysis with phpstan and psalm
- Package
Exception
interface now extends\Throwable
- Lots of minor issues caught by static analysis
- Added sanity checks to
BaseDateTimeConverter
when working with connection resource (e.g. it will no longer try to getDateStyle
setting from closed connection). - Added tests for
FloatConverter
andNumericConverter
that check behaviour with locales having','
as a decimal separator. ByteaConverter
will reject non-strings.HstoreConverter
will properly error on invalid input.- Additional checks for
pg_*()
functions returningfalse
.
- Added sanity checks to
1.0.0-beta.3 - 2020-09-18
- Date and time converters will return
\DateTimeImmutable
instances instead of\DateTime
. DateTimeRange
bounds are now instances of\DateTimeImmutable
instead of\DateTime
. It accepts all\DateTimeInterface
implementations for bounds but will convert them to\DateTimeImmutable
.- Disallow subsequent
setConnection()
calls onTypeConverterFactory
implementations with differentConnection
instances.
- Date and time converters will accept instances of
\DateTimeInterface
, not just\DateTime
. StubConverter::output()
will convert a non-null value to string.DefaultTypeConverterFactory::setConnection()
properly updates the existing converters.
1.0.0-beta.2 - 2020-07-19
Namespaced BadMethodCallException
now extends SPL's BadMethodCallException
rather than InvalidArgumentException
1.0.0-beta - 2020-07-18
- Types array in
DefaultTypeConverterFactory
is pre-populated with built-in data types of PostgreSQL. Loading metadata from DB / cache will now only be needed if using custom types. Connection::atomic()
method which accepts a callable and executes it atomically, opening a transaction and creating savepoints for nestedatomic()
calls as needed. It will automatically commit if callback executes successfully and rollback if it throws an exception. It is possible to register callbacks to execute after the final commit or rollback.Connection::quoteIdentifier()
method.
- Requires at least PHP 7.2
- Requires at least PostgreSQL 9.3
- Split
TypeConverterFactory::getConverter()
method intogetConverterForTypeOID()
- returns a converter for the database type OID, used byResultSet
to find converters for result columns,getConverterForTypeSpecification()
- returns a converter for a user-supplied type specification (e.g. type name or array describing fields of the composite type).
- Removed
Connection::guessOutputFormat()
, addedTypeConverterFactory::getConverterForPHPValue()
instead. Made it possible to specify mapping between PHP classes and type converters inDefaultTypeConverterFactory
so that itsgetConverterForPHPValue()
implementation can process new custom types. - Methods
beginTransaction()
,commit()
,rollback()
no longer work with savepoints, separate methodscreateSavepoint()
,releaseSavepoint()
,rollbackToSavepoint()
added - Renamed
InvalidQueryException
toServerException
and added several subclasses for that. If a query fails:ConnectionException
is thrown when connection to server failed.- Subclass of
ServerException
is thrown based onSQLSTATE
error code when said code is available.
- Support for
mbstring.func_overload
, which was deprecated in PHP 7.2 fsec
field from customDateInterval
class, as nativef
field for fractional seconds is available since PHP 7.1.
- Optimized type converter for interval fields quite a bit.
- Sub-converters of container converters (array, composite and range) that implement
ConnnectionAware
now properly receive the connection resource. Connection::quote()
now uses recommendedpg_escape_literal()
under the hood.- Connection is automatically established only the first time it is needed, not after an explicit
disconnect()
call.
0.2.2 - 2017-09-18
Constructor of PreparedStatement
should skip null
values $paramTypes
like it did before 0.2.1
0.2.1 - 2017-09-12
- Manual
prepare()
/deallocate()
methods toPreparedStatement
- Allow cloning a
Connection
object, but force opening a different connection.
- Removed unused
BadMethodCallException
class
RangeConverter
could enter an infinite loop on some invalid input.- Field index in
ResultSet
was checked against wrong property. - Types specified for query parameters and results as
TypeConverter
instances will always be passed throughTypeConverterFactory::getConverter()
so that converters implementingConnectionAware
can be properly configured. Previous behaviour was inconsistent. - When a
TypeConverter
instance is passed toStubTypeConverterFactory::getConverter()
it will be returned instead ofStubConverter
. Converter implementingConnectionAware
will be configured with current connection, like withDefaultTypeConverterFactory
.
0.2.0 - 2017-09-04
- It is now possible to cache composite types' structure and automatically load structure of free-standing composite types.
- New
converters\StubConverter
andconverters\StubTypeConverterFactory
allow to essentially switch off type conversion. Instance of the former is also now returned instead ofconverters\StringConverter
when a proper converter cannot be determined.
- Removed
MetadataCache
interface and its implementations. The package can now use any PSR-6 compatible cache implementation for metadata. TypeConverterFactory
is now an interface. Previous class is renamedconverters\DefaultTypeConverterFactory
and implements said interface.- Features depending on classes from
sad_spirit\pg_builder
package were removed fromDefaultTypeConverterFactory
, will now be available insad_spirit\pg_builder
.
converters\containers\CompositeConverter
changed to not useeach()
construct deprecated in PHP 7.2
0.1.0 - 2014-09-28
Initial release on GitHub