aliroAbstractDatabase

Mambo family methods

Most methods that require table names expect them to use the standard symbolic prefix of #__ that is automatically translated to the actual database prefix. There are a number of exceptions to this, which are noted in the relevant methods.

int = getErrorNum()

Returns the error number for the most recent SQL operation. Note that most errors will cause a database exception, so applications must trap this exception if they will to do their own error processing.

string = getErrorMsg()

Returns the error message for the most recent SQL operation. Note that most errors will cause a database exception, so applications must trap this exception if they will to do their own error processing.

string = getEscaped($text)

Helper method (in the sense of not being directly tied to the database object) that returns a string with escaping to make it suitable for writing to a database table.

null = setQuery( $sql, $cached=false, $prefix='#__' )

Stores a SQL statement, given in the first parameter. The second parameter is provided for backwards compatibility, and is stored in case a derived class wishes to use it. However, the abstract class does nothing with it on the grounds that a cache directly on database operations makes little sense given that the database already has its own efficient query cache. Normally, the SQL statement will be assumed to have table names prefixed with #__ and this will be replaced with the actual table prefix before the statement is stored. It is possible, by setting the third parameter, to use an alternative symbol for the prefix.

string = replacePrefix ($sql, $prefix='#__')

Takes a SQL statement and substitutes the database prefix for any occurrence of #__ that is not within quotes. The standard #__ can have an alternative value by providing the second parameter. This method is not normally needed outside the class.

string = getQuery ($sql=null)

If no parameter is provided, then the last SQL submitted to the database object will be used. The stored or provided SQL is returned wrapped in HTML ready for display to a browser.

cursor = query ($sql=null)

If no parameter is provided, then the last SQL submitted to the database object will be used. The stored or provided SQL is submitted to the database system for processing. If the operation is successful, then a cursor is both retained in the object and also returned. NOTE: Aliro will not give an error return, but will raise an exception if there is an error during SQL processing. An application can trap this if required, or it will be dealt with by Aliro's default error handling.

null = query_batch()

This instigates processing of a previously submitted batch of SQL queries, using the setQuery() method. Unlike other CMS versions, the Aliro version does not expect any parameters. This is not a particularly developed method, and is used primarily for Aliro installation, when a number of tables are created and some data inserted.

int = getNumRows ($cur=null)

Returns the number of rows that were returned for the SELECT query referred to by the supplied cursor. If no parameter is given, then the last cursor is used - this is the normal usage of the method.

int = getAffectedRows ()

Returns the number of rows affected by the preceding DELETE or UPDATE operation. Note that "affected" is treated quite literally. If an UPDATE matches a row but does not actually change any values, it will not be included in the count of affected rows.

mixed = loadResult()

Returns the first item from the first row resulting from a SELECT query. This may be the only item returned, depending on the SELECT statement. If the SELECT does not produce any rows, then the result will be a PHP null.

array = loadResultArray($numinarray=0)

Returns the specified item from each row resulting from a SELECT query. By default the first item from each row is returned, but the parameter can be used to obtain a different item. If the SELECT does not produce any rows, then the result will be a PHP null. This is not ideal, as it would be better to receive back an empty array. However, it is retained for backwards compatibility with earlier Mambo family systems.

array = loadAssocList( $key=null )

Returns a result set from a SELECT query as associative arrays that have the field names as array keys and the field values as array values. If a key is specified and refers to one of the fields in the result set, the return values will be keyed by the values of the key field. Otherwise, the return values will have numeric subscripts. If the SELECT does not produce any rows, then the result will be a PHP null. This is not ideal, as it would be better to receive back an empty array. However, it is retained for backwards compatibility with earlier Mambo family systems.

mixed = loadObjectList($key=null)

Returns a result set from a SELECT query as an array of objects, or if no rows result from the query, a PHP null is returned. If a key name is provided as the parameter, then the array will be keyed by the values of the key field. Otherwise, the subscripts will be numeric. A more powerful method is provided in Aliro, called doSQLget().

loadRow()

I'm not sure what this does

loadRowList

Nor this one, without studying what happens, have never used it

bool = insertObject ($table, $object, $keyName=NULL)

This method will insert an object into a table on the assumption that the names of the object properties correspond to field names in the table. The table name is provided as the first parameter, and may use the standard symbolic prefix of #__ to be substituted with the actual prefix for the database. If the third parameter is provided and the table uses autoincrement, then the object's property identified by "keyName" is set to the new row's autoincremented key. The result indicates whether there was any logical failure in the method. A failure of the database operation will cause an exception, as usual. A final "verbose" parameter was offered in Mambo, but is not supported in Aliro and therefore will be ignored if present.

