>> YANA 4 PHP Framework >> Docs For Class StructureFile

Class StructureFile

Description

database schema file

This wrapper class represents the structure of a database

  • access: public

Located in /includes/class_structurefile.php

Object
   |
   --InputStream
      |
      --SecureInputStream
         |
         --SecureFileStream
            |
            --SML
               |
               --StructureFile
Method Summary
  • StructureFile StructureFile (string $filename)
  • bool addColumn (string $table, string $column)
  • bool addFile (string $filename)
  • bool addTable (string $table)
  • bool checkRow (string $table, mixed &$row, [bool $is_insert = true])
  • array getColumns (string $table)
  • array|false getColumnsByType (string $table, string $type)
  • array getConstraint (string $operation, string $table, [array $columns = array()])
  • mixed getDefault (string $table, string $column)
  • string getDescription (string $table, string $column)
  • array|false getFiles (string $table)
  • array getForeignKeys (string $table)
  • array getImageSettings (string $table, string $column)
  • array getIndexes (string $table)
  • int getLength (string $table, string $column)
  • string getPrimaryKey (string $table)
  • string|bool(false) 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 isPrimaryKey (string $table, string $column)
  • bool isReadonly ([string $table = ""], [string $column = ""])
  • bool isStrict ()
  • bool isTable (string $table)
  • bool isUnique (string $table, string $column)
  • bool isVisible (string $table, string $column, [string $action = ""])
  • array|bool read ()
  • bool setAuto (string $table, string $column, bool $isNullable)
  • bool setConstraint (string $constraint, string $operation, [string $table = null], [string $column = null])
  • bool setDefault (string $table, string $column, midex $value)
  • bool setDescription (string $table, string $column, string $description)
  • bool setEditable (bool $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 setLength (string $table, string $column, int $length)
  • bool setNullable (string $table, string $column, bool $isNullable)
  • 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 setVisible (bool $isVisible, string $table, string $column, [string $action = ""])
  • mixed untaintInput (string $table, string $column, mixed $value, [int $escape = YANA_ESCAPE_NONE])

Methods

constructor
StructureFile StructureFile (
string $filename
)
List of parameters:
Name Type Description
$filename string
Description:

Create a new instance of this class.

add a new column
bool addColumn (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
Description:

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

  • since: 2.9
  • access: public
include structure file
bool addFile (
string $filename
)
List of parameters:
Name Type Description
$filename string
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
Description:

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

  • since: 2.9
  • access: public
validate a row against the schema
bool checkRow (
string $table, mixed &$row, [bool $is_insert = true]
)
List of parameters:
Name Type Description
$table string
&$row mixed
$is_insert bool
Description:

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

  • access: public
get the names of all columns in a table
array getColumns (
string $table
)
List of parameters:
Name Type Description
$table string
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|false getColumnsByType (
string $table, string $type
)
List of parameters:
Name Type Description
$table string
$type string
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
$columns array (optional)
Description:

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

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
$column string
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).

  • access: public
get the user description of a column
string getDescription (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
Description:

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

get a list of all columns that contain blobs
array|false getFiles (
string $table
)
List of parameters:
Name Type Description
$table string
Description:

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

  • 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
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.

  • 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
$column string
Description:

Returns an array of the following values:

  1.  array (
  2.     'size'       int,  // maximum size in bytes
  3.         'width'      int,  // horizontal dimension in px
  4.         'height'     int,  // vertical dimension in px
  5.         'ratio'      bool// keep aspect-ratio (true=yes, false=no)
  6.         'background' array(redgreenblue// color of canvas
  7.   )
If one of the values above does not exist, the field is set to 'null'.

get a list of all indexed columns in a table
array getIndexes (
string $table
)
List of parameters:
Name Type Description
$table string
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 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
$column string
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.

get the primary key of a table
string getPrimaryKey (
string $table
)
List of parameters:
Name Type Description
$table string
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|bool(false) getProfile (
string $table
)
List of parameters:
Name Type Description
$table string
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).

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
$foreignKey string
Description:
  • 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
$columns array
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.

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
$column string
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.

get a list of all unique columns in table
array getUniqueConstraints (
string $table
)
List of parameters:
Name Type Description
$table string
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
$column string
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.

check whether a column uses the "autofill" feature
bool isAuto (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
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".

check whether a column is autonumber/autoincrement
bool isAutonumber (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
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.

  • name: StructureFile::isAutonumber()
  • since: 2.8.6
  • access: public
check whether a column exists in the current structure
bool isColumn (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
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
$column string
$action string
Description:

Returns bool(true) if:

  1. the table and column exist AND
  2. the column's readonly flag is set to true (see StructureFile::isReadonly) AND
  3. the column is not visible (see StructureFile::isVisible) AND
  4. the column setting DISPLAY.READONLY is not set, or false AND
  5. the column setting DISPLAY.READONLY.$action is not set OR
  6. 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.

check whether a foreign key exists in the current structure
bool isForeignKey (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
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
$column string
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.

check whether a primary key exists in the current structure
bool isPrimaryKey (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
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
$column string
Description:

Returns bool(true) if:

  1. database is set to 'readonly=true', or
  2. $table is set to 'readonly=true', or
  3. $column in $table is set to 'readonly=true'

Returns bool(false) otherwise.

check whether the structure defines the "USE_STRICT" setting as bool(true)
bool isStrict ()
Description:
check whether a table exists in the current structure
bool isTable (
string $table
)
List of parameters:
Name Type Description
$table string
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
$column string
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.

check whether the column should be visible
bool isVisible (
string $table, string $column, [string $action = ""]
)
List of parameters:
Name Type Description
$table string
$column string
$action string
Description:

Returns bool(true) if:

  1. the table and column exist AND
  2. the column setting DISPLAY.HIDDEN is not set, or false AND
  3. the column setting DISPLAY.HIDDEN.$action is not set OR
  4. 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.

read and initialize the file
array|bool 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()

make a column use auto-number / auto-filled values
bool setAuto (
string $table, string $column, bool $isNullable
)
List of parameters:
Name Type Description
$table string
$column string
$isNullable bool
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.

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

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
$column string
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.

set the default value of a field as specified in the structure
bool setDefault (
string $table, string $column, midex $value
)
List of parameters:
Name Type Description
$table string
$column string
$value midex
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
$column string
$description string
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.

select whether the column should be editable
bool setEditable (
bool $isEditable, string $table, string $column, [string $action = ""]
)
List of parameters:
Name Type Description
$isEditable bool
$table string
$column string
$action string
Description:

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

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.

add a foreign key constraint
bool setForeignKey (
string $table, string $column, [string $ftable = null]
)
List of parameters:
Name Type Description
$table string
$column string
$ftable string
Description:

To unset, leave $ftable blank.

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
$column string
$settings array
Description:

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

  1.  array (
  2.     'size'       int,  // maximum size in bytes
  3.         'width'      int,  // horizontal dimension in px
  4.         'height'     int,  // vertical dimension in px
  5.         'ratio'      bool// keep aspect-ratio (true=yes, false=no)
  6.         'background' array(redgreenblue// color of canvas
  7.   )
If one of the values above does not exist, the field is set to 'null'.

add/remove an index on a column
bool setIndex (
string $table, string $column, bool $hasIndex
)
List of parameters:
Name Type Description
$table string
$column string
$hasIndex bool
Description:

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

set the maximum length property of a column
bool setLength (
string $table, string $column, int $length
)
List of parameters:
Name Type Description
$table string
$column string
$length int
Description:

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

The argument $length must be a positive integer.

choose wether a column should be nullable
bool setNullable (
string $table, string $column, bool $isNullable
)
List of parameters:
Name Type Description
$table string
$column string
$isNullable bool
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).

set the primary key of a table
bool setPrimaryKey (
string $table, string $column
)
List of parameters:
Name Type Description
$table string
$column string
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
$column string
Description:

To unset, leave $column blank.

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

set the "readonly" property
bool setReadonly (
bool $isReadonly, [string $table = null], [string $column = null]
)
List of parameters:
Name Type Description
$isReadonly bool
$table string
$column string
Description:

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

select whether the structure should use the "strict" directive
void setStrict (
bool $isStrict
)
List of parameters:
Name Type Description
$isStrict bool
Description:

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

set constraint
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 select, insert, update, delete
$table string
$column string
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.

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
$column string
$value midex
Description:

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

add/remove a unique constraint on a column
bool setUnique (
string $table, string $column, bool $isUnique
)
List of parameters:
Name Type Description
$table string
$column string
$isUnique bool
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.

select whether the column should be visible
bool setVisible (
bool $isVisible, string $table, string $column, [string $action = ""]
)
List of parameters:
Name Type Description
$isVisible bool
$table string
$column string
$action string
Description:

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

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.

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
$column string
$value mixed
$escape int
Description:
  • access: public
inherited from base classes

Inherited From SML

Inherited From SecureFileStream

Inherited From SecureInputStream

Inherited From InputStream

Inherited From Object

Documentation generated on Sun, 11 Mar 2007 15:02:47 +0100 by phpDocumentor 1.3.1

yana author: Thomas MeyerHomepage: www.yanaframework.net