Constants

Version

Version

Properties

$Version

$Version : string

Type

string — Readonly. The current SmartDatabase version number. Set in constructor. Needed for storing version in serialized objects. Changes for each change made to the SmartDatabase code

$DbManager

$DbManager : \DbManager

Type

\DbManager — The DbManager instance, passed in the class constructor

$DEV_MODE

$DEV_MODE : boolean

Development mode toggle. When true, does extra verifications (ie data types, columns, etc) that are a must for development, but may slow things down a bit when running in production.

In DEV mode, extra type checking takes place to verify you're setting values correctly. This helps with mostly with debugging, but also helps to avoid data corruption if you do something wrong. Once things seem to be up and going pretty well, you can set this to false for some performance improvement.

Type

boolean

$DEV_MODE_WARNINGS

$DEV_MODE_WARNINGS : boolean

Type

boolean — if true and in $DEV_MODE, warnings will be shown for like missing classes and etc.

$DefaultTimezone

$DefaultTimezone : string

Type

string — If this is a date column and a TimeZone is set on this column (or the database-level), then ALL datetime/timestamp values stored will be converted to UTC time for storing in the DB, then returned in the set timezone. Empty will use system time and won't touch dates (not recommended) There is a SmartDatabase level $DefaultTimezone, and also a SmartColumn $DefaultTimezone. If both values are set, the column's default will take precedence.

$XmlSchemaDateModified

$XmlSchemaDateModified : \date

The date the XML file used in LoadXmlSchema() was modified. If multiple XML Schemas are loaded, uses the latest of all.

Useful for serializing objects, storing them somewhere ($_SESSION, memcached, etc), then retrieving without needing to completely rebuild the database from xml

Type

\date

Methods

__construct()

__construct(array  $options = null, string  $deprecated = null) : \SmartDatabase

Constructor for a new SmartDatabse object. Note that you can cache these objects within Memcached so we don't have to parse the XML and create the structure for every request (@see SmartDatabase::GetCached()).

$options = array(
    'db-manager' => null, //DbManager - The DbManager instance that will be used to perform operations on the actual database. If null, no database operations can be performed (use for 'in-memory' instances)
    'xml-schema-file-path' => null, //string - the database schema file to load. If left null, you will need to either build the database yourself useing ->AddTable() or load a schema from XML using ->LoadSchema()
    'dev-mode' => true, //boolean - development mode toggle. When true, does extra verifications (ie data types, columns, etc) that are a must for development, but may slow things down a bit when running in production.
    'dev-mode-warnings' => true, //boolean. if true and in $DEV_MODE, warnings will be shown for like missing classes and etc.
    'default-timezone' => ''    //string (i.e. "GMT", "CST"). if set, sets the DefaultTimezone to this value . using "date('T')" will use php's default date timezone that is currently set and can be changed with a call to "date_default_timezone_set(...);". empty will use default system time (not recommended)
)

Parameters

array $options

[optional] see description above

string $deprecated

[optional] [deprecated] Use $options instead. This used to be the 'xml-schema-file-path' option

Returns

\SmartDatabase

GetAllTables()

GetAllTables() : array

Returns an assoc of all tables. The returned array's key=$tableName, value=$Table

Returns

array —

an assoc of all tables. The returned array's key=$tableName, value=$Table

GetTable()

GetTable(string  $tableName) : \SmartTable

Returns the Table instance matching the given $tableName. An exception is thrown if the table does not exist. Shortcut: use array notation- $databse['YOUR_TABLE_NAME']

Parameters

string $tableName

The name of the table to get.

Returns

\SmartTable

The Table instance matching the given $tableName. An exception is thrown if the table does not exist.

AddTable()

AddTable(\SmartTable  $Table) 

Adds a table to be managed by this Database. Replaces any table with the same name

Parameters

\SmartTable $Table

RemoveTable()

RemoveTable(string  $tableName) 

Removes a table from being managed by this Database.

Parameters

string $tableName

The name of the table to remove

RemoveAllTables()

RemoveAllTables() 

Removes all tables from being managed by this Database.

TableExists()

TableExists(string  $tableName) : boolean

Returns true if the table exists, false otherwise.

Parameters

string $tableName

the name of the table to look for

Returns

boolean —

true if the table exists, false otherwise.

LoadXmlSchema()

LoadXmlSchema(string  $xmlSchemaFilePath, array  $options = null) 

Loads a database schema from an XML file. This schema will replace any tables that are currently being managed by the Database instance.

$options is an assoc-array, as follows:

$options = array(
    'clear-current-schema'=false, //if set to true, all tables currently loaded within this instance will be removed (unmanaged. the actual table still exists in the real db). if false, the given $xmlSchemaFilePath is simply added to whatever is currently in this database instance (tables/properties with the same name are overwritten with the new schema)
);

Parameters

string $xmlSchemaFilePath

The path of the XML database schema file to load.

array $options

[optional] See description

WriteXmlSchema()

WriteXmlSchema(string  $xmlSchemaFilePath = null) : string

