pg_convert

    (PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

    pg_convert — Convert associative array values into forms suitable for SQL statements

    Description

    pg_convert(
        PgSql\Connection $connection,
        string $table_name,
        array $values,
        int $flags = 0
    ): array|false

    pg_convert() checks and converts the values in values into suitable values for use in an SQL statement. Precondition for pg_convert() is the existence of a table table_name which has at least as many columns as values has elements. The fieldnames in table_name must match the indices in values and the corresponding datatypes must be compatible. Returns an array with the converted values on success, false otherwise.

    Note:

    Boolean values are accepted and converted to PostgreSQL booleans. String representations of boolean values are also supported. null is converted to PostgreSQL NULL.

    Parameters

    connection

    An PgSql\Connection instance.

    table_name

    Name of the table against which to convert types.

    values

    Data to be converted.

    flags

    Any number of PGSQL_CONV_IGNORE_DEFAULT, PGSQL_CONV_FORCE_NULL or PGSQL_CONV_IGNORE_NOT_NULL, combined.

    Return Values

    An array of converted values, or false on failure.

    Errors/Exceptions

    A ValueError or TypeError is thrown when the value or type of field does not match properly with a PostgreSQL's type.

    Changelog

    Version Description
    8.3.0 Now throws a ValueError or TypeError error when the value or type of field does not match properly with a PostgreSQL's type; previously an E_WARNING was emitted.
    8.1.0 The connection parameter expects an PgSql\Connection instance now; previously, a resource was expected.

    Examples

    Example #1 pg_convert() example

    <?php
    $dbconn     = pg_connect('dbname=foo');

    $tmp = array(
    'author' => 'Joe Thackery',
    'year' => 2005,
    'title' => 'My Life, by Joe Thackery'
    );

    $vals = pg_convert($dbconn, 'authors', $tmp);
    ?>

    See Also

    Improve This Page

    Learn How To Improve This Page • Submit a Pull Request • Report a Bug
    ＋add a note

    User Contributed Notes 5 notes

    up
    2
    Anonymous
    20 years ago
    The only options that I see are:

    PGSQL_CONV_IGNORE_DEFAULT - Do not use DEAFULT value by removing field from returned array
    PGSQL_CONV_FORCE_NULL - Convert to NULL if string is null string
    PGSQL_CONV_IGNORE_NOT_NULL - Ignore NOT NULL constraints

    These are constants, so don't quote them or anything.
    up
    0
    gorhas at gmail dot com
    9 years ago
    There is a problem when using interval.
    If in the array
    "time_pause" => '00:30:00'
    and time_pause is an interval
    the insert fails
    pg_insert(): '00:30:00' does not match with '^(@?[ \t]+)?((([-+]?[ \t]+)?[0-9]+(\.[0-9]*)?[ ...
    up
    0
    dharana at dharana dot net
    21 years ago
    I've found "options" possible values:

    PG_CONV_CHECK - check only
    PG_CONV_STRICT - raise warning for non fatal error
    PG_CONV_QUOTE - add quote around values for vchar, text datetime.
    PG_CONV_SLASH - add slashes if it needed.
    PG_CONV_NULLCHK - check values are defined for NOT NULL fields.
    PG_CONV_NO_DEFAULT - ignore default value even if value is empty string.
    up
    -1
    VLroyrenn
    6 years ago
    Another thing that's not well documented is that (as of PHP 7.0/7.1) pg_convert doesn't like non-scalar types and will fail (but not throw just emit an E_WARNING and return false) if you pass it anything other than a string or a number, including an array or something like a DateTime. If you want to insert those types, you actually have to convert those yourself.

    Also, somewhat surprisingly, $table_name is not compatible with the output of pg_​escape_​identifier, or seemingly any other kind of escaping.
    up
    -1
    Hayley Watson
    7 years ago
    This will only apply the appropriate escaping and such appropriate for embedding the PHP value into an SQL statement.

    It does (by default) check for nulls when the column is marked NOT NULL, and it will complain about trying to convert strings for an integer column (floats will be truncated).

    Beyond the barest checking of syntax, however, it does NOT verify that the given value is a legitimate value for the column type.

    <?php
    // Assuming smallints.smallintis a smallint (-32768..32767) type column
    foreach([-1234,
    1234,
    0,
    32767,
    -    32768,
    32768, // bogus value for smallint type
    45.8, // gets truncated to 45
    400000, // bogus value for smallint type
    ] as $smallint)
    {
    $tmp = ['smallint' => $smallint];
    $vals = pg_convert($dbconn, 'smallints', ['smallint' => $smallint]);
    echo     $vals['"smallint"'],"\n"; // Notice the column name is also made SQL-safe
    }

    // Assuming uuids.uuid is a UUID type column
    foreach(['a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    'A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11',
    'a0eebc999c0b4ef8bb6d6bb9bd380a11',
    '{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11}',
    'Invalid Not-a-UUID',
    '{a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11}',
    'a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11',
    ] as     $uuid)
    {
    $tmp = ['uuid' => $uuid];
    $vals = pg_convert($dbconn, 'uuids', ['uuid' => $uuid]);
    echo     $vals['"uuid"'],"\n";
    }

    ?>

    All of the above data values will be "converted" - even the invalid ones - without complaint.
    ＋add a note
    To Top