Class Database

Copyright: 2004-2016 The Admidio Team
License: GNU General Public License v2.0 only **********************************************************************************************
Brief:

Handle the connection to the database, send all sql statements and handle the returned rows.

This class creates a connection to the database and provides several methods to communicate with the database. There are methods to send sql statements and to handle the response of the database. This class also supports transactions. Just call Database#startTransaction and finish it with Database#endTransaction. If you call this multiple times only 1 transaction will be open and it will be closed after the last endTransaction was send.

Class: Database
Code:

// create object and open connection to database try { $gDb = new Database($gDbType, $g_adm_srv, null, $g_adm_db, $g_adm_usr, $g_adm_pw); } catch (AdmException $e) { $e->showText(); }

Code:

// send sql to database and assign the returned PDOStatement $organizationsStatement = $gDb->query('SELECT org_shortname, org_longname FROM adm_organizations');

// now fetch all rows of the returned PDOStatement within one array $organizationsList = $organizationsStatement->fetchAll();

// Array with the results: // $organizationsList = array( // [0] => array( // [org_shortname] => 'DEMO' // [org_longname] => 'Demo-Organization' // ) // [1] => array( // [org_shortname] => 'TEST' // [org_longname] => 'Test-Organization' // )

// you can also go step by step through the returned PDOStatement while ($organizationNames = $organizationsStatement->fetch()) { echo $organizationNames['shortname'].' '.$organizationNames['longname']; }

Endcode: Now you can use the new object @b $gDb to send a query to the database
Endcode
Par:

Examples To open a connection you can use the settings of the config.php of Admidio.

Located at database.php

Methods summary

