Reference Manuals

DBAPI

DBAPI — This is the base DBAPI class.

DBAPI is part of the DBAPI package.

Synopsis

class DBAPI {
        private        array               $args
        private        array               $args_used
        public         bool                $cast_object_to_string
        public         bool                $compound_inserts
        protected      resource            $last_result
        private        array               $placeholders
        public         bool                $return_on_error

        public         DBAPI               __construct               ( string $dsn,
                                                                       string $username,
                                                                       string $password,
                                                                       array $options );
        private        string              add_placeholder           ( array $match );
        public         int                 affectedrows              ( void );
        private        string              build_insert_array        ( array $args,
                                                                       bool $use_keys );
        private        string              build_update_array        ( array $args );
        public         void                close                     ( void );
        private        int                 count_vars                ( string $query );
        public         int                 errno                     ( void );
        public         string              error                     ( void );
        public         mixed               escape                    ( mixed $var );
        protected      resource            execute_query             ( string $query );
        public         array               fetchcol                  ( resource $result );
        public         array               fetchrow                  ( resource $result );
        public         array               fetchrowset               ( resource $result );
        public         void                freeresult                ( resource $result );
        private        mixed               get_arg                   ( array $key );
        public         mixed               lastid                    ( void );
        protected      string              limit_query               ( string $query,
                                                                       int $length,
                                                                       int $start );
        public         array               parse_dsn                 ( strinf $dsn );
        private        string              parse_insert_query        ( string $query,
                                                                       array $args );
        private        array               parse_query               ( array $args );
        private        string              parse_single_query        ( string $query,
                                                                       array $args );
        public         resource            query                     ( string $query,
                                                                       mixed $arg,... );
        public         resource            query_limit               ( string $query,
                                                                       mixed $arg,...,
                                                                       int $start,
                                                                       int $length );
        public         mixed               quote                     ( mixed $var );
        private        string              restore_placeholder       ( array $match );
        public         void                return_on_error           ( bool $bool );
}

Object Hierarchy

DBAPI
 +----phppdo
 +----sqlite2
 +----mysql

Description

This is the base DBAPI class.

Specific implementations should subclass this base class and implement the database specific functions marked as abstract.

Attribute Details

$args

private        array          $args

An array used for the arguments to be parsed into a query

Default value: empty string

$args_used

private        array          $args_used

An array to keep track of used arguments. This allows named arguments to be used multiple times.

Default value: empty string

$cast_object_to_string

public         bool           $cast_object_to_string

Whether to cast variables of type 'object' to string

Default value: empty string

$compound_inserts

public         bool           $compound_inserts

Whether or not compound insert statements shouldbe used

Default value: empty string

$last_result

protected      resource       $last_result

The last used SQL result resource

$placeholders

private        array          $placeholders

An array containing quoted strings and their placeholders. Used during query parsing

Default value: empty string

$return_on_error

public         bool           $return_on_error

Whether to return silently on an SQL error or let PHP handle it

Default value: empty string

Method Details

__construct()

public         DBAPI          __construct               ( string $dsn,
                                                          string $username,
                                                          string $password,
                                                          array $options );

Create a database connection

This function is identical to PHP's PDO() constructor.

$dsn
A DSN connection string for the database
$username
The username to authenticate with
$password
The password for the user
$options
The options for the database

add_placeholder()

private        string         add_placeholder           ( array $match );

A preg_replace() callback to replace a quoted string with a placeholder

$match
The matched array of quoted string to be replaced

affectedrows()

public         int            affectedrows              ( void );

Get the number of rows affected by the last query

build_insert_array()

private        string         build_insert_array        ( array $args,
                                                          bool $use_keys );

Build an SQL insert statement out of a series of arguments

$args
The arguments to build the insert statement from
$use_keys
If this is true, use named arguments instead of argument values

build_update_array()

private        string         build_update_array        ( array $args );

Build an SQL update statement out of a series of arguments

$args
The arguments to build the update statement from

close()

public         void           close                     ( void );

Close the database connection

count_vars()

private        int            count_vars                ( string $query );

