<?php
// TODO: Complete documentation.
/*!
@mainpage
%Xyndravandria is the name of a collection of projects designed and developed by Mauro Di Girolamo (maurodigirolamo@web.de); he is therefore the copyright (c) owner of %Xyndravandria itself and all of its projects.
%Xyndravandria Dyverath is released under the terms of the %Xyndravandria PHP License (XyndravandriaPHPLicense.txt). You should be given a copy of the %Xyndravandria PHP License (XyndravandriaPHPLicense.txt) within the same directory as the README.md; if not, you can get a copy at http://Xyndravandria.ohost.de/XyndravandriaPHPLicense.txt . There might be a release under a freer license for a later, more stable version.
All projects:
<table>
<tr>
<th>Project</th>
<th>Language</th>
<th>Description</th>
</tr>
<tr>
<td>%Xyndravandria Averazain<br>http://github.com/MauroDiGirolamo/Xyndravandria_Averazain</td>
<td>PHP</td>
<td>Averazain is an Ajax framework supporting also JavaScript disabled clients perfectly - including search engines like Google.</td>
</tr>
<tr>
<td>%Xyndravandria Dyverath<br>http://github.com/MauroDiGirolamo/Xyndravandria_Dyverath</td>
<td>PHP</td>
<td>Dyverath is a database access wrapper.</td>
</tr>
<tr>
<td>%Xyndravandria Erozaver<br>http://github.com/MauroDiGirolamo/Xyndravandria_Erozaver</td>
<td>PHP</td>
<td>Erozaver is a class extending the type hinting given by the PHP engine (additional support for basic type hinting and size constraints).</td>
</tr>
<tr>
<td>%Xyndravandria Mondraviel<br>http://github.com/MauroDiGirolamo/Xyndravandria_Mondraviel</td>
<td>PHP</td>
<td>Mondraviel is a class used to separate HTML from PHP code by firstly register models - files containing place holders embedded in HTML code - and then later fill them dynamically with content by passing values for the place holders.</td>
</tr>
</table>
In the following, the usage of Dyverath will be explained roughly; if you would like to know more detailled information, you can take a look at the in-depth documentation by browsing through either the namespaces or the data structures in the navigation above.
@section S1 I. Overview
%Dyverath is a database access wrapper. It aims to quicken working with databases by representing a database system and its components with PHP classes.
@section S2 II. Basics
Open a connection to a database by using @ref Xyndravandria::Dyverath::Dyverath::Connect( ) "Dyverath::Connect( )"; you will be returned a @ref Xyndravandria::Dyverath::Server "Server" object. @n
@verbatim $Server = Dyverath::Connect( 'localhost', 'User', 'Password' ); @endverbatim
You can access a database on a server by using the magic @ref Xyndravandria::Dyverath::Server::__get( ) "Server::__get( )" method of that @ref Xyndravandria::Dyverath::Server "Server" object. This time, a @ref Xyndravandria::Dyverath::Database "Database" object will be returned.
@verbatim $ForumDatabase = $Server->Forum; // Assuming there is a database called 'Forum' on your server. @endverbatim
Now, you can continue with accessing a table of that database by making use of the @ref Xyndravandria::Dyverath::Database::__get( ) "Database::__get( )" method. You are returned a @ref Xyndravandria::Dyverath::Table "Table" object.
@verbatim $UserTable = $ForumDatabase->User; // Assuming there is a table called 'User' within a database called 'Forum'. @endverbatim
@section S3 III. Magic methods are always only aliases
The caption is meaningful enough. Take a look at the in-depth documentation of all the magic methods to see the actual methods called. One example: @ref Xyndravandria::Dyverath::Table::__invoke( ) "Table::__invoke( )" is actually an alias of @ref Xyndravandria::Dyverath::Table::DatasetByPrimaryKey( ) "Table::DatasetByPrimaryKey( )". @n
This is not only due to the fact that some server's PHP version might not support magic methods (if you are given such a server, then sorry - in this documentation, I am always using the magic methods and not their aliases), but also when thinking of invalid characters of method names in coherence with __call( ), __get( ) and __set( ): Imagine you have a database called "The Forum Database". Now, calling @verbatim $Server->The Forum Database @endverbatim to get a @ref Xyndravandria::Dyverath::Database "Database" object is obviously invalid. @n
Therefore, you can also use @verbatim $Server->Database( 'The Forum Database' ) @endverbatim
@section S4 IV. Generating the components of a query
At this point, I would like you to give you an overview of how the components of a query are built in Dyverath. @n
Just click on the links of the following listing and you bill be lead to the separate document page. There, you should read the detailed description where the usage should be explained. @n
For the best understanding, please read the documentations on the order of the following list:
<ul>
<li>@ref Xyndravandria::Dyverath::Query::Component::Type::Column "Xyndravandria::Dyverath::Query::Component::Type::Column"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Type::ConstantValue "Xyndravandria::Dyverath::Query::Component::Type::ConstantValue"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Type::Limit "Xyndravandria::Dyverath::Query::Component::Type::Limit"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Type::Operator "Xyndravandria::Dyverath::Query::Component::Type::Operator"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Type::Value "Xyndravandria::Dyverath::Query::Component::Type::Value"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Statement::Statement "Xyndravandria::Dyverath::Query::Component::Statement::Statement"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Statement::StatementListing::Where "Xyndravandria::Dyverath::Query::Component::Statement::StatementListing::Where"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Statement::StatementListing::InsertIntoStatement "Xyndravandria::Dyverath::Query::Component::Statement::StatementListing::InsertIntoStatement"</li>
<li>@ref Xyndravandria::Dyverath::Query::Component::Statement::StatementListing::UpdateStatement "Xyndravandria::Dyverath::Query::Component::Statement::StatementListing::UpdateStatement"</li>
</ul>
@section S5 V. Selecting data
<ul>
<li>@ref Xyndravandria::Dyverath::Table::Data( ) "Table::Data( )"</li>
<li>@ref Xyndravandria::Dyverath::Data::Dataset( ) "Data::Dataset( )"</li>
<li>@ref Xyndravandria::Dyverath::Dataset::__get( ) "Dataset::__get( )" (@ref Xyndravandria::Dyverath::Dataset::Read( ) "Dataset::Read( )")</li>
<li>@ref Xyndravandria::Dyverath::Data "Data" implements Iterator ( [Number of result] => [Dataset] )</li>
<li>@ref Xyndravandria::Dyverath::Dataset "Dataset" implements Iterator ( [Column name] => [Value] )</li>
</ul>
@section S6 VI. Updating data
<ul>
<li>@ref Xyndravandria::Dyverath::Data::UpdateColumnTotal( ) "Data::UpdateColumnTotal( )"</li>
<li>@ref Xyndravandria::Dyverath::Dataset::__set( ) "Dataset::__set( )" (@ref Xyndravandria::Dyverath::Dataset::Write( ) "Dataset::Write( )")</li>
</ul>
@section S7 VII. Inserting data
<ul>
<li>@ref Xyndravandria::Dyverath::Table::Insert( ) "Table::Insert( )"</li>
</ul>
@section S8 VIII. Deleting data
<ul>
<li>@ref Xyndravandria::Dyverath::Data::Delete( ) "Data::Delete( )"</li>
<li>@ref Xyndravandria::Dyverath::Data::DeleteDataset( ) "Data::DeleteDataset( )"</li>
<li>@ref Xyndravandria::Dyverath::Dataset::Delete( ) "Dataset::Delete( )"</li>
</ul>
@section S9 IX. Working with primary keys
As you might noticed before, you can read out a dataset directly if you pass a primary key value to either a @ref Xyndravandria::Dyverath::Database "Database" object - optional parameter of @ref Xyndravandria::Dyverath::Database::Table( ) "Database::Table( )" - or a @ref Xyndravandria::Dyverath::Table "Table" object - magic method @ref Xyndravandria::Dyverath::Table::__invoke( ) "Table::__invoke( )".
@verbatim
--
-- DummyData.sql
--
CREATE DATABASE IF NOT EXISTS `Forum`;
CREATE TABLE IF NOT EXISTS `Forum`.`User` (
`ID` INT( 11 ) NOT NULL DEFAULT -1,
`Name` VARCHAR( 255 ) NOT NULL DEFAULT '',
`Age` INT( 3 ) NOT NULL DEFAULT -1,
PRIMARY KEY( `ID` )
) ;
INSERT INTO `Forum`.`User` ( `User`.`ID`, `User`.`Name`, `User`.`Age` ) VALUES ( 20, 'Peter "o Clock', 18 );
@endverbatim
<br>
@verbatim
<?php
######################
# PrimaryKey.php #
######################
require_once( 'Xyndravandria/Dyverath/Implement.php' );
use Xyndravandria\Dyverath\Dyverath;
$Server = Dyverath::Connect( 'localhost', 'Kaze', 'Kaze' ); // Needs modification.
$ForumDatabase = $Server->Forum;
$UserTable = $ForumDatabase->User;
$UserDataset = $UserTable( 20 ); // Primary key = ID = 20
echo 'Hello, ' . $UserDataset->Name . '!<br>';
$UserDataset->Name = 'Dominic'; // This _will_ change the MySQL table and not only the PHP object (value of the `Name` column from 'Peter "o Clock' to 'Dominic').
echo 'Your name is now ' . $UserDataset->Name . '.';
?>
@endverbatim
A primary key may also consist of more than one column.
@verbatim
$NewsDataset = $WebsiteDatabase->News( array( 3, 'Welcome' ) ); // Maybe you have a table called 'News' with a primary key consisting of both an id and a title column.
@endverbatim
@section S10 IV. Building a whole query manually
In the following, a whole query will be built manually. Please note that this is not how Dyverath is thought to work! This is just if you want to make a very long query which is not yet supported to make with Dyverath, but of course might be added later.
@verbatim
--
-- DummyData.sql
--
CREATE DATABASE IF NOT EXISTS `Forum`;
CREATE TABLE IF NOT EXISTS `Forum`.`User` (
`ID` INT( 11 ) NOT NULL DEFAULT -1,
`Name` VARCHAR( 255 ) NOT NULL DEFAULT '',
`Age` INT( 3 ) NOT NULL DEFAULT -1,
PRIMARY KEY( `ID` )
) ;
INSERT INTO `Forum`.`User` ( `User`.`ID`, `User`.`Name`, `User`.`Age` ) VALUES ( 20, 'Peter "o Clock', 18 );
@endverbatim
<br>
@verbatim
<?php
#################
# Query.php #
#################
require_once( 'Xyndravandria/Dyverath/Implement.php' );
use Xyndravandria\Dyverath\Dyverath;
use Xyndravandria\Dyverath\Query\Select;
use Xyndravandria\Dyverath\Query\Component\Type\Column;
use Xyndravandria\Dyverath\Query\Component\Type\Operator;
use Xyndravandria\Dyverath\Query\Component\Type\Value;
use Xyndravandria\Dyverath\Query\Component\Type\Limit;
use Xyndravandria\Dyverath\Query\Component\Statement\StatementListing\Where;
use Xyndravandria\Dyverath\Query\Component\Statement\Statement;
$Server = Dyverath::Connect( 'localhost', 'Kaze', 'Kaze' ); // Needs modification.
$ForumDatabase = $Server->Forum;
$UserTable = $ForumDatabase->User;
$Column = new Column( array( 'Birthday', array( 'Age' => 'The Age' ) ) );
$Where = new Where( array( new Statement( new Column( 'Name' ), new Operator( '=' ), new Value( 'Peter "o Clock' ) ), new Operator( 'AND' ), new Statement( new Column( 'ID' ), new Operator( '>' ), new Value( 10 ) ) ) );
$OrderBy = new Column( array( 'ID' => Column::Ascending ) );
$Limit = new Limit( '1' );
$Select = new Select( $Column, $UserTable, $Where, $OrderBy, $Limit );
echo $Select;
?>
@endverbatim
will output this perfectly optimised query with escaped values:
@verbatim SELECT `User`.`Birthday`, `User`.`Age` AS `The Age` FROM `Forum`.`User` WHERE `Name` = 'Peter \"o Clock' AND `ID` > 10 ORDER BY `User`.`ID` ASC LIMIT 1 @endverbatim
*/
?> |
Stumble It!
Bookmark in del.icio.us
Download