bool = updateObject ($table, $object, $keyName, $updateNulls=true)

Uses the supplied object to update a row in the specified table. The table name may use the symbolic prefix #__ to be substituted with the actual datbase prefix, as with most database methods. The key name must be given and must correspond to a property of the object whose value is used to specify the row to be updated. The final, optional parameter indicates whether object properties that are null will be used to update the database or whether they will be ignored. Even if nulls in the object are used for the update, they do not enter actual NULL into the database, simply set the field using a zero length string.

int = insertid()

Used after an insert operation into a table that is keyed using an auto-increment integer. The new key is returned.

string = getVersion()

Returns the version of the database system, currently MySQL.

array = getTableList()

Returns an array of table names, including all the tables in the database. These are the actual names, and has usually been used to check for the existence of a particular table. This operation is much more easily achieved by using the Aliro tableExists() method which expects a table name with the standard symbolic prefix of #__ thus avoiding the need to find out the actual database prefix. The Aliro method is also more efficient, as it takes advantage of cached data rather than going to the database.

array = getTableCreate($tablenames)

Given an array of actual table names (not using #__ but the actual prefix), this method returns an array of SQL statements, each of which creates one of the specified tables.

array = getTableFields($tablenames)

Returns an array with one entry for each of the names in the supplied array of table names. Each entry in the returned array is an array of field information. The table names must be actual names. Generally, there are Aliro methods that will be more useful, both because they work on the #__ prefixed table names and also because they cache database information.

Aliro methods

All Aliro methods that take table names as parameters expect the symbolic prefix of #__ to be used. Where necessary, this will be automatically converted to the actual database prefix. There should be no need for an application to find out what the database prefix actually is.

string = getName()

Returns the name of this database.

array = getAllFieldInfo ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The return value is an array containing the results of SQL "SHOW FIELDS FROM ...". If the table name given is invalid, the array will have zero elements.

array = getAllFieldNames ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The return value is an array containing the fields that exist within the table. If the tablename is invalid, the array will have zero elements.

bool = addFieldIfMissing ($tablename, $fieldname, $fieldspec, $alterIfPresent=false)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field that may be added. The third parameter is a SQL field specification that will be used if the field is added. If the boolean fourth parameter is given as true, then if the field is already present, the field specification will be used in a SQL ALTER TABLE statement. Note that with the boolean set to false, the cost of this operation is very low in case the field already exists, because information about tables is cached. But if it is true, then the method will always cause one SQL operation. The return value is true if the field was added, or false if it was already present.

bool = function dropFieldIfPresent ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field that may be dropped. The return value is a boolean indicating whether the field was dropped.

bool = alterField ($tablename, $fieldname, $fieldspec)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field that may be altered. The third parameter is a SQL field specification that will be used if the field is altered. The return value is a boolean that will be false if there is no such field, and true if there is. In the latter case, the specified field will have been altered.

string = getFieldInfo ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field whose information is wanted. The return value will be the information for the field obtained from SQL "SHOW FIELDS FROM ..." if the table and field exist, otherwise null.

string = setFieldValue ($value)

This is a helper method (in the sense that it does not do anything that is specific to the database object) that processes a value and returns a string that can be used to to set the value in a SQL statement. If the parameter is non-numeric, it will be escaped. If it is integer, it will not be enclosed in quotes; in all other cases it will.

bool = tableExists ($tablename)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. If the table exists the return value is true, otherwise false.

string = restoreOnePrefix ($tablename)

This method is mainly for internal use, but might be helpful for an application. It takes a table name that is expected to have the standard database prefix (e.g. aliro_) at its start. If this is found, then the standard symbolic prefix of #__ is put in its place. Otherwise the table name is left unaltered. The result is returned.

cursor = doSQL ($sql)

The provided SQL is stored in the database object, and submitted to the database system for processing. This method combines setQuery() and query() into a single operation that is useful for INSERT, UPDATE and DELETE operations. NOTE: Aliro will not give an error return, but will raise an exception if there is an error during SQL processing. An application can trap this if required, or it will be dealt with by Aliro's default error handling.

array = doSQLget ($sql, $classname='stdClass', $key=null, $max=0)

The provided SQL is stored in the database object, and submitted to the database system for processing. It is assumed to be a SELECT statement. An array of database rows is returned (which may contain zero elements). If the second parameter is supplied, then it determines the class that will be created for each row. If the name of the key is given as the third parameter, then the array that is returned will have the key values as its keys instead of having sequential numeric values as its keys. If the fourth parameter is given a positive value, then only the first so many results will be included in the returned array. NOTE: Aliro will not give an error return, but will raise an exception if there is an error during SQL processing. An application can trap this if required, or it will be dealt with by Aliro's default error handling.

int = getCount()

Returns a count of the number of queries that have been processed in the current request. Primarily intended for use by Aliro, but generally available.

string = getLogged()

Returns an HTML format string showing all the queries that have been run in the current request. Again, primarily intended for Aliro use, but generally available.

string = getQuery ($sql=)

cursor = query ($sql=)

array = loadAssocList( $key= )

mixed = loadObjectList($key=)

array = doSQLget ($sql, $classname='stdClass', $key=, $max=0)

array = doSQLget ($sql, $classname='stdClass', $key=, $max=0)

Most methods that require table names expect them to use the standard symbolic prefix of #"" that is automatically translated to the actual database prefix. There are a number of exceptions to this, which are noted in the relevant methods.

null = setQuery( $sql, $cached=false, $prefix='#""' )

Stores a SQL statement, given in the first parameter. The second parameter is provided for backwards compatibility, and is stored in case a derived class wishes to use it. However, the abstract class does nothing with it on the grounds that a cache directly on database operations makes little sense given that the database already has its own efficient query cache. Normally, the SQL statement will be assumed to have table names prefixed with #"" and this will be replaced with the actual table prefix before the statement is stored. It is possible, by setting the third parameter, to use an alternative symbol for the prefix.

string = replacePrefix ($sql, $prefix='#""')

Takes a SQL statement and substitutes the database prefix for any occurrence of #"" that is not within quotes. The standard #"" can have an alternative value by providing the second parameter. This method is not normally needed outside the class.
This method will insert an object into a table on the assumption that the names of the object properties correspond to field names in the table. The table name is provided as the first parameter, and may use the standard symbolic prefix of #"" to be substituted with the actual prefix for the database. If the third parameter is provided and the table uses autoincrement, then the object's property identified by "keyName" is set to the new row's autoincremented key. The result indicates whether there was any logical failure in the method. A failure of the database operation will cause an exception, as usual. A final "verbose" parameter was offered in Mambo, but is not supported in Aliro and therefore will be ignored if present.
Uses the supplied object to update a row in the specified table. The table name may use the symbolic prefix #"" to be substituted with the actual datbase prefix, as with most database methods. The key name must be given and must correspond to a property of the object whose value is used to specify the row to be updated. The final, optional parameter indicates whether object properties that are null will be used to update the database or whether they will be ignored. Even if nulls in the object are used for the update, they do not enter actual NULL into the database, simply set the field using a zero length string.
Returns an array of table names, including all the tables in the database. These are the actual names, and has usually been used to check for the existence of a particular table. This operation is much more easily achieved by using the Aliro tableExists() method which expects a table name with the standard symbolic prefix of #"" thus avoiding the need to find out the actual database prefix. The Aliro method is also more efficient, as it takes advantage of cached data rather than going to the database.
Given an array of actual table names (not using #"" but the actual prefix), this method returns an array of SQL statements, each of which creates one of the specified tables.
Returns an array with one entry for each of the names in the supplied array of table names. Each entry in the returned array is an array of field information. The table names must be actual names. Generally, there are Aliro methods that will be more useful, both because they work on the #"" prefixed table names and also because they cache database information.
All Aliro methods that take table names as parameters expect the symbolic prefix of #"" to be used. Where necessary, this will be automatically converted to the actual database prefix. There should be no need for an application to find out what the database prefix actually is.
Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #""simple_text. The return value is an array containing the results of SQL "SHOW FIELDS FROM ...". If the table name given is invalid, the array will have zero elements.
Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #""simple_text. The return value is an array containing the fields that exist within the table. If the tablename is invalid, the array will have zero elements.
Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #""simple_text. The second parameter is the name of the field that may be added. The third parameter is a SQL field specification that will be used if the field is added. If the boolean fourth parameter is given as true, then if the field is already present, the field specification will be used in a SQL ALTER TABLE statement. Note that with the boolean set to false, the cost of this operation is very low in case the field already exists, because information about tables is cached. But if it is true, then the method will always cause one SQL operation. The return value is true if the field was added, or false if it was already present.
Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #""simple_text. The second parameter is the name of the field that may be dropped. The return value is a boolean indicating whether the field was dropped.
Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #""simple_text. The second parameter is the name of the field that may be altered. The third parameter is a SQL field specification that will be used if the field is altered. The return value is a boolean that will be false if there is no such field, and true if there is. In the latter case, the specified field will have been altered.
Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #""simple_text. The second parameter is the name of the field whose information is wanted. The return value will be the information for the field obtained from SQL "SHOW FIELDS FROM ..." if the table and field exist, otherwise null.
Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #""simple_text. If the table exists the return value is true, otherwise false.
This method is mainly for internal use, but might be helpful for an application. It takes a table name that is expected to have the standard database prefix (e.g. aliro_) at its start. If this is found, then the standard symbolic prefix of #"" is put in its place. Otherwise the table name is left unaltered. The result is returned.

aliroAbstractDatabase

Mambo family methods

Most methods that require table names expect them to use the standard symbolic prefix of #__ that is automatically translated to the actual database prefix. There are a number of exceptions to this, which are noted in the relevant methods.

int = getErrorNum()

string = getErrorMsg()

string = getEscaped($text)

null = setQuery( $sql, $cached=false, $prefix='#__' )

Stores a SQL statement, given in the first parameter. The second parameter is provided for backwards compatibility, and is stored in case a derived class wishes to use it. However, the abstract class does nothing with it on the grounds that a cache directly on database operations makes little sense given that the database already has its own efficient query cache. Normally, the SQL statement will be assumed to have table names prefixed with #__ and this will be replaced with the actual table prefix before the statement is stored. It is possible, by setting the third parameter, to use an alternative symbol for the prefix.

string = replacePrefix ($sql, $prefix='#__')

Takes a SQL statement and substitutes the database prefix for any occurrence of #__ that is not within quotes. The standard #__ can have an alternative value by providing the second parameter. This method is not normally needed outside the class.

string = getQuery ($sql=)

cursor = query ($sql=)

null = query_batch()

int = getNumRows ($cur=null)

int = getAffectedRows ()

mixed = loadResult()

array = loadResultArray($numinarray=0)

array = loadAssocList( $key= )

mixed = loadObjectList($key=)

loadRow()

loadRowList

bool = insertObject ($table, $object, $keyName=NULL)

This method will insert an object into a table on the assumption that the names of the object properties correspond to field names in the table. The table name is provided as the first parameter, and may use the standard symbolic prefix of #__ to be substituted with the actual prefix for the database. If the third parameter is provided and the table uses autoincrement, then the object's property identified by "keyName" is set to the new row's autoincremented key. The result indicates whether there was any logical failure in the method. A failure of the database operation will cause an exception, as usual. A final "verbose" parameter was offered in Mambo, but is not supported in Aliro and therefore will be ignored if present.

bool = updateObject ($table, $object, $keyName, $updateNulls=true)

Uses the supplied object to update a row in the specified table. The table name may use the symbolic prefix #__ to be substituted with the actual datbase prefix, as with most database methods. The key name must be given and must correspond to a property of the object whose value is used to specify the row to be updated. The final, optional parameter indicates whether object properties that are null will be used to update the database or whether they will be ignored. Even if nulls in the object are used for the update, they do not enter actual NULL into the database, simply set the field using a zero length string.

int = insertid()

string = getVersion()

Returns the version of the database system, currently MySQL.

array = getTableList()

Returns an array of table names, including all the tables in the database. These are the actual names, and has usually been used to check for the existence of a particular table. This operation is much more easily achieved by using the Aliro tableExists() method which expects a table name with the standard symbolic prefix of #__ thus avoiding the need to find out the actual database prefix. The Aliro method is also more efficient, as it takes advantage of cached data rather than going to the database.

array = getTableCreate($tablenames)

Given an array of actual table names (not using #__ but the actual prefix), this method returns an array of SQL statements, each of which creates one of the specified tables.

array = getTableFields($tablenames)

Returns an array with one entry for each of the names in the supplied array of table names. Each entry in the returned array is an array of field information. The table names must be actual names. Generally, there are Aliro methods that will be more useful, both because they work on the #__ prefixed table names and also because they cache database information.

Aliro methods

All Aliro methods that take table names as parameters expect the symbolic prefix of #__ to be used. Where necessary, this will be automatically converted to the actual database prefix. There should be no need for an application to find out what the database prefix actually is.

string = getName()

array = getAllFieldInfo ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The return value is an array containing the results of SQL "SHOW FIELDS FROM ...". If the table name given is invalid, the array will have zero elements.

array = getAllFieldNames ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The return value is an array containing the fields that exist within the table. If the tablename is invalid, the array will have zero elements.

bool = addFieldIfMissing ($tablename, $fieldname, $fieldspec, $alterIfPresent=false)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field that may be added. The third parameter is a SQL field specification that will be used if the field is added. If the boolean fourth parameter is given as true, then if the field is already present, the field specification will be used in a SQL ALTER TABLE statement. Note that with the boolean set to false, the cost of this operation is very low in case the field already exists, because information about tables is cached. But if it is true, then the method will always cause one SQL operation. The return value is true if the field was added, or false if it was already present.

bool = function dropFieldIfPresent ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field that may be dropped. The return value is a boolean indicating whether the field was dropped.

bool = alterField ($tablename, $fieldname, $fieldspec)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field that may be altered. The third parameter is a SQL field specification that will be used if the field is altered. The return value is a boolean that will be false if there is no such field, and true if there is. In the latter case, the specified field will have been altered.

string = getFieldInfo ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. The second parameter is the name of the field whose information is wanted. The return value will be the information for the field obtained from SQL "SHOW FIELDS FROM ..." if the table and field exist, otherwise null.

string = setFieldValue ($value)

bool = tableExists ($tablename)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #__simple_text. If the table exists the return value is true, otherwise false.

string = restoreOnePrefix ($tablename)

This method is mainly for internal use, but might be helpful for an application. It takes a table name that is expected to have the standard database prefix (e.g. aliro_) at its start. If this is found, then the standard symbolic prefix of #__ is put in its place. Otherwise the table name is left unaltered. The result is returned.

cursor = doSQL ($sql)

array = doSQLget ($sql, $classname='stdClass', $key=, $max=0)

int = getCount()

string = getLogged()

Returns the version of the database system, currently MySQL.

<nowiki>string = getQuery ($sql=)</nowiki>

<nowiki>cursor = query ($sql=)</nowiki>

<nowiki>array = loadAssocList( $key= )</nowiki>

<nowiki>mixed = loadObjectList($key=)</nowiki>

<nowiki>array = doSQLget ($sql, $classname='stdClass', $key=, $max=0)</nowiki>

Most methods that require table names expect them to use the standard symbolic prefix of # that is automatically translated to the actual database prefix. There are a number of exceptions to this, which are noted in the relevant methods.

aliroAbstractDatabase

Mambo family methods

Most methods that require table names expect them to use the standard symbolic prefix of # that is automatically translated to the actual database prefix. There are a number of exceptions to this, which are noted in the relevant methods.

int = getErrorNum()

string = getErrorMsg()

string = getEscaped($text)

null = setQuery( $sql, $cached=false, $prefix='#' )

Stores a SQL statement, given in the first parameter. The second parameter is provided for backwards compatibility, and is stored in case a derived class wishes to use it. However, the abstract class does nothing with it on the grounds that a cache directly on database operations makes little sense given that the database already has its own efficient query cache. Normally, the SQL statement will be assumed to have table names prefixed with # and this will be replaced with the actual table prefix before the statement is stored. It is possible, by setting the third parameter, to use an alternative symbol for the prefix.

string = replacePrefix ($sql, $prefix='#')

Takes a SQL statement and substitutes the database prefix for any occurrence of # that is not within quotes. The standard # can have an alternative value by providing the second parameter. This method is not normally needed outside the class.

<nowiki>string = getQuery ($sql=)</nowiki>

<nowiki>cursor = query ($sql=)</nowiki>

null = query_batch()

int = getNumRows ($cur=null)

int = getAffectedRows ()

mixed = loadResult()

array = loadResultArray($numinarray=0)

<nowiki>array = loadAssocList( $key= )</nowiki>

<nowiki>mixed = loadObjectList($key=)</nowiki>

loadRow()

loadRowList

bool = insertObject ($table, $object, $keyName=NULL)

This method will insert an object into a table on the assumption that the names of the object properties correspond to field names in the table. The table name is provided as the first parameter, and may use the standard symbolic prefix of # to be substituted with the actual prefix for the database. If the third parameter is provided and the table uses autoincrement, then the object's property identified by "keyName" is set to the new row's autoincremented key. The result indicates whether there was any logical failure in the method. A failure of the database operation will cause an exception, as usual. A final "verbose" parameter was offered in Mambo, but is not supported in Aliro and therefore will be ignored if present.

bool = updateObject ($table, $object, $keyName, $updateNulls=true)

Uses the supplied object to update a row in the specified table. The table name may use the symbolic prefix # to be substituted with the actual datbase prefix, as with most database methods. The key name must be given and must correspond to a property of the object whose value is used to specify the row to be updated. The final, optional parameter indicates whether object properties that are null will be used to update the database or whether they will be ignored. Even if nulls in the object are used for the update, they do not enter actual NULL into the database, simply set the field using a zero length string.

int = insertid()

string = getVersion()

array = getTableList()

Returns an array of table names, including all the tables in the database. These are the actual names, and has usually been used to check for the existence of a particular table. This operation is much more easily achieved by using the Aliro tableExists() method which expects a table name with the standard symbolic prefix of # thus avoiding the need to find out the actual database prefix. The Aliro method is also more efficient, as it takes advantage of cached data rather than going to the database.

array = getTableCreate($tablenames)

Given an array of actual table names (not using # but the actual prefix), this method returns an array of SQL statements, each of which creates one of the specified tables.

array = getTableFields($tablenames)

Returns an array with one entry for each of the names in the supplied array of table names. Each entry in the returned array is an array of field information. The table names must be actual names. Generally, there are Aliro methods that will be more useful, both because they work on the # prefixed table names and also because they cache database information.

Aliro methods

All Aliro methods that take table names as parameters expect the symbolic prefix of # to be used. Where necessary, this will be automatically converted to the actual database prefix. There should be no need for an application to find out what the database prefix actually is.

string = getName()

array = getAllFieldInfo ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #simple_text. The return value is an array containing the results of SQL "SHOW FIELDS FROM ...". If the table name given is invalid, the array will have zero elements.

array = getAllFieldNames ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #simple_text. The return value is an array containing the fields that exist within the table. If the tablename is invalid, the array will have zero elements.

bool = addFieldIfMissing ($tablename, $fieldname, $fieldspec, $alterIfPresent=false)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #simple_text. The second parameter is the name of the field that may be added. The third parameter is a SQL field specification that will be used if the field is added. If the boolean fourth parameter is given as true, then if the field is already present, the field specification will be used in a SQL ALTER TABLE statement. Note that with the boolean set to false, the cost of this operation is very low in case the field already exists, because information about tables is cached. But if it is true, then the method will always cause one SQL operation. The return value is true if the field was added, or false if it was already present.

bool = function dropFieldIfPresent ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #simple_text. The second parameter is the name of the field that may be dropped. The return value is a boolean indicating whether the field was dropped.

bool = alterField ($tablename, $fieldname, $fieldspec)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #simple_text. The second parameter is the name of the field that may be altered. The third parameter is a SQL field specification that will be used if the field is altered. The return value is a boolean that will be false if there is no such field, and true if there is. In the latter case, the specified field will have been altered.

string = getFieldInfo ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #simple_text. The second parameter is the name of the field whose information is wanted. The return value will be the information for the field obtained from SQL "SHOW FIELDS FROM ..." if the table and field exist, otherwise null.

string = setFieldValue ($value)

bool = tableExists ($tablename)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #simple_text. If the table exists the return value is true, otherwise false.

string = restoreOnePrefix ($tablename)

This method is mainly for internal use, but might be helpful for an application. It takes a table name that is expected to have the standard database prefix (e.g. aliro_) at its start. If this is found, then the standard symbolic prefix of # is put in its place. Otherwise the table name is left unaltered. The result is returned.

cursor = doSQL ($sql)

<nowiki>array = doSQLget ($sql, $classname='stdClass', $key=, $max=0)</nowiki>

int = getCount()

string = getLogged()

aliroAbstractDatabase

=Mambo family methods

Most methods that require table names expect them to use the standard
symbolic prefix of # that is automatically translated to the actual
database prefix. There are a number of exceptions to this, which
are noted in the relevant methods.

int = getErrorNum()

Returns the error number for the most recent SQL operation. Note that
most errors will cause a database exception, so applications must trap
this exception if they will to do their own error processing.

string = getErrorMsg()

Returns the error message for the most recent SQL operation. Note that most errors will cause a database exception, so applications must trap this exception if they will to do their own error processing.

string = getEscaped($text)

Helper method (in the sense of not being directly tied to the database object)
that returns a string with escaping to make it suitable for writing to
a database table.

null = setQuery( $sql, $cached=false, $prefix='#' )

Stores a SQL statement, given in the first parameter. The second parameter is provided for backwards compatibility, and
is stored in case a derived class wishes to use it. However, the
abstract class does nothing with it on the grounds that a cache
directly on database operations makes little sense given that the
database already has its own efficient query cache. Normally, the
SQL statement will be assumed to have table names prefixed with # and
this will be replaced with the actual table prefix before the statement
is stored. It is possible, by setting the third parameter, to use
an alternative symbol for the prefix.

string = replacePrefix ($sql, $prefix='#')

Takes a SQL statement and substitutes the database prefix for any occurrence
of # that is not within quotes. The standard # can have an
alternative value by providing the second parameter. This method
is not normally needed outside the class.

string = getQuery ($sql=)

If no parameter is provided, then the last SQL submitted to the database
object will be used. The stored or provided SQL is returned
wrapped in HTML ready for display to a browser.

cursor = query ($sql=)

If no parameter is provided, then the last SQL submitted to the database
object will be used. The stored or provided SQL is submitted to
the database system for processing. If the operation is
successful, then a cursor is both retained in the object and also
returned. NOTE: Aliro will not give an error return, but will
raise an exception if there is an error during SQL processing. An
application can trap this if required, or it will be dealt with by
Aliro's default error handling.

null = query_batch()

This instigates processing of a previously submitted batch of SQL queries,
using the setQuery() method. Unlike other CMS versions, the Aliro
version does not expect any parameters. This is not a
particularly developed method, and is used primarily for Aliro
installation, when a number of tables are created and some data
inserted.

int = getNumRows ($cur=null)

Returns the number of rows that were returned for the SELECT query referred to by the
supplied cursor. If no parameter is given, then the last cursor
is used - this is the normal usage of the method.

int = getAffectedRows ()

Returns the number of rows affected by the preceding DELETE or UPDATE
operation. Note that "affected" is treated quite literally.
If an UPDATE matches a row but does not actually change any
values, it will not be included in the count of affected rows.

mixed = loadResult()

Returns the first item from the first row resulting from a SELECT query.
This may be the only item returned, depending on the SELECT
statement. If the SELECT does not produce any rows, then the
result will be a PHP null.

array = loadResultArray($numinarray=0)

Returns the specified item from each row resulting from a SELECT query.
By default the first item from each row is returned, but the
parameter can be used to obtain a different item. If the SELECT
does not produce any rows, then the result will be a PHP null.
This is not ideal, as it would be better to receive back an empty
array. However, it is retained for backwards compatibility with
earlier Mambo family systems.

array = loadAssocList( $key= )

Returns a result set from a SELECT query as associative arrays that have the
field names as array keys and the field values as array values.
If a key is specified and refers to one of the fields in the
result set, the return values will be keyed by the values of the key
field. Otherwise, the return values will have numeric subscripts. If the SELECT does not produce any rows, then the result will be a
PHP null. This is not ideal, as it would be better to receive back an
empty array. However, it is retained for backwards compatibility with
earlier Mambo family systems.

mixed = loadObjectList($key=)

Returns a result set from a SELECT query as an array of objects, or if no rows
result from the query, a PHP null is returned. If a key name is
provided as the parameter, then the array will be keyed by the values
of the key field. Otherwise, the subscripts will be numeric.
A more powerful method is provided in Aliro, called doSQLget().

loadRow()

I'm not sure what this does

loadRowList

Nor this one, without studying what happens, have never used it

bool = insertObject ($table, $object, $keyName=NULL)

This method will insert an object into a table on the assumption that the
names of the object properties correspond to field names in the table.
The table name is provided as the first parameter, and may use
the standard symbolic prefix of # to be substituted with the actual
prefix for the database. If the third parameter is provided and
the table uses autoincrement, then the object's property identified by
"keyName" is set to the new row's autoincremented key. The result
indicates whether there was any logical failure in the method. A
failure of the database operation will cause an exception, as usual.
A final "verbose" parameter was offered in Mambo, but is not
supported in Aliro and therefore will be ignored if present.

bool = updateObject ($table, $object, $keyName, $updateNulls=true)

Uses the supplied object to update a row in the specified table. The
table name may use the symbolic prefix # to be substituted with the
actual datbase prefix, as with most database methods. The key
name must be given and must correspond to a property of the object
whose value is used to specify the row to be updated. The final,
optional parameter indicates whether object properties that are null
will be used to update the database or whether they will be ignored.
Even if nulls in the object are used for the update, they do not
enter actual NULL into the database, simply set the field using a zero
length string.

int = insertid()

Used after an insert operation into a table that is keyed using an auto-increment integer. The new key is returned.

string = getVersion()

Returns the version of the database system, currently MySQL.

array = getTableList()

Returns an array of table names, including all the tables in the database.
These are the actual names, and has usually been used to check
for the existence of a particular table. This operation is much
more easily achieved by using the Aliro tableExists() method which
expects a table name with the standard symbolic prefix of # thus
avoiding the need to find out the actual database prefix. The
Aliro method is also more efficient, as it takes advantage of cached
data rather than going to the database.

array = getTableCreate($tablenames)

Given an array of actual table names (not using # but the actual prefix),
this method returns an array of SQL statements, each of which creates
one of the specified tables.

array = getTableFields($tablenames)

Returns an array with one entry for each of the names in the supplied array of
table names. Each entry in the returned array is an array of
field information. The table names must be actual names.
Generally, there are Aliro methods that will be more useful, both
because they work on the # prefixed table names and also because they
cache database information.

Aliro methods

All Aliro methods that take table names as parameters expect the symbolic prefix of #
to be used. Where necessary, this will be automatically converted
to the actual database prefix. There should be no need for an
application to find out what the database prefix actually is.

string = getName()

Returns the name of this database.

array = getAllFieldInfo ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic
prefix, e.g. #simple_text. The return value is an array
containing the results of SQL "SHOW FIELDS FROM ...". If the
table name given is invalid, the array will have zero elements.

array = getAllFieldNames ($tablename)

Requires a valid table name as parameter, in the format that uses the symbolic prefix, e.g. #simple_text. The return value is an array
containing the fields that exist within the table. If the tablename is invalid, the array will have zero elements.

bool = addFieldIfMissing ($tablename, $fieldname, $fieldspec, $alterIfPresent=false)

Requires a valid table name as the first parameter, in the format that uses the
symbolic prefix, e.g. #simple_text. The second parameter is the
name of the field that may be added. The third parameter is a SQL
field specification that will be used if the field is added. If
the boolean fourth parameter is given as true, then if the field is
already present, the field specification will be used in a SQL ALTER
TABLE statement. Note that with the boolean set to false, the
cost of this operation is very low in case the field already exists,
because information about tables is cached. But if it is true,
then the method will always cause one SQL operation. The return
value is true if the field was added, or false if it was already
present.

bool = function dropFieldIfPresent ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the
symbolic prefix, e.g. #simple_text. The second parameter is the
name of the field that may be dropped. The return value is a
boolean indicating whether the field was dropped.

bool = alterField ($tablename, $fieldname, $fieldspec)

Requires a valid table name as the first parameter, in the format that
uses the
symbolic prefix, e.g. #simple_text. The second parameter is the
name
of the field that may be altered. The third parameter is a SQL
field
specification that will be used if the field is altered. The
return value is a boolean that will be false if there is no such field,
and true if there is. In the latter case, the specified field
will have been altered.

string = getFieldInfo ($tablename, $fieldname)

Requires a valid table name as the first parameter, in the format that uses the
symbolic prefix, e.g. #simple_text. The second parameter is the
name of the field whose information is wanted. The return value
will be the information for the field obtained from SQL "SHOW FIELDS
FROM ..." if the table and field exist, otherwise null.

string = setFieldValue ($value)

This is a helper method (in the sense that it does not do anything that is
specific to the database object) that processes a value and returns a
string that can be used to to set the value in a SQL statement.
If the parameter is non-numeric, it will be escaped. If it
is integer, it will not be enclosed in quotes; in all other cases it
will.

bool = tableExists ($tablename)

Requires a valid table name as the first parameter, in the format that uses the symbolic prefix, e.g. #simple_text. If the table exists the return value is true, otherwise false.

string = restoreOnePrefix ($tablename)

This method is mainly for internal use, but might be helpful for an
application. It takes a table name that is expected to have the
standard database prefix (e.g. aliro_) at its start. If this is
found, then the standard symbolic prefix of # is put in its place.
Otherwise the table name is left unaltered. The result is
returned.

cursor = doSQL ($sql)

The provided SQL is stored in the database object, and submitted to the database system for
processing. This method combines setQuery() and query() into a
single operation that is useful for INSERT, UPDATE and DELETE
operations. NOTE: Aliro will not give an error return, but will raise an exception
if there is an error during SQL processing. An application can trap
this if required, or it will be dealt with by Aliro's default error
handling.

array = doSQLget ($sql, $classname='stdClass', $key=, $max=0)

The provided SQL is stored in the database object, and submitted to the
database system for processing. It is assumed to be a SELECT
statement. An array of database rows is returned (which may
contain zero elements). If the second parameter is supplied, then
it determines the class that will be created for each row. If the
name of the key is given as the third parameter, then the array that is
returned will have the key values as its keys instead of having
sequential numeric values as its keys. If the fourth parameter is
given a positive value, then only the first so many results will be
included in the returned array. NOTE: Aliro will not give an error return, but will raise an exception
if there is an error during SQL processing. An application can trap
this if required, or it will be dealt with by Aliro's default error
handling.

int = getCount()

Returns a count of the number of queries that have been processed in the
current request. Primarily intended for use by Aliro, but
generally available.

string = getLogged()

Returns an HTML format string showing all the queries that have been run in the current
request. Again, primarily intended for Aliro use, but generally
available.