`public`	# `__construct( string $engine, string $host, integer $port, string $dbName, string $username = null, string $password = null, array $options = array() )` The constructor will check if a valid engine was set and try to connect to the database. If the engine is invalid or the connection not possible an exception will be thrown. The constructor will check if a valid engine was set and try to connect to the database. If the engine is invalid or the connection not possible an exception will be thrown. Parameters `$engine` The database type that is supported from Admidio. @b mysql and @b pgsql are valid values. `$host` The hostname or server where the database is running. e.g. localhost or 127.0.0.1 `$port` If you don't use the default port of the database then set your port here. `$dbName` Name of the database you want to connect. `$username` Username to connect to database `$password` Password to connect to database `$options` Throws `AdmException`
`private`	# `setDSNString( string $engine )` Create a valid DSN string for the engine that was set through the constructor. If no valid engine is set than an exception is thrown. Create a valid DSN string for the engine that was set through the constructor. If no valid engine is set than an exception is thrown. Parameters `$engine` The database type that is supported from Admidio. @b mysql and @b pgsql are valid values. Throws PDOException
`private`	# `setConnectionOptions( )` Set connection specific options like UTF8 connection. These options should always be set if Admidio connect to a database. Set connection specific options like UTF8 connection. These options should always be set if Admidio connect to a database.
`protected string`	# `getPropertyFromDatabaseConfig( string $property )` Parameters `$property` Property name of the in use database config Returns string Returns the value of the chosen property
`public string`	# `getName( )` Get the name of the database that is running Admidio. Get the name of the database that is running Admidio. Returns string Returns a string with the name of the database e.g. 'MySQL' or 'PostgreSQL'
`public string`	# `getMinimumRequiredVersion( )` Get the minimum required version of the database that is necessary to run Admidio. Get the minimum required version of the database that is necessary to run Admidio. Returns string Returns a string with the minimum required database version e.g. '5.0.1'
`public string`	# `getVersion( )` Get the version of the connected database. Get the version of the connected database. Returns string Returns a string with the database version e.g. '5.5.8'
`public boolean`	# `startTransaction( )` Start a transaction if no open transaction exists. If you call this multiple times only 1 transaction will be open and it will be closed after the last endTransaction was send. Start a transaction if no open transaction exists. If you call this multiple times only 1 transaction will be open and it will be closed after the last endTransaction was send. Returns boolean See Database#endTransaction Database#rollback
`public boolean`	# `endTransaction( )` The method will commit an open transaction to the database. If the transaction counter is greater 1 than only the counter will be decreased and no commit will performed. The method will commit an open transaction to the database. If the transaction counter is greater 1 than only the counter will be decreased and no commit will performed. Returns boolean Returns @b true if the commit was successful otherwise @b false See Database#startTransaction Database#rollback
`public string`	# `escapeString( string $string )` Escapes special characters within the input string. In contrast to the quote method, the returned string has no quotes around the input string! Escapes special characters within the input string. In contrast to the quote method, the returned string has no quotes around the input string! Parameters `$string` The string to be quoted. Returns string Returns a quoted string that is theoretically safe to pass into an SQL statement. See PDO::quote
`protected string`	# `getBacktrace( )` This method will create an backtrace of the current position in the script. If several scripts were called than each script with their position will be listed in the backtrace. This method will create an backtrace of the current position in the script. If several scripts were called than each script with their position will be listed in the backtrace. Returns string Returns a string with the backtrace of all called scripts.
`public string`	# `lastInsertId( )` Returns the ID of the unique id column of the last INSERT operation. This method replace the old method Database#insert_id. Returns the ID of the unique id column of the last INSERT operation. This method replace the old method Database#insert_id. Returns string Return ID value of the last INSERT operation. See Database#insert_id
`public PDOStatement`	# `query( string $sql, boolean $showError = true )` Send a sql statement to the database that will be executed. If debug mode is set then this statement will be written to the error log. If it's a @b SELECT statement then also the number of rows will be logged. If an error occurred the script will be terminated and the error with a backtrace will be send to the browser. Send a sql statement to the database that will be executed. If debug mode is set then this statement will be written to the error log. If it's a @b SELECT statement then also the number of rows will be logged. If an error occurred the script will be terminated and the error with a backtrace will be send to the browser. Parameters `$sql` A string with the sql statement that should be executed in database. `$showError` Default will be @b true and if an error the script will be terminated and occurred the error with a backtrace will be send to the browser. If set to Returns PDOStatement For @b SELECT statements an object of PDOStatement will be returned. This should be used to fetch the returned rows. If an error occurred then @b false will be returned. B false no error will be shown and the script will be continued.
`public boolean`	# `rollback( )` If there is a open transaction than this method sends a rollback to the database and will set the transaction counter to zero. If there is a open transaction than this method sends a rollback to the database and will set the transaction counter to zero. Returns boolean See Database#startTransaction Database#endTransaction
`public string[]\|array[]`	# `showColumns( string $table, boolean $showColumnProperties = true )` Methods reads all columns and their properties from the database table. Methods reads all columns and their properties from the database table. Parameters `$table` Name of the database table for which the columns should be shown. `$showColumnProperties` If this is set to @b false only the column names were returned. Returns string[]\|array[] Returns an array with each column and their properties if $showColumnProperties is set to @b true. The array has the following format: array ( 'column1' => array ( 'serial' => '1', 'null' => '0', 'key' => '0', 'type' => 'integer' ), 'column2' => array (...) ... ) TODO https://secure.php.net/manual/en/pdostatement.getcolumnmeta.php https://www.postgresql.org/docs/9.5/static/infoschema-columns.html https://dev.mysql.com/doc/refman/5.7/en/columns-table.html
`public`	# `showError( )` Display the error code and error message to the user if a database error occurred. The error must be read by the child method. This method will call a backtrace so you see the script and specific line in which the error occurred. Display the error code and error message to the user if a database error occurred. The error must be read by the child method. This method will call a backtrace so you see the script and specific line in which the error occurred. Returns Will exit the script and returns a html output with the error information.
`public static string[]`	# `getAvailableDBs( )` Returns an array with all available PDO database drivers of the server. Returns an array with all available PDO database drivers of the server. Deprecated 3.1.0:4.0.0 Switched to native PDO method. Returns string[] Returns an array with all available PDO database drivers of the server. See PDO::getAvailableDrivers
`public mixed\|null`	# `fetch_array( PDOStatement $pdoStatement = null, integer $fetchType = PDO::FETCH_BOTH )` Fetch a result row as an associative array, a numeric array, or both. Fetch a result row as an associative array, a numeric array, or both. Deprecated 3.1.0:4.0.0 Switched to native PDO method. Please use the PHP class PDOStatement and the method fetch instead. Parameters `$pdoStatement` An object of the class PDOStatement. This should be set if multiple rows where selected and other sql statements are also send to the database. `$fetchType` Set the result type. Can contain @b PDO::FECTH_ASSOC for an associative array, Returns mixed\|null Returns an array that corresponds to the fetched row and moves the internal data pointer ahead. See PDOStatement::fetch B PDO::FETCH_NUM for a numeric array or @b PDO::FETCH_BOTH (Default).
`public mixed\|null`	# `fetch_object( PDOStatement $pdoStatement = null )` Fetch a result row as an object. Fetch a result row as an object. Deprecated 3.1.0:4.0.0 Switched to native PDO method. Please use methods Database#fetchAll or Database#fetch instead. Please use the PHP class PDOStatement and the method fetchObject instead. Parameters `$pdoStatement` An object of the class PDOStatement. This should be set if multiple rows where selected and other sql statements are also send to the database. Returns mixed\|null Returns an object that corresponds to the fetched row and moves the internal data pointer ahead. See PDOStatement::fetchObject
`public string`	# `insert_id( )` Returns the ID of the unique id column of the last INSERT operation. Returns the ID of the unique id column of the last INSERT operation. Deprecated 3.1.0:4.0.0 Renamed method to camelCase style. Please use methods Database#lastInsertId instead. Returns string Return ID value of the last INSERT operation. See Database#lastInsertId
`public integer\|null`	# `num_rows( PDOStatement $pdoStatement = null )` Returns the number of rows of the last executed statement. Returns the number of rows of the last executed statement. Deprecated 3.1.0:4.0.0 Switched to native PDO method. Please use the PHP class PDOStatement and the method rowCount instead. Parameters `$pdoStatement` An object of the class PDOStatement. This should be set if multiple rows where selected and other sql statements are also send to the database. Returns integer\|null Return the number of rows of the result of the sql statement. See PDOStatement::rowCount

Properties summary

`protected`	`$host`	#
`protected`	`$port`	#
`protected`	`$dbName`	#
`protected`	`$username`	#
`protected`	`$password`	#
`protected`	`$options`	#
`protected`	`$dsn`	#
`protected`	`$pdo`	#
`protected`	`$transactions`	#
`protected`	`$pdoStatement`	#
`protected`	`$dbStructure`	#
`protected`	`$fetchArray`	#
`protected`	`$minRequiredVersion`	#
`protected`	`$databaseName`	#

Packages

Classes

Exceptions

Functions

Class Database

Methods summary

Parameters

Throws

Parameters

Throws

Parameters

Returns

Returns

Returns

Returns

Returns

See

Returns

See

Parameters

Returns

See

Returns

Returns

See

Parameters

Returns

B

Returns

See

Parameters

Returns

Returns

Deprecated

Returns

See

Deprecated

Parameters

Returns

See

B

Deprecated

Parameters

Returns

See

Deprecated

Returns

See

Deprecated

Parameters

Returns

See

Properties summary