Docs For Class DbStructure

YANA Framework for PHP

Class DbStructure

Description

database structure file

This wrapper class represents the structure of a database

access: public

Object
   |
   --FileSystemResource
      |
      --FileReadonly
         |
         --File
            |
            --SML
               |
               --DbStructure

Method Summary

DbStructure DbStructure (string $filename)
bool addColumn (string $table, string $column)
bool addFile (string $filename)
bool addTable (string $table)
bool checkRow (string $table, mixed &$row, [bool $isInsert = true])
bool dropChangelog ()
bool dropColumn (string $table, string $column)
bool dropTable (string $table)
mixed getAction (string $table, string $column, [string $namespace = 'DEFAULT'])
array getActions (string $table)
array getChangelog ()
array getColumns (string $table)
array getColumnsByType (string $table, string $type)
array getConstraint (string $operation, string $table, [array $columns = array()])
mixed getDefault (string $table, string $column)
string getDescription ([string $table = null], [string $column = null])
array getFiles (string $table)
array getForeignKeys (string $table)
array getImageSettings (string $table, string $column)
array getIndexes (string $table)
bool getInit ([string $table = null])
int getLength (string $table, string $column)
array getListOfFiles ([bool $fullFilename = false])
int getPrecision (string $table, string $column)
string getPrimaryKey (string $table)
string getProfile (string $table)
mixed getSource ()
mixed getStructure ()
string getTableByForeignKey (string $table, string $foreignKey)
array getTables ()
array getTrigger (int $prefix, string $operation, string $table, [array $columns = array()])
string getType (string $table, string $column)
array getUniqueConstraints (string $table)
bool hasIndex (string $table, string $column)
bool isAuto (string $table, string $column)
bool isAutonumber (string $table, string $column)
bool isColumn (string $table, string $column)
bool isEditable (string $table, string $column, [string $action = ""])
bool isForeignKey (string $table, string $column)
bool isNullable (string $table, string $column)
bool isNumber (string $table, string $column)
bool isNumericArray (string $table, string $column)
bool isPrimaryKey (string $table, string $column)
bool isReadonly ([string $table = ""], [string $column = ""])
bool isStrict ()
bool isTable (string $table)
bool isUnique (string $table, string $column)
bool isUnsigned (string $table, string $column)
bool isVisible (string $table, string $column, [string $action = ""])
bool isZerofill (string $table, string $column)
array read ()
bool renameColumn (string $table, string $oldColumn, string $newColumn)
bool renameTable (string $oldTable, string $newTable)
mixed setAction (string $table, string $column, [string $action = null], [string $namespace = 'DEFAULT'], [string $linkText = ''], [string $tooltip = ''])
bool setAuto (string $table, string $column, [bool $isAuto = true])
bool setConstraint (string $constraint, string $operation, [string $table = null], [string $column = null])
bool setDefault (string $table, string $column, mixed $value)
bool setDescription (string $table, string $column, string $description)
bool setEditable (bool|int $isEditable, string $table, string $column, [string $action = ""])
bool setForeignKey (string $table, string $column, [string $ftable = null])
array setImageSettings (string $table, string $column, array $settings)
bool setIndex (string $table, string $column, bool $hasIndex)
bool setInit (string $table, [array $statements = null])
bool setLength (string $table, string $column, int $length, [int $precision = -1])
bool setNullable (string $table, string $column, bool $isNullable)
bool setNumericArray (string $table, string $column, [bool $isNumeric = true])
bool setPrimaryKey (string $table, string $column)
bool setProfile (string $table, [string $column = null])
bool setReadonly (bool $isReadonly, [string $table = null], [string $column = null])
void setStrict (bool $isStrict)
bool setTrigger (string $trigger, int $prefix, string $operation, [string $table = null], [string $column = null])
bool setType (string $table, string $column, midex $value)
bool setUnique (string $table, string $column, bool $isUnique)
bool setUnsigned (string $table, string $column, bool $isUnsigned)
bool setVisible (bool|int $isVisible, string $table, string $column, [string $action = ""])
bool setZerofill (string $table, string $column, bool $isZerofill)
mixed untaintInput (string $table, string $column, mixed $value, [int $escape = YANA_ESCAPE_NONE])

Methods

constructor

DbStructure DbStructure (

string $filename

)

List of parameters:

Name	Type	Description
$filename	string	name of database structure file

Description:

Create a new instance of this class.

The argument $filename may either be a path to a structure file, or, if the file refers to an active database and is stored in the database configuration directory, the name of a database without any path or file extension.

add a new column

bool addColumn (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) on success and bool(false) otherwise.

see: DbStructure::dropColumn()
see: DbStructure::renameColumn()
since: 2.9
access: public
name: DbStructure::addColumn()

include structure file

bool addFile (

string $filename

)

List of parameters:

Name	Type	Description
$filename	string	path to another structure file

Description:

