CmsDb

An extension of SimplePDO allowing to keep track of all changes in the database and enabling the user to confirm or undo changes.

Overview ##CmsDbCreator

CmsDb extends SimplePDO {
    public __construct ($host, $db, $user, $pw)
    public mixed query (string $query[, string $ph_types, mixed $ph_value1[, mixed $ph_value2[, ...]]])
    public mixed query (string $query[, string $ph_types, array $ph_values])
    public int confirmChange (int $change_id, string $token)
    public int undoChange (int $change_id, string $token)
    public array getLastQuery ()
}

CmsDb::__construct()

public CmsDb::__construct (string $host, string $db, string $user, string $pw)

Creates a CmsDb instance representing representing a simplified connection to a MySQL database. That database has to be CmsDb-formatted (i.e. the CmsDbCreator::formatDatabase() method has to have been applied).

Parameters

The parameters are equal to the ones of SimplePDO::__construct().

• $host The IP address or URL of the MySQL server to connect to.
• $db The name of the CmsDbAdv-formatted databse.
• $user The user used to log into the database.
• $pw The user's password.

Return Values

Returns a CmsDb object on success.

CmsDb::query()

public mixed CmsDb::query (string $query[, string $ph_types, mixed $ph_value1[, mixed $ph_value2[, ...]]])
public mixed CmsDb::query (string $query[, string $ph_typesmarkdown-header-, array $ph_values])

Analyzes an SQL query and transforms it if CmsDb-formatted tables are concerned before transmitting it to the MySQL server using the SimplePDO::query() method.

Parameters

The parameters are equal to the ones of SimplePDO::query().

• $query The SQL query to process. The SQL syntax allowed by MySQL is not fully supported, e.g. you can't use the INSERT INTO table SET column = value syntax and escaped table or column names like `table_name` are disallowed. You can detect problems using the CmsDb::getLastQuery() method and request any useful syntax recognition using a ticket.

• $ph_types A string containing the variable types to check the placeholder values against. The single letters must simply be concatenated in the order of appearance of the according "?" placeholders in the query (e.g. 'isib' for int, string, int, bool). See SimplePDO::query() for the available types.

• $ph_value1, $ph_value2, ... The values that should be inserted for the according placeholders.

  OR

• $ph_values An array containing all placeholder values. That array may be any one-dimensional array, even an associative one.

Return Values

If the query was an INSERT, UPDATE or DELETE query affecting a CmsDb-formatted table: Returns a CmsDbResult object on success from which things like the last insert id or the number of affected rows can be retrieved and which enables you to retrieve confirmation keys etc. or directly confirm a change.

Else, i.e. as well if it was a SELECT query concerning a CmsDbAdv-formatted table: Behaves exactly like SimplePDO::query(), also returning the same information. This is

• an associative array containing the results of a SELECT or SHOW query,
• the last insert ID in the case of an INSERT query or
• the number of affected rows in every other case.

CmsDb::getLastQuery()

public array CmsDb::getLastQuery ()

Gives information about the query last executed with CmsDb::query(). This method is mainly intended for debugging purposes.

Return Values

Returns an array containing information about the last executed query. The array has the following structure (be aware that, depending on the type of query and on the moment when an error occurred, not all keys may be set):

array $last_query = (
    'funcArgs' => array $args, //an array containing the arguments passed to the query() method at its latest execution
    'extractedQueryType' => string $type, //the detected type of the last query (e.g. 'DELETE' or 'UPDATE'), this is not set if the query was directly passed to the CmsDb::query() method
    'extracted_table_name' => string $name, //the name of the CmsDbAdv-formatted table/view affected by the last query
    'executedQuery' => string $query, //the last query passed to the CmsDb::query() method (i.e. the query as it was transformed by the CmsDbAdv::query() method)
    'SimplePDO' => array $lastSimplePdoQuery //information retrieved with the SimplePDO::getLastQuery() method (see below)
    //there are, depending on the query type, more possible keys not specified here
);

For more information on the data in $last_query['SimplePDO'], see SimplePDO::getLastQuery(). It does not really represent the query last executed by SimplePDO but the last main query (generally the INSERT query). Other queries can have been executed by SimplePDO::query() after that main query, e.g. to check for any key violations.