Count the number of variables/placeholders in an SQL query

$query
The query to count variables in

errno()

public         int            errno                     ( void );

Return the last SQL error number

error()

public         string         error                     ( void );

Return the last SQL error message

escape()

public         mixed          escape                    ( mixed $var );

Escape a variable to safely use in in SQL

$var
The varibale to escape

execute_query()

protected      resource       execute_query             ( string $query );

Execute a single SQL query

$query
The SQL query to execute

fetchcol()

public         array          fetchcol                  ( resource $result );

Fetch an array containing the values of the first column in the result set

$result
The SQL result resource. Default is NULL which means the last result resource used

fetchrow()

public         array          fetchrow                  ( resource $result );

Fetch a single row from the SQL result set. If no result is specified, it should use the protected last_result variable

$result
The SQL result resource. Default is NULL

fetchrowset()

public         array          fetchrowset               ( resource $result );

Fetch an array of rows from the SQL result set. If no result is specified, it should use the protected last_result variable

$result
The SQL result resource. Default is NULL

freeresult()

public         void           freeresult                ( resource $result );

Free an SQL result resource. If no result is specified, it should use the protected last_result variable

$result
The result resource to free. Default is NULL

get_arg()

private        mixed          get_arg                   ( array $key );

A preg_replace callback to return a quoted/escaped argument and remove it from the SQL argument list

$key
The matched array of argument keys to return.

lastid()

public         mixed          lastid                    ( void );

Get the unique ID of the last row that was insterted in the database

limit_query()

protected      string         limit_query               ( string $query,
                                                          int $length,
                                                          int $start );

Modify a query to limit the size of the returned result set

$query
The query to modify
$length
The maximum size of the result set
$start
The offset into the result set. Default is 0

parse_dsn()

public         array          parse_dsn                 ( strinf $dsn );

Parse a data source name.

This function takes a PHP PDO compatible DSN and parses it into an array containing key-value pairs from the DSN string. The database type prefix is set in the phptype field.

$dsn
A PDO-compatible DSN connection string

parse_insert_query()

private        string         parse_insert_query        ( string $query,
                                                          array $args );

Parse a two dimensional array into one big compound INSERT statement

$query
The SQL query to parse
$args
The arguments for the query. See README for usage.

parse_query()

private        array          parse_query               ( array $args );

Parse a set of variables in one or more queries. Queries are passed in the form of array($query, [, arg [, ...]]). It determins the kind of query (INSERT or something else) and the number of queries. The actual parsing is done in parse_single_query() or parse_insert_query().

$args
An array containing the query and the arguments to parse in the query

parse_single_query()

private        string         parse_single_query        ( string $query,
                                                          array $args );

Parse a series of variables into an SQL query. Variables in the query can be specified as positional arguments ? or ar named variables {variable}. First all the named variables from the argument list are replaces, then the positional arguments from whatever is left from the argument list.

$query
The SQL query to parse
$args
The arguments for the query. See README for usage.

query()

public         resource       query                     ( string $query,
                                                          mixed $arg,... );

Execute a regular SQL query

$query
The SQL query to execute
$arg,...
Optional. The arguments for the query. See README for usage.

query_limit()

public         resource       query_limit               ( string $query,
                                                          mixed $arg,...,
                                                          int $start,
                                                          int $length );

Execute a query and return a limited set of results

$query
The SQL query to execute
$arg,...
The arguments for the query. See README for usage.
$start
Starting offset in the result set
$length
The number of records to return

quote()

public         mixed          quote                     ( mixed $var );

Escape and properly quote a variable

$var
The variable to escape and quote

restore_placeholder()

private        string         restore_placeholder       ( array $match );

A preg_replace() callback to restore a placeholder with the original text

$match
The matched array of placeholder to replace

return_on_error()

public         void           return_on_error           ( bool $bool );

Whether to return when an SQL error occurs (TRUE) or to trigger an error (FALSE).

$bool
TRUE if the DBAPI should capture errors and return normally, FALSE if errors should be handled by PHP. Default: FALSE