SQLite3

class SQLite3 (View source)

A class that interfaces SQLite 3 databases.

Constants

OK Since: 8.0

DENY Since: 8.0

IGNORE Since: 8.0

CREATE_INDEX Since: 8.0

CREATE_TABLE Since: 8.0

CREATE_TEMP_INDEX Since: 8.0

CREATE_TEMP_TABLE Since: 8.0

CREATE_TEMP_TRIGGER Since: 8.0

CREATE_TEMP_VIEW Since: 8.0

CREATE_TRIGGER Since: 8.0

CREATE_VIEW Since: 8.0

DELETE Since: 8.0

DROP_INDEX Since: 8.0

DROP_TABLE Since: 8.0

DROP_TEMP_INDEX Since: 8.0

DROP_TEMP_TABLE Since: 8.0

DROP_TEMP_TRIGGER Since: 8.0

DROP_TEMP_VIEW Since: 8.0

DROP_TRIGGER Since: 8.0

DROP_VIEW Since: 8.0

INSERT Since: 8.0

PRAGMA Since: 8.0

READ Since: 8.0

SELECT Since: 8.0

TRANSACTION Since: 8.0

UPDATE Since: 8.0

ATTACH Since: 8.0

DETACH Since: 8.0

ALTER_TABLE Since: 8.0

REINDEX Since: 8.0

ANALYZE Since: 8.0

CREATE_VTABLE Since: 8.0

DROP_VTABLE Since: 8.0

FUNCTION Since: 8.0

SAVEPOINT Since: 8.0

COPY Since: 8.0

RECURSIVE Since: 8.0

Methods

void
open(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = '')

Opens an SQLite database

bool
close()

Closes the database connection

bool
exec(string $query)

Executes a result-less query against a given database

static array
version()

Returns the SQLite3 library version as a string constant and as a number

int
lastInsertRowID()

Returns the row ID of the most recent INSERT into the database

int
lastErrorCode()

Returns the numeric result code of the most recent failed SQLite request

string
lastErrorMsg()

Returns English text describing the most recent failed SQLite request

bool
busyTimeout(int $milliseconds)

Sets the busy connection handler

bool
loadExtension(string $name)

Attempts to load an SQLite extension library

int
changes()

Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement

static string
escapeString(string $string)

Returns a string that has been properly escaped

SQLite3Stmt|false
prepare(string $query)

Prepares an SQL statement for execution

SQLite3Result|false
query(string $query)

Executes an SQL query

mixed
querySingle(string $query, bool $entireRow = false)

Executes a query and returns a single result

bool
createFunction(string $name, mixed $callback, int $argCount = -1, int $flags = 0)

Registers a PHP function for use as an SQL scalar function

bool
createAggregate(string $name, mixed $stepCallback, mixed $finalCallback, int $argCount = -1)

Registers a PHP function for use as an SQL aggregate function

bool
createCollation(string $name, callable $callback)

Registers a PHP function for use as an SQL collating function

resource|false
openBlob(string $table, string $column, int $rowid, string $database = 'main', int $flags = SQLITE3_OPEN_READONLY)

Opens a stream resource to read a BLOB

bool
enableExceptions(bool $enable = false)

Enable throwing exceptions

__construct(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = '')

Instantiates an SQLite3 object and opens an SQLite 3 database

int
lastExtendedErrorCode()

No description

bool
enableExtendedResultCodes(bool $enable = true)

No description

bool
backup(SQLite3 $destination, string $sourceDatabase = 'main', string $destinationDatabase = 'main')

Backup one database to another database

bool
setAuthorizer(callable|null $callback)

Configures a callback to be used as an authorizer to limit what a statement can do

Details

at line 153
void open(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = '')

Opens an SQLite database

Parameters

string $filename

Path to the SQLite database, or :memory: to use in-memory database.

int $flags

Optional flags used to determine how to open the SQLite database. By default, open uses SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE.

SQLITE3_OPEN_READONLY: Open the database for reading only.

string $encryptionKey

An optional encryption key used when encrypting and decrypting an SQLite database.