This function merges the contents of another file with the current structure.

Note that you can reach the same result by using the 'INCLUDE' tag in the structure file. See the developer's cookbook for an example.

access: public

add a new table

bool addTable (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns bool(true) on success and bool(false) otherwise.

see: DbStructure::dropTable()
see: DbStructure::renameTable()
since: 2.9
access: public
name: DbStructure::addTable()

validate a row against this file

bool checkRow (

string $table, mixed &$row, [bool $isInsert = true]

)

List of parameters:

Name	Type	Description
$table	string	table name
&$row	mixed	values of the inserted/updated row
$isInsert	bool	type of operation (true = insert, false = update)

Description:

The argument $row is expected to be an associative array of values, representing a row that should be inserted or updated in $table. The keys of the array $row are expected to be the lowercased column names.

Returns bool(true) if $row is valid and bool(false) otherwise.

access: public

flush the changelog

bool dropChangelog ()

Description:

This clears all entries in the changelog.

The function returns bool(true) on succes. If the log is already empty, it returns bool(false) instead.

see: DbStructure::getChangelog()
since: 2.9.7
access: public
name: DbStructure::dropChangelog()

drop a column

bool dropColumn (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	previous name of column

Description:

Returns bool(true) on success and bool(false) otherwise.

see: DbStructure::renameColumn()
see: DbStructure::addColumn()
since: 2.9.7
access: public
name: DbStructure::dropColumn()

drop a table

bool dropTable (

string $table

)

List of parameters:

Name	Type	Description
$table	string	previous name of table

Description:

Removes a table definition from the database. Returns bool(true) on success and bool(false) otherwise.

see: DbStructure::renameTable()
see: DbStructure::addTable()
since: 2.9.7
access: public
name: DbStructure::dropTable()

get the action property of a field as specified in the structure

mixed getAction (

string $table, string $column, [string $namespace = 'DEFAULT']

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$namespace	string	namespace of form

Description:

Returns constant NULL (not bool(false)) if value is not specified. Use is_null($result) to test for existance, don't use empty($result).

The argument $namespace can be either 'edit', 'select', or empty. See FormCreator::getNamespace() for details.

see: FormCreator::getNamespace()
see: DbStructure::setAction()
see: DbStructure::getActions()
since: 2.9.4
access: public
name: DbStructure::getAction()

get all columns of a table, where the action property is set

array getActions (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns the list of columns as an associative array, where the names of the columns will be the array keys and the value of the 'action' property will be the array values. If no such columns are found, the array will be empty.

Note that the values may either be of type 'string', or an array of strings, with 1 or 2 elements, where the keys are the namespace of the form the setting applies to and the values are the name of the action to link to.

The array will use the following syntax (example):

array(
'column1' => array(
'EDIT' => 'actionName1',
'SELECT' => 'actionName2'
),
'column2' => array(
'EDIT' => 'actionName3',
'SELECT' => 'actionName4'
),
'column2' => 'actionName5'
);

see: FormCreator::getNamespace()
see: DbStructure::setAction()
see: DbStructure::getAction()
since: 2.9.4
access: public
name: DbStructure::getActions()

get list of changes for your documentation purposes

array getChangelog ()

Description:

This class automatically logs changes to the data model, which have been introduced by using functions of this class. A changelog is created, that may be used for various purposes, e.g. creating automatic documentation.

This function returns a list of changes that have been applied to the current database structure as a multidimensional associative array. On error, or if no changelog exists, it returns bool(false) instead.

The changelog entries use the following syntax:

array(
'DESCRIPTION' => "comment of your choice",
'FUNCTION' => 'create' or 'rename' or 'update' or 'drop',
'ARGS' => array(
0 => 'table',
1 => 'column'
)
)

Here is an example of what your result might look like:

array(
0 => array(
'DESCRIPTION' => "12 Dec 2000 (ADMIN) create table",
'FUNCTION' => 'create',
'ARGS' => array(
0 => 'foo'
),
1 => array(
'DESCRIPTION' => "12 Dec 2000 (ADMIN) update column",
'FUNCTION' => 'update',
'ARGS' => array(
0 => 'bar',
1 => 'id'
),
)

Here is an example on how to export the changelog to XML:

$log = $structure->getChangelog();
print XMLencode($log);

The created xml code may then be converted to HTML using a xml-converter of your choice. As an alternative, you might also decide to loop through the array and output all entries directly as (X)HTML.

see: DbStructure::dropChangelog()
since: 2.9.7
access: public
name: DbStructure::getChangelog()

get the names of all columns in a table

array getColumns (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns a numeric array of all columns in $table. Issues an E_USER_NOTICE and returns an empty array, if $table does not exist in current structure file.

access: public

get a list of all columns that match a certain type

array getColumnsByType (

string $table, string $type

)

List of parameters:

Name	Type	Description
$table	string	name of table
$type	string	datatype ('string', 'text', 'int', ...)

Description:

Returns false if the table does not exist. Otherwise it returns a list of column names.

since: 2.9 RC3
access: public

get all constraints for an address

array getConstraint (

string $operation, string $table, [array $columns = array()]

)

List of parameters:

Name	Type	Description
$operation	string	one of select, insert, update, delete
$table	string	name of table
$columns	array	list of columns

Description:

Retrieves all "constraint" entries that apply to the given operation on the dataset and returns the results as an numeric array.

see: DbStructure::setConstraint()
since: version 2.8.4
access: public
name: DbStructure::getConstraint()

get the default value of a field as specified in the structure

mixed getDefault (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns the default value of $column in $table (where available). The type of the default value returned depends on the type of the column.

Returns constant NULL (not bool(false)) if the default value is not specified, or the table/column does not exist. Use is_null($result) to test for existance, don't use empty($result).

access: public

get the user description of a column

string getDescription (

[string $table = null], [string $column = null]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns the description text (=comment) of $column in $table as a string or bool(false) if none exists.

see: DbStructure::setDescription()
since: 2.8.6
access: public
name: DbStructure::getDescription()

get a list of all columns that contain blobs

array getFiles (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

This function provides a list of all columns, which are of type "image" or "file" in $table as a numeric array of strings.

It returns bool(false) if the table does not exist.

since: 2.8.9
access: public

return a list of foreign keys defined on a table

array getForeignKeys (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns an associative array of foreign keys. If $table is not a specified in the current structure file, then NULL is returned instead. If the table has no foreign keys, an empty array is returned.

Note that this operation is not case sensitive.

The returned result will look as follows:

array(
'column_1' => 'table_1',
'column_2' => 'table_2'
);

Example of usage:

foreach ($structure->getForeignKeys($table) as $fColumn => $fTable)
{
print "Column $fColumn in $table points to primary key of table $fTable.\n";
}

access: public

get the properties of a field of type 'image'

array getImageSettings (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns an array of the following values:

array (
'size' : int, // maximum size in bytes
'width' : int, // horizontal dimension in px
'height' : int, // vertical dimension in px
'ratio' : bool, // keep aspect-ratio (true=yes, false=no)
'background' : array(red, green, blue) // color of canvas
)

If one of the values above does not exist, the field is set to 'null'.

see: DbStructure::setImageSettings()
since: 2.8.9
access: public
name: DbStructure::getImageSettings()

get a list of all indexed columns in a table

array getIndexes (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns a numeric array of all columns in $table, that are marked with the option INDEX => true (which means, all columns that have an index).

since: 2.8.5
access: public

get sql statements for initialization of a table

bool getInit (

[string $table = null]

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns a list of sql statements as a numeric array on success and bool(false) on error.

This can be particularly usefull to insert standard rows in a table on creation, that otherwise would be empty.

You may leave argument $table blank to get all statements for all tables.

see: DbStructure::setInit()
since: 2.9.7
access: public
name: DbStructure::getInit()

get the maximum length of a column as specified in the structure

int getLength (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns the 'length' attribute of $column in $table. Returns int(0) if there is no $table, or the table has no column named $column, or the column does not have a 'length' attribute.

see: DbStructure::setLength()
access: public
name: DbStructure::getLength()

return list of known structure files

array getListOfFiles (

[bool $fullFilename = false]

)

List of parameters:

Name	Type	Description
$fullFilename	bool	return items as full filenames (true = yes, false = no)

Description:

This function returns a numeric list of filenames of known structure files. Each item is a valid argument for calling the constructor of this class.

If the argument $fullFilename is set to bool(true) the items are complete filenames, including the path, relative to the framework's root directory. Otherwise only the names of the structures are returned, which are easier to read for humans. Both may be used as input to create a new instance.

In case of an unexpected error, this function returns an empty array.

since: 2.9.7
access: public

get the maximum length of the decimal fraction of a float

int getPrecision (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns the 'precision' attribute of $column in $table. Returns int(0) if there is no $table, or the table has no column named $column, or the column does not have a 'precision' attribute.

see: DbStructure::setLength()
see: DbStructure::getLength()
since: 2.9.7
access: public
name: DbStructure::getPrecision()

get the primary key of a table

string getPrimaryKey (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns the name of the primary key column of $table as a lower-cased string. Returns NULL and issues an E_USER_WARNING if $table is not a listed table in the current structure file. Returns NULL and issues an E_USER_WARNING if there is no primary key for $table.

access: public

check whether the table has a column containing a profile id

string getProfile (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns the name of a column that is supposed to contain the profile id (if any).

If no table named $table is listed in the current structure file or $table does not have a column using a profile id, or the specified column does not exist, the function returns bool(false).

see: DbStructure::setProfile()
since: 2.9
access: public
name: DbStructure::getProfile()

get the file source

mixed getSource ()

Description:

Returns the text of the source file containing the database structure as a string or bool(false) on error.

access: public

get the compiled structure of the database

mixed getStructure ()

Description:

access: public

get the name of the table, a foreign key points to

string getTableByForeignKey (

string $table, string $foreignKey

)

List of parameters:

Name	Type	Description
$table	string	name of base table
$foreignKey	string	name of column containing the foreign key

Description:

Returns the lower-cased table name. If the foreign key does not exist, an empty string is returned.

access: public

get a list of all tables in the current database

array getTables ()

Description:

Returns a numeric array of all tables in the current structure file. Issues an E_USER_NOTICE and returns an empty array, if the list of tables is empty.

access: public

get all triggers for an address

array getTrigger (

int $prefix, string $operation, string $table, [array $columns = array()]

)

List of parameters:

Name	Type	Description
$prefix	int	currently one of YANA_TRIGGER_BEFORE, YANA_TRIGGER_AFTER
$operation	string	one of insert, update, delete
$table	string	name of table
$columns	array	list of columns

Description:

Retrieves all "trigger" entries that apply to the given operation on the dataset and returns the results as an numeric array.

There are two constants to use for argument $prefix: The first, YANA_TRIGGER_BEFORE, refers to triggers that fire BEFORE the action $operation is carried out. And YANA_TRIGGER_AFTER, refers to triggers that fire AFTER the action $operation has been carried out.

see: DbStructure::setTrigger()
since: 2.8.5
access: public
name: DbStructure::getTrigger()

get the data type of a field as specified in the structure

string getType (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns the 'type' attribute of $column in $table as a lower-cased string. Returns string("") if there is no $table, or the table has no column named $column, or the column does not have a 'type' attribute.

see: DbStructure::setType()
access: public
name: DbStructure::getType()

get a list of all unique columns of a table

array getUniqueConstraints (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns a numeric array of all columns in $table, that are marked with the option UNQIUE => true (which means, all columns that have an unique constraint).

since: 2.8.5
access: public

check whether a column is indexed in the current structure

bool hasIndex (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file and it has a column named $column, which has an index. Returns bool(false) otherwise. Note that this operation is not case sensitive.

see: DbStructure::setIndex()
since: 2.8.5
access: public
name: DbStructure::hasIndex()

check whether a column uses the "autofill" feature

bool isAuto (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file and it has a column named $column that uses the autofill feature. Returns bool(false) otherwise. Note that this operation is not case sensitive.

Autofill is activated by setting the property "REQUIRED" to "AUTO".

see: DbStructure::isAutonumber()
since: 2.9
access: public
name: DbStructure::isAuto()

check whether a column is autonumber/autoincrement

bool isAutonumber (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file and it has a column named $column that is an autonumber colummn. Returns bool(false) otherwise. Note that this operation is not case sensitive.

since: 2.8.6
access: public
name: DbStructure::isAutonumber()

check whether a column exists in the current structure

bool isColumn (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file and it has a column named $column in its list of contents. Returns bool(false) otherwise. Note that this operation is not case sensitive.

access: public

check whether the column should be editable

bool isEditable (

string $table, string $column, [string $action = ""]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$action	string	namespace of form ('SELECT', 'EDIT', 'NEW', 'SEARCH')

Description:

Returns bool(true) if:

the table and column exist AND
the column's readonly flag is set to true (see DbStructure::isReadonly) AND
the column is not visible (see DbStructure::isVisible) AND
the column setting DISPLAY.READONLY is not set, or false AND
the column setting DISPLAY.READONLY.$action is not set OR
the column setting DISPLAY.READONLY.$action exists and is set to false.

Returns bool(false) otherwise.

If the argument $action is not provided, the last two do not apply.

see: DbStructure::isVisible()
see: DbStructure::isReadonly()
since: 2.9.0 RC1
access: public
name: DbStructure::isEditable()

check whether a foreign key exists in the current structure

bool isForeignKey (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file and it has a column named $column in its list of foreign keys. Returns bool(false) otherwise. Note that this operation is not case sensitive.

access: public

check whether a column allows NULL values

bool isNullable (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file and it has a column named $column that allows undefined values (NULL). Returns bool(false) otherwise. Note that this operation is not case sensitive.

see: DbStructure::setNullable()
since: 2.8.6
access: public
name: DbStructure::isNullable()

check if column has a numeric data type

bool isNumber (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if the table and colum exist and the type of the column is numeric. Returns bool(false) otherwise.

since: 2.9.6
access: public

check whether the column has a list-style type

bool isNumericArray (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if:

the table and column exist AND
the column's type is 'array' AND
the column setting DISPLAY.NUMERIC is set to 'true'

Returns bool(false) otherwise.

since: 2.9.4
access: public

check whether a primary key exists in the current structure

bool isPrimaryKey (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file and its primary key is named $column. Returns bool(false) otherwise. Note that this operation is not case sensitive.

access: public

check whether the "READONLY" flag is set to bool(true)

bool isReadonly (

[string $table = ""], [string $column = ""]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if:

database is set to 'readonly=true', or
$table is set to 'readonly=true', or
$column in $table is set to 'readonly=true'

Returns bool(false) otherwise.

see: DbStructure::isEditable()
see: DbStructure::isVisible()
access: public
name: DbStructure::isReadonly()

check whether the structure defines the "USE_STRICT" setting as bool(true)

bool isStrict ()

Description:

Returns bool(true) if the "USE_STRICT" property of the database is true and bool(false) otherwise.

see: DbStructure::setStrict()
access: public
name: DbStructure::isStrict()

check whether a table exists in the current structure

bool isTable (

string $table

)

List of parameters:

Name	Type	Description
$table	string	name of table

Description:

Returns bool(true) if a table with the given name is listed in the current structure file and bool(false) otherwise. Note that this operation is not case sensitive.

access: public

check whether a column has a unique constraint

bool isUnique (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file, it has a column named $column in its list of contents and this column has a unique constraint. Returns bool(false) otherwise. Note that this operation is not case sensitive.

see: DbStructure::setUnique()
since: 2.8.5
access: public
name: DbStructure::isUnique()

check whether a column is an unsigned number

bool isUnsigned (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file, it has a column named $column in its list of contents and this column has the flag unsigned set to bool(true). Returns bool(false) otherwise.

This function will also return bool(true), if the property "zerofill" is set to true, as "zerofill" requires the "unsigned" flag to be set.

Important note: if unsigned is not supported by your DBMS, it is emulated by the framework's database API.

see: DbStructure::setUnsigned()
since: 2.9.6
access: public
name: DbStructure::isUnsigned()

check whether the column should be visible

bool isVisible (

string $table, string $column, [string $action = ""]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$action	string	namespace of form ('SELECT', 'EDIT', 'NEW', 'SEARCH')

Description:

Returns bool(true) if:

the table and column exist AND
the column setting DISPLAY.HIDDEN is not set, or false AND
the column setting DISPLAY.HIDDEN.$action is not set OR
the column setting DISPLAY.HIDDEN.$action exists and is set to false.

Returns bool(false) otherwise.

If the argument $action is not provided, the last two do not apply.

see: DbStructure::isReadonly()
see: DbStructure::isEditable()
since: 2.9.0 RC1
access: public
name: DbStructure::isVisible()

check whether a column is a number with the zerofill flag set

bool isZerofill (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) if a table named $table is listed in the current structure file, it has a column named $column in its list of contents and this column has the flag zerofill set to bool(true). Returns bool(false) otherwise.

Zerofill only makes sense, if the column has a numeric data type, which has a fixed length.

It is meant to be interpreted as follows: If zerofill is set to bool(true), the number is always expanded to the maximum number of digits, defined by the property "length". If length is not set, it is to be ignored.

Important note: if zerofill is not supported by your DBMS, it is emulated by the framework's database API.

see: DbStructure::setZerofill()
since: 2.9.6
access: public
name: DbStructure::isZerofill()

read and initialize the file

array read ()

Description:

Always call this first before anything else. Returns the file content on success and bool(false) on error.

since: 2.8.8
access: public

Redefinition of: SML::read()

rename a column

bool renameColumn (

string $table, string $oldColumn, string $newColumn

)

List of parameters:

Name	Type	Description
$table	string	name of table
$oldColumn	string	previous name of column
$newColumn	string	new name of column

Description:

Returns bool(true) on success and bool(false) otherwise.

see: DbStructure::dropColumn()
see: DbStructure::addColumn()
since: 2.9.7
access: public
name: DbStructure::renameColumn()

rename a table

bool renameTable (

string $oldTable, string $newTable

)

List of parameters:

Name	Type	Description
$oldTable	string	previous name of table
$newTable	string	new name of table

Description:

Returns bool(true) on success and bool(false) otherwise.

see: DbStructure::dropTable()
see: DbStructure::addTable()
since: 2.9.7
access: public
name: DbStructure::renameTable()

set the action property of a field

mixed setAction (

string $table, string $column, [string $action = null], [string $namespace = 'DEFAULT'], [string $linkText = ''], [string $tooltip = '']

)

List of parameters:

Name	Type	Description
$table	string	name of table to modify
$column	string	name of column to modify
$action	string	name of action to link to
$namespace	string	namespace of form to add action to
$linkText	string	text of created hyperlink (may also be path to an image)
$tooltip	string	title-attribute of hyperlink (displayed as tooltip)

Description:

This property can be used to tell the form generator to produce a clickable link on this column. The link will point to the action provided here.

You may use the argument $linkText to specify some text or image to display. For images just enter the file's name and path as text (e.g. "common_files/icon_new.gif").

The argument $namespace can be either 'edit', 'select', or empty. See FormCreator::getNamespace() for details.

To unset the action property, leave off the argument $action, or set it to NULL. Note: when the property is unset, the arguments $linkText and $tooltip are ignored.

Returns constant bool(false) on error.

see: FormCreator::getNamespace()
see: DbStructure::getActions()
see: DbStructure::getAction()
since: 2.9.4
access: public
name: DbStructure::setAction()

make a column use auto-number / auto-filled values

bool setAuto (

string $table, string $column, [bool $isAuto = true]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$isAuto	bool	new value of this property

Description:

Sets the property "required" of the selected column to the value "auto".

This enables the "autofill" feature, which is available for columns of several types. On columns of type "integer" it mimics MySQL's "auto increment" feature. On columns of type "ip" it enters the visitor's remote address (IP) automatically. For type "time" it enters the current server time.

However: you should note, that the user input takes precedence over the autofill feature, which defines a default value.

Note: this function does not check wether "autofill" does "make sense" for the type of column you selected. It also does not clear the "default" property of the column, if any.

Also note that this property is "virtual". This means, there is not really a property "auto" in structure files. Instead this will set the property "required" to the value "auto". If the argument $isAuto is set to false, the property "required" will be set back to bool(true). This is identical to calling DbStructure::setNullable() with the value bool(false). Thus calling DbStructure::isNullable() on this column will return bool(false).

Returns bool(false) if the table or column does not exist.

see: DbStructure::isNullable()
see: DbStructure::setNullable()
see: DbStructure::isAuto()
since: 2.9
access: public
name: DbStructure::setAuto()

set constraint

bool setConstraint (

string $constraint, string $operation, [string $table = null], [string $column = null]

)

List of parameters:

Name	Type	Description
$constraint	string	PHP-Code
$operation	string	one of select, insert, update, delete
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) on success and bool(false) on error.

Note: This function will check some syntax of your code. However, it can't ensure that your codes makes sense. So keep in mind that it is your job in the first place to ensure the constraint is valid!

BE WARNED: As always - do NOT use this function with any unchecked user input.

see: DbStructure::getConstraint()
since: 2.9
access: public
name: DbStructure::setConstraint()

set the default value of a field as specified in the structure

bool setDefault (

string $table, string $column, mixed $value

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$value	mixed	new value of this property

Description:

since: 2.8.9
access: public

set the description property of a column

bool setDescription (

string $table, string $column, string $description

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column (set to NULL to modify the description property of a table)
$description	string	new value of this property

Description:

Returns bool(true) on success and bool(false) on error.

A description is the "label" of a column. A human-readable small phrase that should tell readers what it is.

Note: though you may take any length of text you want, you are best adviced to use really short phrases like 'name', 'address' or 'phone' as a description.

Note: to set the property description of a table instead of a column, set the argument $column to NULL. To set the property of a database, set the argument $table to NULL.

see: DbStructure::getDescription()
since: 2.9
access: public
name: DbStructure::setDescription()

select whether the column should be editable

bool setEditable (

bool|int $isEditable, string $table, string $column, [string $action = ""]

)

List of parameters:

Name	Type	Description
$isEditable	bool\|int	new value of this property
$table	string	name of table
$column	string	name of column
$action	string	namespace of form ('SELECT', 'EDIT', 'NEW', 'SEARCH')

Description:

This sets the "display.readonly" property of the column to bool(false), if $isEditable is bool(true) and vice versa.

The argument $isEditable may also be an integer of 0 through 100. If so, this value will be compared with the security level of the user and the column will be editable, if the user has a level of permission of $isVisible or higher. E.g. if $isEditable is set to 100, the column will only be editable by administrators, while setting it to 30 will make it editable to administrators and all other users, which at least have a security level of 30 or above.

This function returns bool(true) on success and bool(false) on error.

Note: if you don't provide the attribute $action then settings will apply to all actions. Otherwise you need to set the display property for all actions separately.

see: DbStructure::isVisible()
since: 2.9
access: public
name: DbStructure::setVisible()

add a foreign key constraint

bool setForeignKey (

string $table, string $column, [string $ftable = null]

)

List of parameters:

Name	Type	Description
$table	string	name of base table
$column	string	name of column
$ftable	string	name of target table

Description:

Sets a foreign key constraint on a $column in $table. The foreign key will point to table $ftable.

To unset the constraint, leave $ftable blank, or set it to null.

Returns bool(true) on success and bool(false) on error.

access: public

set the properties of a field of type 'image'

array setImageSettings (

string $table, string $column, array $settings

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$settings	array	new set of image settings

Description:

The argument $settings is an array of the following values:

array (
'size' : int, // maximum size in bytes
'width' : int, // horizontal dimension in px
'height' : int, // vertical dimension in px
'ratio' : bool, // keep aspect-ratio (true=yes, false=no)
'background' : array(red, green, blue) // color of canvas
)

If one of the values above does not exist, the field is set to 'null'.

see: DbStructure::getImageSettings()
since: 2.9
access: public
name: DbStructure::setImageSettings()

add/remove an index on a column

bool setIndex (

string $table, string $column, bool $hasIndex

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$hasIndex	bool	new value of this property

Description:

Returns bool(true) on success and bool(false) on error.

see: DbStructure::hasIndex()
since: 2.9
access: public
name: DbStructure::setIndex()

set sql statements for initialization of a table

bool setInit (

string $table, [array $statements = null]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$statements	array	list of sql statements

Description:

This adds a list of standard SQL statements to a table, that will be auto-run, when the database is installed. This can be particularly usefull to insert standard rows in a table on creation, that otherwise would be empty.

To unset the currently selected initialization statements, set the second argument to NULL.

Returns bool(true) on success and bool(false) otherwise.

1) Note on SQL syntax. The syntax of the statements is limited, since it needs to be DBMS-independent. This is, only Insert, Update and Delete statements are allowed. These statements must comply with the syntax understood by the framework's internal query parser. E.g. this means 1) no quoting of identifiers and 2) double-quotes (") need to be used as string delimiters. If you don't limit yourself to these restrictions, it might still run for the choosen DBMS, but it may not work with the internal virtual database or any other DBMS, that does not support the syntax you have used.

To test the syntax of your statements for a structure file foo.config you may use the following code:

global $YANA;
$parser = new DbQueryParser($YANA->connect('foo'));
foreach ($statements as $statement)
{
if (!$parser->parseSQL($statement)) {
die("Invalid sql: $statement");
}
}

Example for a valid sql statement:

insert into bar (bar_id, bar_value) values("FOO", 1)

2) Note on alternatives. You may have several external sql files for each DBMS you wish to support. To do so you should name your files after the associated structure file and place each of them in the config/db/.install/ directory. E.g. if your structure file is named "foo.config", you should have your sql files named "foo.sql" and put them in "config/db/.install/mysql/foo.sql" for MySQL, "config/db/.install/postgresql/foo.sql" for PostgreSQL aso.

see: DbStructure::getInit()
since: 2.9.7
access: public
name: DbStructure::setInit()

set the maximum length property of a column

bool setLength (

string $table, string $column, int $length, [int $precision = -1]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$length	int	new value of this property
$precision	int	applies to type float only

Description:

Returns bool(true) on success and bool(false) on error.

The argument $length must be a positive integer.

The argument $precision has been added in version 2.9.7. It applies to floating point values only and defines the length of the decimal fraction of the input number.

see: DbStructure::getPrecision()
see: DbStructure::getLength()
since: 2.9
access: public
name: DbStructure::setLength()

choose wether a column should be nullable

bool setNullable (

string $table, string $column, bool $isNullable

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$isNullable	bool	new value of this property

Description:

Sets the "required" property of the column. If the argument $isNullable is bool(true), then "required" is set to false. Otherwise it is set to true.

If the table or column is not defined, the function returns bool(false). Otherwise it returns bool(true).

see: DbStructure::isNullable()
since: 2.9
access: public
name: DbStructure::setNullable()

set's the type of the column to be a numeric array

bool setNumericArray (

string $table, string $column, [bool $isNumeric = true]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$isNumeric	bool	turn on / off

Description:

This sets the type property of the column to 'array' and sets the display property of the column to 'numeric'. Note that the display property is interpreted by Yana's automated form generator only.

Calling this function with $isNumeric set to bool(false) will NOT reset the type of the column. It will just set the display property.

Note: numeric arrays are just like standard arrays, expect that the array's keys are not displayed in automatically generated forms, so that they appear to the user as simple lists. In cases where the array keys do not matter, this might be easier for users to read an edit.

This also means, that the array's keys are also generated automatically by such forms; you don't have precise control over the keys. Use this feature for lists, where you just don't care about the keys of the array.

since: 2.9.4
access: public

set the primary key of a table

bool setPrimaryKey (

string $table, string $column

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

Select $column as the primary key of $table. Returns bool(true) on success and bool(false) on error.

access: public

add/remove a profile reference on a column

bool setProfile (

string $table, [string $column = null]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column

Description:

To unset, leave $column blank.

Returns bool(true) on success and bool(false) on error.

see: DbStructure::getProfile()
since: 2.9
access: public
name: DbStructure::setProfile()

set the "readonly" property

bool setReadonly (

bool $isReadonly, [string $table = null], [string $column = null]

)

List of parameters:

Name	Type	Description
$isReadonly	bool	new value of this property
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) on success and bool(false) otherwise.

see: DbStructure::isReadonly()
access: public
name: DbStructure::setReadonly()

select whether the structure should use the "strict" directive

void setStrict (

bool $isStrict

)

List of parameters:

Name	Type	Description
$isStrict	bool	new value of this property

Description:

Set the property "USE_STRICT" of the database file to the argument $isStrict;

see: DbStructure::isStrict()
since: 2.9
access: public
name: DbStructure::setStrict()

set trigger

bool setTrigger (

string $trigger, int $prefix, string $operation, [string $table = null], [string $column = null]

)

List of parameters:

Name	Type	Description
$trigger	string	PHP-Code
$prefix	int	currently one of YANA_TRIGGER_BEFORE, YANA_TRIGGER_AFTER
$operation	string	one of insert, update, delete
$table	string	name of table
$column	string	name of column

Description:

Returns bool(true) on success and bool(false) on error.

BE WARNED: As always - do NOT use this function with any unchecked user input.

see: DbStructure::getTrigger()
since: 2.9
access: public
name: DbStructure::setTrigger()

set the type of a field as specified in the structure

bool setType (

string $table, string $column, midex $value

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$value	midex	new value of this property

Description:

Note: this function does not check if the provided string is a valid type name.

see: DbStructure::getType()
since: 2.9 RC3
access: public
name: DbStructure::setType()

add/remove a unique constraint on a column

bool setUnique (

string $table, string $column, bool $isUnique

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$isUnique	bool	new value of this property (true = use unique constraint, false = don't use constraint)

Description:

Returns bool(true) on success and bool(false) otherwise.

Note: you don't need to set a "unique" constraint on a primary key. A "primary key" column always requires its values to be unique.

Primary keys implicitely have a unique constraint.

see: DbStructure::isUnique()
since: 2.9
access: public
name: DbStructure::setUnique()

set a column to an unsigned number

bool setUnsigned (

string $table, string $column, bool $isUnsigned

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$isUnsigned	bool	new value of this property (true = use unique constraint, false = don't use constraint)

Description:

Returns bool(true) on success and bool(false) otherwise.

If the type set on this column is not numeric, the function returns bool(false).

An "unsigned" number is supposed to be interpreted as a positive value. This means, with "unsigned" = true, any value lesser than 0 is invalid.

Important note: if zerofill is not supported by your DBMS, it is emulated by the framework's database API.

If the framework's API encounters an invalid number, it returns false and issues an error. Note that this is unlike MySQL, which automatically and silently replaces an invalid value by 0 - which *MIGHT* lead to an error or unexpected behavior of an application working on the database.

see: DbStructure::isUnsigned()
since: 2.9.6
access: public
name: DbStructure::setUnsigned()

select whether the column should be visible

bool setVisible (

bool|int $isVisible, string $table, string $column, [string $action = ""]

)

List of parameters:

Name	Type	Description
$isVisible	bool\|int	new value of this property
$table	string	name of table
$column	string	name of column
$action	string	namespace of form ('SELECT', 'EDIT', 'NEW', 'SEARCH')

Description:

This sets the property "display.hidden" of the column to bool(true), if $isVisible is bool(false) and vice versa.

The argument $isVisible may also be an integer of 0 through 100. If so, this value will be compared with the security level of the user and the column will be visible, if the user has a level of permission of $isVisible or higher. E.g. if $isVisible is set to 100, the column will only be visible to an administrator, while setting it to 30 will make it visible to administrators and all other users, which at least have a security level of 30 or above.

This function returns bool(true) on success and bool(false) on error.

Note: if you don't provide the attribute $action then settings will apply to all actions. Otherwise you need to set the display property for all actions separately.

see: DbStructure::isVisible()
since: 2.9
access: public
name: DbStructure::setVisible()

set a numeric column to zerofill

bool setZerofill (

string $table, string $column, bool $isZerofill

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$isZerofill	bool	new value of this property (true = use zerofill feature, false = don't use it)

Description:

Returns bool(true) on success and bool(false) otherwise.

If the type set on this column is not numeric, the function returns bool(false).

Be aware that setting "zerofill" to bool(true) will also set the property "unsigned", as "zerofill" depends on this.

Important note: if zerofill is not supported by your DBMS, it is emulated by the framework's database API.

see: DbStructure::isZerofill()
since: 2.9.6
access: public
name: DbStructure::setZerofill()

untaint user input data with the help of the schema

mixed untaintInput (

string $table, string $column, mixed $value, [int $escape = YANA_ESCAPE_NONE]

)

List of parameters:

Name	Type	Description
$table	string	name of table
$column	string	name of column
$value	mixed	value to untaint
$escape	int	automated charater escaping

Description:

Will convert input to a datatype and argument length that fits the settings of the provided column.

For details on the $escape argument, see function_untaintInput().

see: function_untaintInput()
access: public
name: DbStructure::untaintInput()

inherited from base classes

Inherited From SML

Inherited From File

Inherited From FileReadonly

Inherited From FileSystemResource

Inherited From Object

Documentation generated on Sat, 03 Jan 2009 22:22:20 +0100 by phpDocumentor 1.4.0

yana author: Thomas Meyer Homepage: www.yanaframework.net