Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

ADOdb XML Schema (v0.3). xmlschema is a class that allows the user to quickly and easily build a database on any ADOdb-supported platform using a simple XML schema.

Author: Richard Tango-Lowy
Author: Dan Cech
Copyright: 2004-2005 ars Cognita Inc., all rights reserved
Copyright: 2005-2013 John Lim
Copyright: 2014 Damien Regad, Mark Newnham and the ADOdb community
License: BSD-3-Clause
License: LGPL-2.1-or-later
File Size: 2400 lines (63 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 2 files
 lib/adodb/adodb-datadict.inc.php
 lib/adodb/adodb.inc.php

Defines 6 classes

dbObject:: (9 methods):
  __construct()
  _tag_open()
  _tag_cdata()
  _tag_close()
  create()
  destroy()
  supportedPlatform()
  prefix()
  fieldID()

dbTable:: (12 methods):
  __construct()
  _tag_open()
  _tag_cdata()
  _tag_close()
  addIndex()
  addData()
  addField()
  addFieldOpt()
  addTableOpt()
  addTableComment()
  create()
  drop()

dbIndex:: (8 methods):
  __construct()
  _tag_open()
  _tag_cdata()
  _tag_close()
  addField()
  addIndexOpt()
  create()
  drop()

dbData:: (7 methods):
  __construct()
  _tag_open()
  _tag_cdata()
  _tag_close()
  addField()
  addData()
  create()

dbQuerySet:: (10 methods):
  __construct()
  _tag_open()
  _tag_cdata()
  _tag_close()
  newQuery()
  discardQuery()
  buildQuery()
  addQuery()
  create()
  prefixQuery()

adoSchema:: (32 methods):
  __construct()
  setUpgradeMethod()
  existingData()
  executeInline()
  continueOnError()
  parseSchema()
  parseSchemaFile()
  parseSchemaString()
  removeSchema()
  removeSchemaString()
  executeSchema()
  printSQL()
  saveSQL()
  create_parser()
  _tag_open()
  _tag_cdata()
  _tag_close()
  convertSchemaString()
  convertSchemaFile()
  transformSchema()
  xslt_error_handler()
  schemaFileVersion()
  schemaStringVersion()
  extractSchema()
  setPrefix()
  prefix()
  supportedPlatform()
  clearSQL()
  addSQL()
  getSQL()
  destroy()
  logMsg()


Class: dbObject  - X-Ref

Abstract DB Object. This class provides basic methods for database objects, such
as tables and indexes.

__construct( $parent, $attributes = NULL )   X-Ref
NOP


_tag_open( $parser, $tag, $attributes )   X-Ref
XML Callback to process start elements


_tag_cdata( $parser, $cdata )   X-Ref
XML Callback to process CDATA elements


_tag_close( $parser, $tag )   X-Ref
XML Callback to process end elements


create(&$xmls)   X-Ref
No description

destroy()   X-Ref
Destroys the object


supportedPlatform( $platform = NULL )   X-Ref
Checks whether the specified RDBMS is supported by the current
database object or its ranking ancestor.

param: string $platform RDBMS platform name (from ADODB platform list).
return: boolean TRUE if RDBMS is supported; otherwise returns FALSE.

prefix( $name = '' )   X-Ref
Returns the prefix set by the ranking ancestor of the database object.

param: string $name Prefix string.
return: string Prefix.

fieldID( $field )   X-Ref
Extracts a field ID from the specified field.

param: string $field Field.
return: string Field ID.

Class: dbTable  - X-Ref

Creates a table object in ADOdb's datadict format

This class stores information about a database table. As charactaristics
of the table are loaded from the external source, methods and properties
of this class are used to build up the table description in ADOdb's
datadict format.

__construct( $parent, $attributes = NULL )   X-Ref
Iniitializes a new table object.

param: string $prefix DB Object prefix
param: array $attributes Array of table attributes.

_tag_open( $parser, $tag, $attributes )   X-Ref
XML Callback to process start elements. Elements currently
processed are: INDEX, DROP, FIELD, KEY, NOTNULL, AUTOINCREMENT & DEFAULT.


_tag_cdata( $parser, $cdata )   X-Ref
XML Callback to process CDATA elements


_tag_close( $parser, $tag )   X-Ref
XML Callback to process end elements


addIndex( $attributes )   X-Ref
Adds an index to a table object

param: array $attributes Index attributes
return: object dbIndex object

addData( $attributes )   X-Ref
Adds data to a table object

param: array $attributes Data attributes
return: object dbData object

addField( $name, $type, $size = NULL, $opts = NULL )   X-Ref
Adds a field to a table object

$name is the name of the table to which the field should be added.
$type is an ADODB datadict field type. The following field types
are supported as of ADODB 3.40:
- C:  varchar
- X:  CLOB (character large object) or largest varchar size
if CLOB is not supported
- C2: Multibyte varchar
- X2: Multibyte CLOB
- B:  BLOB (binary large object)
- D:  Date (some databases do not support this, and we return a datetime type)
- T:  Datetime or Timestamp
- L:  Integer field suitable for storing booleans (0 or 1)
- I:  Integer (mapped to I4)
- I1: 1-byte integer
- I2: 2-byte integer
- I4: 4-byte integer
- I8: 8-byte integer
- F:  Floating point number
- N:  Numeric or decimal number

param: string $name Name of the table to which the field will be added.
param: string $type    ADODB datadict field type.
param: string $size    Field size
param: array $opts    Field options array
return: array Field specifier array

addFieldOpt( $field, $opt, $value = NULL )   X-Ref
Adds a field option to the current field specifier

This method adds a field option allowed by the ADOdb datadict
and appends it to the given field.

param: string $field    Field name
param: string $opt ADOdb field option
param: mixed $value Field option value
return: array Field specifier array

addTableOpt( $opt )   X-Ref
Adds an option to the table

This method takes a comma-separated list of table-level options
and appends them to the table object.

param: string $opt Table option
return: array Options

addTableComment( $opt )   X-Ref
No description

create( &$xmls )   X-Ref
Generates the SQL that will create the table in the database

param: object $xmls adoSchema object
return: array Array containing table creation SQL

drop()   X-Ref
Marks a field or table for destruction


Class: dbIndex  - X-Ref

Creates an index object in ADOdb's datadict format

This class stores information about a database index. As charactaristics
of the index are loaded from the external source, methods and properties
of this class are used to build up the index description in ADOdb's
datadict format.

__construct( $parent, $attributes = NULL )   X-Ref
Initializes the new dbIndex object.

param: object $parent Parent object
param: array $attributes Attributes

_tag_open( $parser, $tag, $attributes )   X-Ref
XML Callback to process start elements

Processes XML opening tags.
Elements currently processed are: DROP, CLUSTERED, BITMAP, UNIQUE, FULLTEXT & HASH.


_tag_cdata( $parser, $cdata )   X-Ref
XML Callback to process CDATA elements

Processes XML cdata.


_tag_close( $parser, $tag )   X-Ref
XML Callback to process end elements


addField( $name )   X-Ref
Adds a field to the index

param: string $name Field name
return: string Field list

addIndexOpt( $opt )   X-Ref
Adds options to the index

param: string $opt Comma-separated list of index options.
return: string Option list

create( &$xmls )   X-Ref
Generates the SQL that will create the index in the database

param: object $xmls adoSchema object
return: array Array containing index creation SQL

drop()   X-Ref
Marks an index for destruction


Class: dbData  - X-Ref

Creates a data object in ADOdb's datadict format

This class stores information about table data, and is called
when we need to load field data into a table.

__construct( $parent, $attributes = NULL )   X-Ref
Initializes the new dbData object.

param: object $parent Parent object
param: array $attributes Attributes

_tag_open( $parser, $tag, $attributes )   X-Ref
XML Callback to process start elements

Processes XML opening tags.
Elements currently processed are: ROW and F (field).


_tag_cdata( $parser, $cdata )   X-Ref
XML Callback to process CDATA elements

Processes XML cdata.


_tag_close( $parser, $tag )   X-Ref
XML Callback to process end elements


addField( $attributes )   X-Ref
Adds a field to the insert

param: string $name Field name
return: string Field list

addData( $cdata )   X-Ref
Adds options to the index

param: string $opt Comma-separated list of index options.
return: string Option list

create( &$xmls )   X-Ref
Generates the SQL that will add/update the data in the database

param: object $xmls adoSchema object
return: array Array containing index creation SQL

Class: dbQuerySet  - X-Ref

Creates the SQL to execute a list of provided SQL queries

__construct( $parent, $attributes = NULL )   X-Ref
Initializes the query set.

param: object $parent Parent object
param: array $attributes Attributes

_tag_open( $parser, $tag, $attributes )   X-Ref
XML Callback to process start elements. Elements currently
processed are: QUERY.


_tag_cdata( $parser, $cdata )   X-Ref
XML Callback to process CDATA elements


_tag_close( $parser, $tag )   X-Ref
XML Callback to process end elements


newQuery()   X-Ref
Re-initializes the query.

return: boolean TRUE

discardQuery()   X-Ref
Discards the existing query.

return: boolean TRUE

buildQuery( $sql = NULL )   X-Ref
Appends a line to a query that is being built line by line

param: string $data Line of SQL data or NULL to initialize a new query
return: string SQL query string.

addQuery()   X-Ref
Adds a completed query to the query list

return: string    SQL of added query

create( &$xmls )   X-Ref
Creates and returns the current query set

param: object $xmls adoSchema object
return: array Query set

prefixQuery( $regex, $query, $prefix = NULL )   X-Ref
Rebuilds the query with the prefix attached to any objects

param: string $regex Regex used to add prefix
param: string $query SQL query string
param: string $prefix Prefix to be appended to tables, indices, etc.
return: string Prefixed SQL query string.

Class: adoSchema  - X-Ref

Loads and parses an XML file, creating an array of "ready-to-run" SQL statements

This class is used to load and parse the XML file, to create an array of SQL statements
that can be used to build a database, and to build the database using the SQL array.

__construct( $db )   X-Ref
Creates an adoSchema object

Creating an adoSchema object is the first step in processing an XML schema.
The only parameter is an ADOdb database connection object, which must already
have been created.

param: object $db ADOdb database connection object.

setUpgradeMethod( $method = '' )   X-Ref
Sets the method to be used for upgrading an existing database

Use this method to specify how existing database objects should be upgraded.
The method option can be set to ALTER, REPLACE, BEST, or NONE. ALTER attempts to
alter each database object directly, REPLACE attempts to rebuild each object
from scratch, BEST attempts to determine the best upgrade method for each
object, and NONE disables upgrading.

This method is not yet used by AXMLS, but exists for backward compatibility.
The ALTER method is automatically assumed when the adoSchema object is
instantiated; other upgrade methods are not currently supported.

param: string $method Upgrade method (ALTER|REPLACE|BEST|NONE)
returns: string Upgrade method used

existingData( $mode = NULL )   X-Ref
Specifies how to handle existing data row when there is a unique key conflict.

The existingData setting specifies how the parser should handle existing rows
when a unique key violation occurs during the insert. This can happen when inserting
data into an existing table with one or more primary keys or unique indexes.
The existingData method takes one of three options: XMLS_MODE_INSERT attempts
to always insert the data as a new row. In the event of a unique key violation,
the database will generate an error.  XMLS_MODE_UPDATE attempts to update the
any existing rows with the new data based upon primary or unique key fields in
the schema. If the data row in the schema specifies no unique fields, the row
data will be inserted as a new row. XMLS_MODE_IGNORE specifies that any data rows
that would result in a unique key violation be ignored; no inserts or updates will
take place. For backward compatibility, the default setting is XMLS_MODE_INSERT,
but XMLS_MODE_UPDATE will generally be the most appropriate setting.

param: int $mode XMLS_MODE_INSERT, XMLS_MODE_UPDATE, or XMLS_MODE_IGNORE
return: int current mode

executeInline( $mode = NULL )   X-Ref
Enables/disables inline SQL execution.

Call this method to enable or disable inline execution of the schema. If the mode is set to TRUE (inline execution),
AXMLS applies the SQL to the database immediately as each schema entity is parsed. If the mode
is set to FALSE (post execution), AXMLS parses the entire schema and you will need to call adoSchema::ExecuteSchema()
to apply the schema to the database.

param: bool $mode execute
return: bool current execution mode

continueOnError( $mode = NULL )   X-Ref
Enables/disables SQL continue on error.

Call this method to enable or disable continuation of SQL execution if an error occurs.
If the mode is set to TRUE (continue), AXMLS will continue to apply SQL to the database, even if an error occurs.
If the mode is set to FALSE (halt), AXMLS will halt execution of generated sql if an error occurs, though parsing
of the schema will continue.

param: bool $mode execute
return: bool current continueOnError mode

parseSchema( $filename, $returnSchema = FALSE )   X-Ref
Loads an XML schema from a file and converts it to SQL.

Call this method to load the specified schema (see the DTD for the proper format) from
the filesystem and generate the SQL necessary to create the database
described. This method automatically converts the schema to the latest
axmls schema version.
param: string $file Name of XML schema file.
param: bool $returnSchema Return schema rather than parsing.
return: array Array of SQL queries, ready to execute

parseSchemaFile( $filename, $returnSchema = FALSE )   X-Ref
Loads an XML schema from a file and converts it to SQL.

Call this method to load the specified schema directly from a file (see
the DTD for the proper format) and generate the SQL necessary to create
the database described by the schema. Use this method when you are dealing
with large schema files. Otherwise, parseSchema() is faster.
This method does not automatically convert the schema to the latest axmls
schema version. You must convert the schema manually using either the
convertSchemaFile() or convertSchemaString() method.
param: string $file Name of XML schema file.
param: bool $returnSchema Return schema rather than parsing.
return: array Array of SQL queries, ready to execute.

parseSchemaString( $xmlstring, $returnSchema = FALSE )   X-Ref
Converts an XML schema string to SQL.

Call this method to parse a string containing an XML schema (see the DTD for the proper format)
and generate the SQL necessary to create the database described by the schema.
param: string $xmlstring XML schema string.
param: bool $returnSchema Return schema rather than parsing.
return: array Array of SQL queries, ready to execute.

removeSchema( $filename, $returnSchema = FALSE )   X-Ref
Loads an XML schema from a file and converts it to uninstallation SQL.

Call this method to load the specified schema (see the DTD for the proper format) from
the filesystem and generate the SQL necessary to remove the database described.
param: string $file Name of XML schema file.
param: bool $returnSchema Return schema rather than parsing.
return: array Array of SQL queries, ready to execute

removeSchemaString( $schema, $returnSchema = FALSE )   X-Ref
Converts an XML schema string to uninstallation SQL.

Call this method to parse a string containing an XML schema (see the DTD for the proper format)
and generate the SQL necessary to uninstall the database described by the schema.
param: string $schema XML schema string.
param: bool $returnSchema Return schema rather than parsing.
return: array Array of SQL queries, ready to execute.

executeSchema( $sqlArray = NULL, $continueOnErr = NULL )   X-Ref
Applies the current XML schema to the database (post execution).

Call this method to apply the current schema (generally created by calling
parseSchema() or parseSchemaString() ) to the database (creating the tables, indexes,
and executing other SQL specified in the schema) after parsing.
param: array $sqlArray Array of SQL statements that will be applied rather than
param: boolean $continueOnErr Continue to apply the schema even if an error occurs.
returns: integer 0 if failure, 1 if errors, 2 if successful.

printSQL( $format = 'NONE' )   X-Ref
Returns the current SQL array.

Call this method to fetch the array of SQL queries resulting from
parseSchema() or parseSchemaString().

param: string $format Format: HTML, TEXT, or NONE (PHP array)
return: array Array of SQL statements or FALSE if an error occurs

saveSQL( $filename = './schema.sql' )   X-Ref
Saves the current SQL array to the local filesystem as a list of SQL queries.

Call this method to save the array of SQL queries (generally resulting from a
parsed XML schema) to the filesystem.

param: string $filename Path and name where the file should be saved.
return: boolean TRUE if save is successful, else FALSE.

create_parser()   X-Ref
Create an xml parser

return: object PHP XML parser object

_tag_open( $parser, $tag, $attributes )   X-Ref
XML Callback to process start elements


_tag_cdata( $parser, $cdata )   X-Ref
XML Callback to process CDATA elements


_tag_close( $parser, $tag )   X-Ref
XML Callback to process end elements


convertSchemaString( $schema, $newVersion = NULL, $newFile = NULL )   X-Ref
Converts an XML schema string to the specified DTD version.

Call this method to convert a string containing an XML schema to a different AXMLS
DTD version. For instance, to convert a schema created for an pre-1.0 version for
AXMLS (DTD version 0.1) to a newer version of the DTD (e.g. 0.2). If no DTD version
parameter is specified, the schema will be converted to the current DTD version.
If the newFile parameter is provided, the converted schema will be written to the specified
file.
param: string $schema String containing XML schema that will be converted.
param: string $newVersion DTD version to convert to.
param: string $newFile File name of (converted) output file.
return: string Converted XML schema or FALSE if an error occurs.

convertSchemaFile( $filename, $newVersion = NULL, $newFile = NULL )   X-Ref
Converts an XML schema file to the specified DTD version.

Call this method to convert the specified XML schema file to a different AXMLS
DTD version. For instance, to convert a schema created for an pre-1.0 version for
AXMLS (DTD version 0.1) to a newer version of the DTD (e.g. 0.2). If no DTD version
parameter is specified, the schema will be converted to the current DTD version.
If the newFile parameter is provided, the converted schema will be written to the specified
file.
param: string $filename Name of XML schema file that will be converted.
param: string $newVersion DTD version to convert to.
param: string $newFile File name of (converted) output file.
return: string Converted XML schema or FALSE if an error occurs.

transformSchema( $schema, $xsl, $schematype='string' )   X-Ref
No description

xslt_error_handler( $parser, $errno, $level, $fields )   X-Ref
Processes XSLT transformation errors

param: object $parser XML parser object
param: integer $errno Error number
param: integer $level Error level
param: array $fields Error information fields

schemaFileVersion( $filename )   X-Ref
Returns the AXMLS Schema Version of the requested XML schema file.

Call this method to obtain the AXMLS DTD version of the requested XML schema file.
param: string $filename AXMLS schema file
return: string Schema version number or FALSE on error

schemaStringVersion( $xmlstring )   X-Ref
Returns the AXMLS Schema Version of the provided XML schema string.

Call this method to obtain the AXMLS DTD version of the provided XML schema string.
param: string $xmlstring XML schema string
return: string Schema version number or FALSE on error

extractSchema( $data = FALSE, $indent = ' ', $prefix = '' , $stripprefix=false)   X-Ref
Extracts an XML schema from an existing database.

Call this method to create an XML schema string from an existing database.
If the data parameter is set to TRUE, AXMLS will include the data from the database
tables in the schema.

param: boolean $data include data in schema dump
param: string $indent indentation to use
param: string $prefix extract only tables with given prefix
param: boolean $stripprefix strip prefix string when storing in XML schema
return: string Generated XML schema

setPrefix( $prefix = '', $underscore = TRUE )   X-Ref
Sets a prefix for database objects

Call this method to set a standard prefix that will be prepended to all database tables
and indices when the schema is parsed. Calling setPrefix with no arguments clears the prefix.

param: string $prefix Prefix that will be prepended.
param: boolean $underscore If TRUE, automatically append an underscore character to the prefix.
return: boolean TRUE if successful, else FALSE

prefix( $name = '' )   X-Ref
Returns an object name with the current prefix prepended.

param: string    $name Name
return: string    Prefixed name

supportedPlatform( $platform = NULL )   X-Ref
Checks if element references a specific platform

param: string $platform Requested platform
returns: boolean TRUE if platform check succeeds

clearSQL()   X-Ref
Clears the array of generated SQL.


addSQL( $sql = NULL )   X-Ref
Adds SQL into the SQL array.

param: mixed $sql SQL to Add
return: boolean TRUE if successful, else FALSE.

getSQL( $format = NULL, $sqlArray = NULL )   X-Ref
Gets the SQL array in the specified format.

param: string $format Format
return: mixed SQL

destroy()   X-Ref
Destroys an adoSchema object.

Call this method to clean up after an adoSchema object that is no longer in use.

logMsg( $msg, $title = NULL, $force = FALSE )   X-Ref
Message logging function