Return Value

void

No value is returned.

at line 167
bool close()

Closes the database connection

Return Value

bool

TRUE on success, FALSE on failure.

at line 179
bool exec(string $query)

Executes a result-less query against a given database

Parameters

string $query

The SQL query to execute (typically an INSERT, UPDATE, or DELETE query).

Return Value

bool

TRUE if the query succeeded, FALSE on failure.

at line 188
static array version()

Returns the SQLite3 library version as a string constant and as a number

Return Value

array

an associative array with the keys "versionString" and "versionNumber".

at line 197
int lastInsertRowID()

Returns the row ID of the most recent INSERT into the database

Return Value

int

the row ID of the most recent INSERT into the database

at line 206
int lastErrorCode()

Returns the numeric result code of the most recent failed SQLite request

Return Value

int

an integer value representing the numeric result code of the most recent failed SQLite request.

at line 214
string lastErrorMsg()

Returns English text describing the most recent failed SQLite request

Return Value

string

an English string describing the most recent failed SQLite request.

at line 227
bool busyTimeout(int $milliseconds)

Since: 5.3

Sets the busy connection handler

Parameters

int $milliseconds

The milliseconds to sleep. Setting this value to a value less than or equal to zero, will turn off an already set timeout handler.

Return Value

bool

TRUE on success, FALSE on failure.

at line 239
bool loadExtension(string $name)

Attempts to load an SQLite extension library

Parameters

string $name

The name of the library to load. The library must be located in the directory specified in the configure option sqlite3.extension_dir.

Return Value

bool

TRUE if the extension is successfully loaded, FALSE on failure.

at line 250
int changes()

Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement

Return Value

int

an integer value corresponding to the number of database rows changed (or inserted or deleted) by the most recent SQL statement.

at line 262
static string escapeString(string $string)

Returns a string that has been properly escaped

Parameters

string $string

The string to be escaped.

Return Value

string

a properly escaped string that may be used safely in an SQL statement.

at line 273
SQLite3Stmt|false prepare(string $query)

Prepares an SQL statement for execution

Parameters

string $query

The SQL query to prepare.

Return Value

SQLite3Stmt|false

an SQLite3Stmt object on success or FALSE on failure.

at line 284
SQLite3Result|false query(string $query)

Executes an SQL query

Parameters

string $query

The SQL query to execute.

Return Value

SQLite3Result|false

an SQLite3Result object, or FALSE on failure.

at line 310
mixed querySingle(string $query, bool $entireRow = false)

Executes a query and returns a single result

Parameters

string $query

The SQL query to execute.

bool $entireRow

[optional]

By default, querySingle returns the value of the first column returned by the query. If entire_row is TRUE, then it returns an array of the entire first row.

Return Value

mixed

the value of the first column of results or an array of the entire first row (if entire_row is TRUE).

If the query is valid but no results are returned, then NULL will be returned if entire_row is FALSE, otherwise an empty array is returned.

Invalid or failing queries will return FALSE.

at line 337
bool createFunction(string $name, mixed $callback, int $argCount = -1, int $flags = 0)

Registers a PHP function for use as an SQL scalar function

Parameters

string $name

Name of the SQL function to be created or redefined.

mixed $callback

The name of a PHP function or user-defined function to apply as a callback, defining the behavior of the SQL function.

int $argCount

The number of arguments that the SQL function takes. If this parameter is negative, then the SQL function may take any number of arguments.

int $flags

A bitwise conjunction of flags. Currently, only SQLITE3_DETERMINISTIC is supported, which specifies that the function always returns the same result given the same inputs within a single SQL statement.

Return Value

bool

TRUE upon successful creation of the function, FALSE on failure.

at line 367
bool createAggregate(string $name, mixed $stepCallback, mixed $finalCallback, int $argCount = -1)

Registers a PHP function for use as an SQL aggregate function

Parameters

string $name

Name of the SQL aggregate to be created or redefined.

mixed $stepCallback

The name of a PHP function or user-defined function to apply as a callback for every item in the aggregate.

