MySQLDatabase
class MySQLDatabase extends Database implements TransactionManager (View source)
MySQL connector class.
Supported indexes for requireTable()
You are advised to backup your tables if changing settings on an existing database
connection_charset and charset should be equal, similarly so should connection_collation and collation
Traits
Provides extensions to this object to integrate it with standard config API methods.
Allows an object to have extensions applied to it.
Allows an object to declare a set of custom methods
Constants
| PARTIAL_QUERY |
|
| FULL_QUERY |
|
Config options
| extensions | array | An array of extension names and parameters to be applied to this object upon construction. |
from Extensible |
| unextendable_classes | array | Classes that cannot be extended |
from Extensible |
| optimistic_connect | bool | In cases where your environment does not have 'SHOW DATABASES' permission, you can set this to true. Then selectDatabase() will always connect without doing databaseExists() check. |
from Database |
| connection_charset | string | Default connection charset (may be overridden in $databaseConfig) |
|
| connection_collation | string | Default connection collation |
|
| charset | string | Default charset |
|
| sql_mode | string | SQL Mode used on connections to MySQL. Defaults to ANSI. For basic ORM compatibility, this setting must always include ANSI or ANSI_QUOTES. |
|
| collation | string | Default collation |
Properties
| protected static | array | $extra_methods | Custom method sources |
from CustomMethods |
| protected | array | $extra_method_registers | Name of methods to invoke by defineMethods for this instance |
from CustomMethods |
| protected static | array | $built_in_methods | Non-custom public methods. |
from CustomMethods |
| protected | Extension[] | $extension_instances | from Extensible | |
| protected | callable[][] | $beforeExtendCallbacks | List of callbacks to call prior to extensions having extend called on them, each grouped by methodName. |
from Extensible |
| protected | callable[][] | $afterExtendCallbacks | List of callbacks to call after extensions having extend called on them, each grouped by methodName. |
from Extensible |
| protected static | array | $whitelist_array | To use, call from _config.php Example: |
from Database |
| protected | DBConnector | $connector | Database connector object |
from Database |
| protected | int | $queryCount | Amount of queries executed, for debugging purposes. |
from Database |
| protected | DBSchemaManager | $schemaManager | Database schema manager object |
from Database |
| protected | DBQueryBuilder | $queryBuilder | Query builder object |
from Database |
Methods
Attempts to locate and call a method dynamically added to a class at runtime if a default cannot be located
Adds any methods from Extension instances attached to this object.
Register an callback to invoke that defines extra methods
Return TRUE if a method exists on this object
Determines if a custom method with this name is defined.
Get meta-data details on a named method
Return the names of all the methods available on this object
Get all public built in methods for this class
Find all methods on the given object.
Add all the methods from an object property.
Add all the methods from an object property (which is an Extension) to this object.
Add a wrapper method - a method which points to another method with a different name. For example, Thumbnail(x) can be wrapped to generateThumbnail(x)
Add callback as a method.
Allows user code to hook into Object::extend prior to control being delegated to extensions. Each callback will be reset once called.
Allows user code to hook into Object::extend after control being delegated to extensions. Each callback will be reset once called.
Adds any methods from Extension instances attached to this object.
Add an extension to a specific class.
No description
Get extra config sources for this class
Return TRUE if a class has a specified extension.
Calls a method if available on both this object and all applied Extensions, and then attempts to merge all results into an array
Run the given function on all of this object's extensions. Note that this method originally returned void, so if you wanted to return results, you're hosed
Get an extension instance attached to this object by name.
Returns TRUE if this object instance has a specific extension applied in $extension_instances. Extension instances are initialized at constructor time, meaning if you use add_extension() afterwards, the added extension will just be added to new instances of the extended class. Use the static method has_extension() to check if a class (not an instance) has a specific extension.
Get all extension instances for this specific object instance.
Execute the given SQL parameterised query with the specified arguments
Determines if the query should be previewed, and thus interrupted silently.
Allows the display and benchmarking of queries as they are being run
Add the sql queries that need to be partially or fully matched
Get the sql queries that need to be partially or fully matched
Get the autogenerated ID from the previous INSERT query.
Determines if we are connected to a server AND have a valid database selected.
Returns an escaped string. This string won't be quoted, so would be suitable for appending to other quoted strings.
Escapes an identifier (table / database name). Typically the value is simply double quoted. Don't pass in already escaped identifiers in, as this will double escape the value!
Escapes unquoted columns keys in an associative array
Execute a complex manipulation on the database.
Generates a WHERE clause for null comparison check
Generate a WHERE clause for text matching.
function to return an SQL datetime expression that can be used with the adapter in use used for querying a datetime in a certain format
function to return an SQL datetime expression that can be used with the adapter in use used for querying a datetime addition
function to return an SQL datetime expression that can be used with the adapter in use used for querying a datetime subtraction
Can the database override timezone as a connection setting, or does it use the system timezone exclusively?
Return the number of rows affected by the previous operation.
The core search engine, used by this class and its subclasses to do fun stuff.
Determines if this database supports Common Table Expression (aka WITH) clauses.
Does this database support savepoints in transactions By default it is assumed that they don't unless they are explicitly enabled.
Determines if the used database supports given transactionMode as an argument to startTransaction() If transactions are completely unsupported, returns false.
Invoke $callback within a transaction
Start a prepared transaction See http://developer.postgresql.org/pgdocs/postgres/sql-set-transaction.html for details on transaction isolation options
Create a savepoint that you can jump back to if you encounter problems
Rollback or revert to a savepoint if your queries encounter problems If you encounter a problem at any point during a transaction, you may need to rollback that particular query, or return to a savepoint
Determines if the used database supports application-level locks, which is different from table- or row-level locking.
Sets an application-level lock so that no two processes can run at the same time, also called a "cooperative advisory lock".
Remove an application-level lock file to allow another process to run (if the execution aborts (e.g. due to an error) all locks are automatically released).
Determine if the database with the specified name exists
Retrieves the list of all databases the user has access to
Change the connection to the specified database, optionally creating the database if it doesn't exist in the current schema.
Drop the database that this object is currently connected to.
Returns the name of the currently selected database
Generate SQL for sorting by a specific field using MySQL's FIELD function.
Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).
Gets the uninherited value for the given config option
Returns the TransactionManager to handle transactions for this database.
Details
mixed
__call(string $method, array $arguments)
Attempts to locate and call a method dynamically added to a class at runtime if a default cannot be located
You can add extra methods to a class using Extensions}, {@link Object::createMethod() or Object::addWrapperMethod()
protected
defineMethods()
Adds any methods from Extension instances attached to this object.
All these methods can then be called directly on the instance (transparently mapped through __call()}), or called explicitly through {@link extend().
protected
registerExtraMethodCallback(string $name, callable $callback)
Register an callback to invoke that defines extra methods
bool
hasMethod(string $method)
Return TRUE if a method exists on this object
This should be used rather than PHP's inbuild method_exists() as it takes into account methods added via extensions
protected bool
hasCustomMethod($method)
Determines if a custom method with this name is defined.
protected array
getExtraMethodConfig(string $method)
Get meta-data details on a named method
array
allMethodNames(bool $custom = false)
Return the names of all the methods available on this object
static protected array
findBuiltInMethods(string|object $class = null)
Get all public built in methods for this class
protected array
findMethodsFrom(object $object)
Find all methods on the given object.
protected
addMethodsFrom(string $property, string|int $index = null)
Add all the methods from an object property.
protected
removeMethodsFrom(string $property, string|int $index = null)
Add all the methods from an object property (which is an Extension) to this object.
protected
addWrapperMethod(string $method, string $wrap)
Add a wrapper method - a method which points to another method with a different name. For example, Thumbnail(x) can be wrapped to generateThumbnail(x)
protected
addCallbackMethod(string $method, callable $callback)
Add callback as a method.
protected
beforeExtending(string $method, callable $callback)
Allows user code to hook into Object::extend prior to control being delegated to extensions. Each callback will be reset once called.
protected
afterExtending(string $method, callable $callback)
Allows user code to hook into Object::extend after control being delegated to extensions. Each callback will be reset once called.
protected
defineExtensionMethods()
Adds any methods from Extension instances attached to this object.
All these methods can then be called directly on the instance (transparently mapped through __call()}), or called explicitly through {@link extend().
static bool
add_extension(string $classOrExtension, string $extension = null)
Add an extension to a specific class.
The preferred method for adding extensions is through YAML config, since it avoids autoloading the class, and is easier to override in more specific configurations.
As an alternative, extensions can be added to a specific class directly in the Object::$extensions array. See SiteTree::$extensions for examples. Keep in mind that the extension will only be applied to new instances, not existing ones (including all instances created through singleton()).
static
remove_extension(string $extension)
Remove an extension from a class.
Note: This will not remove extensions from parent classes, and must be called directly on the class assigned the extension.
Keep in mind that this won't revert any datamodel additions of the extension at runtime, unless its used before the schema building kicks in (in your _config.php). Doesn't remove the extension from any Object instances which are already created, but will have an effect on new extensions. Clears any previously created singletons through singleton() to avoid side-effects from stale extension information.
static array
get_extensions(string $class = null, bool $includeArgumentString = false)
No description
static array|null
get_extra_config_sources(string $class = null)
Get extra config sources for this class
static bool
has_extension(string $classOrExtension, string $requiredExtension = null, bool $strict = false)
Return TRUE if a class has a specified extension.
This supports backwards-compatible format (static Object::has_extension($requiredExtension)) and new format ($object->has_extension($class, $requiredExtension))
array
invokeWithExtensions(string $method, mixed ...$arguments)
Calls a method if available on both this object and all applied Extensions, and then attempts to merge all results into an array
array
extend(string $method, mixed ...$arguments)
Run the given function on all of this object's extensions. Note that this method originally returned void, so if you wanted to return results, you're hosed
Currently returns an array, with an index resulting every time the function is called. Only adds returns if they're not NULL, to avoid bogus results from methods just defined on the parent extension. This is important for permission-checks through extend, as they use min() to determine if any of the returns is FALSE. As min() doesn't do type checking, an included NULL return would fail the permission checks.
The extension methods are defined during __construct()} in {@link defineMethods().
Extension|null
getExtensionInstance(string $extension)
Get an extension instance attached to this object by name.
bool
hasExtension(string $extension)
Returns TRUE if this object instance has a specific extension applied in $extension_instances. Extension instances are initialized at constructor time, meaning if you use add_extension() afterwards, the added extension will just be added to new instances of the extended class. Use the static method has_extension() to check if a class (not an instance) has a specific extension.
Caution: Don't use singleton(
Extension[]
getExtensionInstances()
Get all extension instances for this specific object instance.
See get_extensions() to get all applied extension classes for this class (not the instance).
This method also provides lazy-population of the extension_instances property.
DBConnector
getConnector()
Get the current connector
setConnector(DBConnector $connector)
Injector injection point for connector dependency
DBSchemaManager
getSchemaManager()
Returns the current schema manager
setSchemaManager(DBSchemaManager $schemaManager)
Injector injection point for schema manager
DBQueryBuilder
getQueryBuilder()
Returns the current query builder
setQueryBuilder(DBQueryBuilder $queryBuilder)
Injector injection point for schema manager
Query
query(string $sql, int $errorLevel = E_USER_ERROR)
Execute the given SQL query.
Query
preparedQuery(string $sql, array $parameters, int $errorLevel = E_USER_ERROR)
Execute the given SQL parameterised query with the specified arguments
protected bool
previewWrite(string $sql)
Determines if the query should be previewed, and thus interrupted silently.
If so, this function also displays the query via the debugging system. Subclasess should respect the results of this call for each query, and not execute any queries that generate a true response.
protected mixed
benchmarkQuery(string $sql, callable $callback, array $parameters = [])
Allows the display and benchmarking of queries as they are being run
protected
displayQuery(mixed $query, float $endtime)
Display query message
static
setWhitelistQueryArray(array $whitelistArray)
Add the sql queries that need to be partially or fully matched
static array
getWhitelistQueryArray()
Get the sql queries that need to be partially or fully matched
int
getGeneratedID(string $table)
Get the autogenerated ID from the previous INSERT query.
bool
isActive()
Determines if we are connected to a server AND have a valid database selected.
string
escapeString(mixed $value)
Returns an escaped string. This string won't be quoted, so would be suitable for appending to other quoted strings.
string
quoteString(mixed $value)
Wrap a string into DB-specific quotes.
string
escapeIdentifier(string|array $value, string $separator = '.')
Escapes an identifier (table / database name). Typically the value is simply double quoted. Don't pass in already escaped identifiers in, as this will double escape the value!
protected array
escapeColumnKeys(array $fieldValues)
Escapes unquoted columns keys in an associative array
manipulate(array $manipulation)
Execute a complex manipulation on the database.
A manipulation is an array of insert / or update sequences. The keys of the array are table names, and the values are map containing 'command' and 'fields'. Command should be 'insert' or 'update', and fields should be a map of field names to field values, NOT including quotes.
The field values could also be in paramaterised format, such as array('MAX(?,?)' => array(42, 69)), allowing the use of raw SQL values such as array('NOW()' => array()).
quiet()
Enable suppression of database messages.
clearAllData()
Clear all data out of the database
clearTable(string $table)
Clear all data in a given table
string
nullCheckClause(string $field, bool $isNull)
Generates a WHERE clause for null comparison check
string
comparisonClause(string $field, string $value, bool $exact = false, bool $negate = false, bool $caseSensitive = null, bool $parameterised = false)
Generate a WHERE clause for text matching.
string
formattedDatetimeClause(string $date, string $format)
function to return an SQL datetime expression that can be used with the adapter in use used for querying a datetime in a certain format
string
datetimeIntervalClause(string $date, string $interval)
function to return an SQL datetime expression that can be used with the adapter in use used for querying a datetime addition
string
datetimeDifferenceClause(string $date1, string $date2)
function to return an SQL datetime expression that can be used with the adapter in use used for querying a datetime subtraction
string
concatOperator()
String operator for concatenation of strings
bool
supportsCollations()
Returns true if this database supports collations
bool
supportsTimezoneOverride()
Can the database override timezone as a connection setting, or does it use the system timezone exclusively?
string
getVersion()
Query for the version of the currently connected database
string
getDatabaseServer()
Get the database server type (e.g. mysql, postgresql).
This value is passed to the connector as the 'driver' argument when initiating a database connection
int
affectedRows()
Return the number of rows affected by the previous operation.
PaginatedList
searchEngine(array $classesToSearch, string $keywords, int $start, int $pageLength, string $sortBy = "Relevance DESC", string $extraFilter = "", bool $booleanSearch = false, string $alternativeFileFilter = "", bool $invertedMatch = false)
The core search engine, used by this class and its subclasses to do fun stuff.
Searches both SiteTree and File.
Caution: While the $keywords argument is escaped for safe use in a query context, you need to ensure that it is also a valid boolean expression when opting into $booleanSearch. For example, the "asterisk" and "greater than" characters have a special meaning in this context, and can only be placed in certain parts of the keywords. You will need to preprocess and sanitise user input accordingly in order to avoid query errors.
bool
supportsCteQueries(bool $recursive = false)
Determines if this database supports Common Table Expression (aka WITH) clauses.
By default it is assumed that it doesn't unless this method is explicitly overridden.
bool
supportsTransactions()
Determines if this database supports transactions
bool
supportsSavepoints()
Does this database support savepoints in transactions By default it is assumed that they don't unless they are explicitly enabled.
bool
supportsTransactionMode(string $mode)
Determines if the used database supports given transactionMode as an argument to startTransaction() If transactions are completely unsupported, returns false.
withTransaction(callable $callback, callable $errorCallback = null, bool|string $transactionMode = false, bool $errorIfTransactionsUnsupported = false)
Invoke $callback within a transaction
supportsExtensions($extensions)
No description
transactionStart(string|bool $transactionMode = false, string|bool $sessionCharacteristics = false)
Start a prepared transaction See http://developer.postgresql.org/pgdocs/postgres/sql-set-transaction.html for details on transaction isolation options
transactionSavepoint(string $savepoint)
Create a savepoint that you can jump back to if you encounter problems
bool|null
transactionRollback(string|bool $savepoint = false)
Rollback or revert to a savepoint if your queries encounter problems If you encounter a problem at any point during a transaction, you may need to rollback that particular query, or return to a savepoint
bool|null
transactionEnd()
Commit everything inside this transaction so far
Boolean is returned if success state is known, or null if unknown. Note: For error checking purposes null should not be treated as error.
int
transactionDepth()
Return depth of current transaction
bool
supportsLocks()
Determines if the used database supports application-level locks, which is different from table- or row-level locking.
See getLock() for details.
bool
canLock(string $name)
Returns if the lock is available.
See supportsLocks() to check if locking is generally supported.
bool
getLock(string $name, int $timeout = 5)
Sets an application-level lock so that no two processes can run at the same time, also called a "cooperative advisory lock".
Return FALSE if acquiring the lock fails; otherwise return TRUE, if lock was acquired successfully. Lock is automatically released if connection to the database is broken (either normally or abnormally), making it less prone to deadlocks than session- or file-based locks. Should be accompanied by a releaseLock() call after the logic requiring the lock has completed. Can be called multiple times, in which case locks "stack" (PostgreSQL, SQL Server), or auto-releases the previous lock (MySQL).
Note that this might trigger the database to wait for the lock to be released, delaying further execution.
bool
releaseLock(string $name)
Remove an application-level lock file to allow another process to run (if the execution aborts (e.g. due to an error) all locks are automatically released).
connect(array $parameters)
Instruct the database to generate a live connection
bool
databaseExists(string $name)
Determine if the database with the specified name exists
array
databaseList()
Retrieves the list of all databases the user has access to
bool
selectDatabase(string $name, bool $create = false, int|bool $errorLevel = E_USER_ERROR)
Change the connection to the specified database, optionally creating the database if it doesn't exist in the current schema.
dropSelectedDatabase()
Drop the database that this object is currently connected to.
Use with caution.
string|null
getSelectedDatabase()
Returns the name of the currently selected database
string
now()
Return SQL expression used to represent the current date/time
string
random()
Returns the database-specific version of the random() function
string
sortByField(string $field, array $values)
Generate SQL for sorting by a specific field using MySQL's FIELD function.
static Config_ForClass
config()
Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).
mixed
uninherited(string $name)
Gets the uninherited value for the given config option
setSQLMode(string $mode)
Sets the SQL mode
selectTimezone(string $timezone)
Sets the system timezone for the database connection
protected TransactionManager
getTransactionManager()
Returns the TransactionManager to handle transactions for this database.
protected
resetTransactionNesting()
In error condition, set transactionNesting to zero
protected
inspectQuery(string $sql)
Inspect a SQL query prior to execution
protected
getLockIdentifier($name)
No description