Gets the current database schema in XML format and optionally writes the XML to a file (specified in $xmlSchemaFilePath). The XML string is returned regardless.

Parameters

string $xmlSchemaFilePath

[optional] If provided, the new XML will overwrite the file at the specified path

Returns

string —

The current database schema in XML format

SyncStructureToDatabase()

SyncStructureToDatabase(boolean  $printResults = false, array  $options = null) : string

Synchronizes the structure of this Database instance to the SQL database connection in the DbManager

    $options = array(
        'debug-mode' => false, //if true, prints all Sync SQL instead of executing it
        'backup-tables' => true, //if true, creates a backup table before altering any existing tables
        'create' => true, //if true, tables and columns will be created if they do not exist
        'update' => true, //if true, existing SQL columns will be updated to match properties defined in the SmartDatabase
        'delete' => true, //if true, columns that do not exist on a SmartDb managed table will be removed (note: unmanaged TABLES are never deleted!)
    );

Parameters

boolean $printResults

[optional] If true, the results will be printed to the screen. (Results are returned regardless.)

array $options

[optional] See description above

Returns

string —

The results of the sync

ReadDatabaseStructure()

ReadDatabaseStructure(array  $options = null) 

Reads the current connected database's structure ($this->DbManager)

    $options = array(
        'preserve-current' => false, //if true, the current smart database structure will be preserved. existing tables/column will be overwritten by the db definitions
        'ignore-table-prefix' => 'backup_', //will not import tables that start with the given prefix
        'table' => null, //string - if provided, will only read the structure of the given table name
    )

Parameters

array $options

count()

count() : integer

For the Countable interface, this allows us to do count($database) to return the number of tables.

Returns

integer —

The number of tables in this database.

GetCached()

GetCached(array  $options = null) : \SmartDatabase

An alternative to calling "new SmartDatabase($options)" - uses memcached to get/save an entire SmartDb structure within cache. You must pass in at least the 'memcached-key' and 'xml-schema-file-path' options. Also, the returned SmartDb will not have it's DbManager set unless you pass the 'db-manager' option, so you may need to set it manually.

    //options are same as SmartDatabase constructor, plus a few extra for memcached
    $options = array(
        'db-manager' => null, //DbManager - The DbManager instance that will be used to perform operations on the actual database. If null, no database operations can be performed (use for 'in-memory' instances)
        'xml-schema-file-path' => null, //string - REQUIRED for caching - the database schema file to load. If left null, you will need to either build the database yourself useing ->AddTable() or load a schema from XML using ->LoadSchema()
        'default-timezone' => '' //if set, $SmartDb->DefaultTimezone will be set to this value
        'dev-mode' => true, //boolean - development mode toggle. When true, does extra verifications (ie data types, columns, etc) that are a must for development, but may slow things down a bit when running in production.
        'dev-mode-warnings' => true, //boolean. if true and in $DEV_MODE, warnings will be shown for like missing classes and etc.
        'memcached-key' => null, //string. REQUIRED for caching. memcached lookup key
        'memcached-host' => 'localhost', //string. memcached connection host
        'memcached-port' => 11211, //int. memcached connection port
        'memcached-timeout' => 250, //int. failover fast-ish
        'memcached-serializer' => Memcached::SERIALIZER_IGBINARY, //a much better serializer than the default one in PHP
        'memcached-compression' => true, //actually makes things faster too
    )

Parameters

array $options

[optional] see description above

Returns

\SmartDatabase

BuildDatabase()

BuildDatabase(array  $xmlAssoc) 

Builds the database from the given, validated, XML Assoc

Parameters

array $xmlAssoc

the xml database structure

BuildInheritedTables()

BuildInheritedTables(string  $tableName, array  $allInheritedTables, array  $queuedTables, array  $completedTables) : 

Makes sure inherited tables get built in the correct order. Also assures there are no "inheritance loops"

Parameters

string $tableName
array $allInheritedTables
array $queuedTables

[optional] Leave empty. Only used for recursions.

array $completedTables

[optional] Leave empty. Only used for recursions.

Returns

GetAssocFromXml()

GetAssocFromXml(string  $xmlPath, string  $xsdFilePath = null) : array

parses the XML file into a structured assoc array

Parameters

string $xmlPath

path of the xml file to parse

string $xsdFilePath

path of the xsd schema file for verifying the xml is valid

Returns

array —

parses the XML file into a structured assoc array

Xml2assoc()

Xml2assoc(string  $xml) : array

Parameters

string $xml

xml to parse

Returns

array —

helper, recursive function for GetAssocFromXml

IsXmlFileValid()

IsXmlFileValid(string  $xmlFilePath, string  $schemaFilePath) : boolean

Returns true if the XML file given in the constructor of this class validates with the schema, false if the XML is invalid.

Parameters

string $xmlFilePath

path of the xml file to parse

string $schemaFilePath

path of the xsd schema file for verifying the xml is valid

Returns

boolean —

true if the XML file given in the constructor of this class validates with the schema, false if the XML is invalid.

BuildSyncStructure()

BuildSyncStructure()