mixed $finalCallback

The name of a PHP function or user-defined function to apply as a callback at the end of the aggregate data.

int $argCount

[optional]

The number of arguments that the SQL aggregate takes. If this parameter is negative, then the SQL aggregate may take any number of arguments.

Return Value

bool

TRUE upon successful creation of the aggregate, FALSE on failure.

at line 391
bool createCollation(string $name, callable $callback)

Since: 5.3

Registers a PHP function for use as an SQL collating function

Parameters

string $name

Name of the SQL collating function to be created or redefined

callable $callback

The name of a PHP function or user-defined function to apply as a callback, defining the behavior of the collation. It should accept two strings and return as strcmp does, i.e. it should return -1, 1, or 0 if the first string sorts before, sorts after, or is equal to the second.

Return Value

bool

TRUE on success or FALSE on failure.

at line 405
resource|false openBlob(string $table, string $column, int $rowid, string $database = 'main', int $flags = SQLITE3_OPEN_READONLY)

Opens a stream resource to read a BLOB

Parameters

string $table

The table name.
string $column

The column name.
int $rowid

The row ID.
string $database

[optional]

The symbolic name of the DB
int $flags

[optional]

Either SQLITE3_OPEN_READONLY or SQLITE3_OPEN_READWRITE to open the stream for reading only, or for reading and writing, respectively.

Return Value

resource|false

Returns a stream resource, or FALSE on failure.

at line 423
bool enableExceptions(bool $enable = false)

Enable throwing exceptions

Parameters

bool $enable

When true, the SQLite3 instance, and SQLite3Stmt and SQLite3Result instances derived from it, will throw exceptions on error. When false, the SQLite3 instance, and SQLite3Stmt and SQLite3Result instances derived from it, will raise warnings on error. For either mode, the error code and message, if any, will be available via SQLite3::lastErrorCode and SQLite3::lastErrorMsg respectively.

Return Value

bool

Returns the old value; true if exceptions were enabled, false otherwise.

at line 449
__construct(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = '')

Instantiates an SQLite3 object and opens an SQLite 3 database

Parameters

string $filename

Path to the SQLite database, or :memory: to use in-memory database.

int $flags

Optional flags used to determine how to open the SQLite database. By default, open uses SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE.

SQLITE3_OPEN_READONLY: Open the database for reading only.

string $encryptionKey

An optional encryption key used when encrypting and decrypting an SQLite database.

Exceptions

Exception

at line 461
int lastExtendedErrorCode()

Since: 7.4

No description

Return Value

int

at line 468
bool enableExtendedResultCodes(bool $enable = true)

Since: 7.4

No description

Parameters

bool $enable

Return Value

bool

at line 490
bool backup(SQLite3 $destination, string $sourceDatabase = 'main', string $destinationDatabase = 'main')

Since: 7.4

Backup one database to another database

SQLite3::backup copies the contents of one database into another, overwriting the contents of the destination database. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.

Parameters

SQLite3 $destination

A database connection opened with SQLite3::open.
string $sourceDatabase

The database name is "main" for the main database, "temp" for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database.
string $destinationDatabase

Analogous to sourceDatabase but for the destination.

Return Value

bool

Returns true on success or false on failure.

at line 511
bool setAuthorizer(callable|null $callback)

Since: 8.0

Configures a callback to be used as an authorizer to limit what a statement can do

Sets a callback that will be called by SQLite every time an action is performed (reading, deleting, updating, etc.). This is used when preparing a SQL statement from an untrusted source to ensure that the SQL statements do not try to access data they are not allowed to see, or that they do not try to execute malicious statements that damage the database. For example, an application may allow a user to enter arbitrary SQL queries for evaluation by a database. But the application does not want the user to be able to make arbitrary changes to the database. An authorizer could then be put in place while the user-entered SQL is being prepared that disallows everything except SELECT statements.

Parameters

callable|null $callback

The callable to be called. If null is passed instead, this will disable the current authorizer callback.

Return Value

bool

Returns true on success or false on failure.