About
News
Downloads
Manual
Support
Examples
Releases
Community
Contact
Blog
Sources for file docs/database.txt in version 4.0 Beta 1
Click on a comment to hide it. Click here to show all comments.
Database Abstraction Layer
XnyoDB::add($type, $alias, $database)
Description:
Adds a new database to the list of ones we have configured. Xnyo will use these when trying to
figure out how
to connect to a database
Arguments:
type
The type of database to be used. This should be one of the supported database type constants (eg
XNYO_DATABASE_PGSQL or XNYO_DATABASE_MYSQL).
Alternatively this can be a string representing the class name of a plugin. This plugin needs to
implement the XnyoDatabasePlugin interface and
reside in a database plugin directory.
alias
The alias for this database. Xnyo will use this to group all related settings for this database.
You will also need to include this alias
when using XnyoDB::set_host(), XnyoDB::set_credentials() and when specifying a database in a
DbSpec plugin.
database
The actual name of the database as your database server knows it. Xnyo will use this when
connecting to the database.
Returns:
(bool) true
Debug:
A message indicating the addition of an item to the database list will be logged in the debug
console should debugging be enabled.
Example:
<?php
// load xnyo
$xnyo = new Xnyo;
// will connect to the MySQL database "mydatabase" on localhost when needed
$db->add(XNYO_DATABASE_MYSQL, 'mydb', 'mydatabase');
?>
XnyoDB::set_host ($alias, $host, $port=null)
Description:
Sets the database server details needed to connect to a server. Not calling this method will
invoke the defaults for the selected database driver.
Arguments:
alias
The alias for the database that you specified when you called XnyoDB::add(). Xnyo will look in
the database list for this value and set the
connection details if found.
host
The hostname for the database server. Will default to localhost in most cases if not set.
port (optional)
The port that the database server is listening on. Will default to the normal port for the
database type if not set.
Returns:
(bool) true
Exceptions:
This method will throw a XnyoError should the specified alias not be found.
Debug:
A message indicating the addition of the host/port to the database list will be logged in the
debug console should debugging be enabled.
Example:
$xnyo = new Xnyo;
// will connect to the MySQL database "mydatabase" on localhost when needed
$db->add(XNYO_DATABASE_MYSQL, 'mydb', 'mydatabase');
// these are the default values should this not be called
$db->set_host('mydb', 'localhost', 3306);
?>
XnyoDB::set_credentials ($alias, $user, $pass=null);
Description:
Sets the credentials necessary to talk with the specified database server. Not calling this method
will invoke the defaults for the selected database driver.
Arguments:
alias
The alias for the database that you specified when you called XnyoDB::add(). Xnyo will look in
the database list for this value and set the
connection details if found.
user
The username necessary to connect to the database. Will likely default to the username of the
web server user. Check the docs for the database
driver.
pass (optional)
The password necessary to connect to the database. Some database types will permit a blank
password, which is what it will default to should
this not be set.
Returns:
(bool) true
Exceptions:
This method will throw a XnyoError should the specified alias not be found.
Debug:
A messaging indicating the addition of the supplied credentials to the database list will be
logged in the debug console should debugging be enabled.
Example:
$xnyo = new Xnyo;
// will connect to the MySQL database "mydatabase" on localhost when needed
$db->add(XNYO_DATABASE_MYSQL, 'mydb', 'mydatabase');
// defaults
$db->set_host('mydb', 'localhost', 3306);
// authenticate as myuser
$db->set_credentials('mydb', 'myuser', 'mypass');
?>
XnyoDB::swap ($table)
Description:
This method will load up a DbSpec plugin matching the supplied tablename. This name is really
another alias, as the DbSpec plugin can abstract the
real table name from the code, should you need to change it. For more info see DbSpec plugins.
The XnyoDB::swap() method will add the specified table as its active connection and silently
connect to the database in the background.
Any of the XnyoDB method calls that require a table object will use the table specified in the
last XnyoDB::swap() call.
Additional calls to XnyoDB::swap() will re-use existing connections and tables where possible.
Arguments:
table
A string representing a DbSpec plugin class. This class needs to extend XnyoActiveRecord and
implement XnyoDbSpecPlugin and reside in a dbspec
plugin directory.
Returns:
(bool) true
Exceptions:
This method can throw any number of exceptions from being unable to locate and load the specified
DbSpec plugin, to invalid DbSpec configurations,
missing or incorrect database aliases, and problems connecting to the database.
Debug:
This method will log many messages in the debug console should debugging be enabled. These include
loading the DbSpec plugin, swapping active connections,
connecting to the database, re-using existing tables and connections.
Example:
// load Xnyo
$xnyo = new Xnyo;
// Use the MySQL database "mydatabase"
$db->add(XNYO_DATABASE_MYSQL, 'mydb', 'mydatabase');
// Specify connection details - these are the defaults
$db->set_host('mydb', 'localhost', 3306);
// Specify authentication information
$db->set_credentials('mydb', 'myuser', 'mypass');
// We want to use the 'person' table.
$db->swap('person');
?>
XnyoDB::spawn ($table)
Description:
This method will load up a DbSpec plugin matching the supplied tablename. This name is really
another alias, as the DbSpec plugin can abstract the
real table name from the code, should you need to change it. For more info see DbSpec plugins.
The XnyoDB::spawn() method will return a XnyoActiveRecord based table object that will function
independently from the XnyoDB object. It will however
intelligently re-use the existing connections to the database to avoid additional overhead. For
more details on the results returned from this
class see the XnyoActiveRecord documentation. Additional calls to XnyoDB::swap() will re-use
existing connections and tables where possible.
One can also trigger an identical process by using the shorter syntax $var = new <tablealias>();
Read More.
Arguments:
table
A string representing a DbSpec plugin class. This class needs to extend XnyoActiveRecord and
implement XnyoDbSpecPlugin and reside in a dbspec
plugin directory.
Returns:
An instance of the DbSpec plugin. This has all the functionality of a XnyoActiveRecord object.
Exceptions:
This method can throw any number of exceptions from being unable to locate and load the specified
DbSpec plugin, to invalid DbSpec configurations,
missing or incorrect database aliases, and problems connecting to the database.
Debug:
This method will log many messages in the debug console should debugging be enabled. These include
loading the DbSpec plugin, creating an additional instance,
connecting to the database, re-using existing tables and connections.
Example:
// load Xnyo
$xnyo = new Xnyo;
// Use the MySQL database "mydatabase"
$db->add(XNYO_DATABASE_MYSQL, 'mydb', 'mydatabase');
// Specify connection details - these are the defaults
$db->set_host('mydb', 'localhost', 3306);
// Specify authentication information
$db->set_credentials('mydb', 'myuser', 'mypass');
// We want to use the 'person' table.
$person = $db->spawn('person');
// This is identical to the line above. See the XnyoActiveRecord docs.
$person = new Person();
?>
/****************************\
* Internally Used Functions *
\****************************/
/****************\
* PDO Functions *
\****************/
/*************************\
* ActiveRecord Functions *
\*************************/