File: Xyndravandria/Dyverath/Table.php

<?php
/*
=============================================================================================================================================
|   This file is part of a project 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 .                                               |
|                                                                                                                                           |
|   The copyright (c) of this project is owned by Mauro Di Girolamo <maurodigirolamo@.web.de>.                                              |
============================================================================================================================================|



Xyndravandria Dyverath
----------------------
Alpha 0.0.0

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.

The documentation is either included in ./admin_media/Documentation/ or can be read at http://Xyndravandria.ohost.de/Dyverath/Documentation/.

All projects:

   Xyndravandria Averazain
   http://github.com/MauroDiGirolamo/Xyndravandria_Averazain
   PHP
   Averazain is an Ajax framework supporting also JavaScript disabled clients perfectly - including search engines like Google.
   
   Xyndravandria Dyverath
   http://github.com/MauroDiGirolamo/Xyndravandria_Dyverath
   PHP
   Dyverath is a database access wrapper.
   
   Xyndravandria Erozaver
   http://github.com/MauroDiGirolamo/Xyndravandria_Erozaver
   PHP
   Erozaver is a class extending the type hinting given by the PHP engine (additional support for basic type hinting and size constraints).
   
   Xyndravandria Mondraviel
   http://github.com/MauroDiGirolamo/Xyndravandria_Mondraviel
   PHP
   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.
*/

namespace Xyndravandria\Dyverath;

use Xyndravandria\Dyverath\Query\Query;
use Xyndravandria\Dyverath\Query\InsertInto;
use Xyndravandria\Dyverath\Query\Component\Statement\StatementListing\Where;
use Xyndravandria\Dyverath\Query\Component\Statement\StatementListing\InsertIntoStatement;
use Xyndravandria\Dyverath\Query\Component\Statement\Statement;
use Xyndravandria\Dyverath\Query\Component\Type\Column;
use Xyndravandria\Dyverath\Query\Component\Type\Operator;
use Xyndravandria\Dyverath\Query\Component\Type\Value;

/// A class representing a Table inside of a Database.
class Table extends ExtendedRepresentingClass {
                         
   /// A reference to the Database a Table is inside of.
   /// <dl class = "type"><dt><b>%Type:</b></dt>
   /// <dd>Database</dd></dl>
   /// @private      
   private $Database = null;
   
   /// Returns Table::$Database.
   /// @public
   /// @returns Database
   public function Database( ) {
      return $this->Database;
   }
   
   /// A @ref Table "Table's" primary key. @n
   /// The reason for being an array is that a primary
   /// key can consist of more than one column by its
   /// definition in MySQL.
   /// <dl class = "type"><dt><b>%Type:</b></dt>
   /// <dd>array of string</dd></dl>
   /// @private      
   private $PrimaryKey = array( );
   
   /// Returns Table::$PrimaryKey.
   /// @public      
   /// @returns array of string
   public function PrimaryKey( ) {
      return $this->PrimaryKey;
   }
   
   /// Reads out a @ref Table "Table's" primary key from
   /// the information schema and saves it into
   /// Table::$PrimaryKey if it exists.
   /// @private
   private function ReadOutPrimaryKey( ) {
      if( ( $Result = $this->Database->Server( )->ExecuteQuery( new Query( 'SELECT `KEY_COLUMN_USAGE`.`COLUMN_NAME` FROM `INFORMATION_SCHEMA`.`KEY_COLUMN_USAGE` WHERE `KEY_COLUMN_USAGE`.`TABLE_NAME` = \'' . \mysql_real_escape_string( $this->Name ) . '\' AND `KEY_COLUMN_USAGE`.`TABLE_SCHEMA` = \'' . \mysql_real_escape_string( $this->Database->Name ) . '\' LIMIT 1' ) ) ) )
         while( $Dataset = \mysql_fetch_object( $Result ) )
            $this->PrimaryKey[ ] = $Dataset->COLUMN_NAME;
      return;
   }
   
   /// Creates a new instance of a Table. @n
   /// Automatically calls @ref ReadOutPrimaryKey( ).
   /// @public
   /// @param string $Name: The name is of the Table.
   /// @param Database $Database: A reference to the
   /// Database this Table is inside of.
   public function __construct( $Name, Database $Database ) {
      //\settype( $Name, 'string' );
      parent::__construct( $Name );
      $this->Database = $Database;
      $this->ReadOutPrimaryKey( );
      return;
   }
   
   /// Returns a @ref Table "Table's" columns.
   /// @public
   /// @returns array of string
   public function Columns( ) { // TODO: Don't read them out every call?
      $Column = array( );
      if( ! ( $Result = $this->Database->Server( )->ExecuteQuery( new Query( 'SELECT `COLUMNS`.`COLUMN_NAME` FROM `INFORMATION_SCHEMA`.`COLUMNS` WHERE `COLUMNS`.`TABLE_NAME`= \'' . \mysql_real_escape_string( $this->Name ) . '\'' ) ) ) )
         throw new XyndravandriaDyverathException( 'Unable to read out the columns of the table \'' . $this->Name . '\' from the information schema.' );
      else
         while( $Dataset = \mysql_fetch_object( $Result ) )
            $Column[ ] = $Dataset->COLUMN_NAME;
      return $Column;
   }
   
   /// Reads out Data of a Table.
   /// @public
   /// @param Column $Column: The columns whose values
   /// will be read out.
   /// @param Where $Where: The WHERE clause used to read
   /// out the Data.
   /// @param Column $OrderBy: The ORDER BY clause used
   /// to read out the Data.
   /// @param Limit $Limit: The LIMIT clause used to read out
   /// the Data.
   /// @returns Data
   /// @note $Column, $Where, $Limit and $OrderBy are
   /// optional parameters. @n
   /// That said,
   /// @verbatim $Data = $Table::Data( ); @endverbatim
   /// is possible and will read out all the data of a
   /// table. @n
   /// Furthermore, $Column may contain a Where:
   /// @verbatim Table::Data( $Where, $OrderBy, $Limit ) == Table::Data( new Column( Column::AllColumns ), $Where, $OrderBy, $Limit ) @endverbatim
   public function Data( $Column = null, Where $Where = null, Column $OrderBy = null, Limit $Limit = null ) {
      if( \is_null( $Column ) || ( $Column instanceof Where && ( $Where == null || $Where instanceof Limit ) ) ) {
         $OrderBy = $Limit;
         $Limit = $Where;
         $Where = $Column;
         $Column = new Column( Column::AllColumns );
      }
      return new Data( $this, $Column, $Where, $OrderBy, $Limit );
   }
   
   /// Gets a Dataset by the values of a primary key's
   /// columns.
   /// @public
   /// @param array of mixed or mixed
   /// $Values: The values of the primary key's columns.
   /// @returns Dataset or null
   public function DatasetByPrimaryKey( $Values ) { // TODO: Type check of $Values?
      \is_array( $Values ) || $Values = array( $Values );
      if( empty( $this->PrimaryKey ) )
         throw new XyndravandriaDyverathException( 'This Table has no primary key.' );
      elseif( \count( $Values ) != \count( $this->PrimaryKey ) )
         throw new XyndravandriaDyverathException( 'Assigment missmatch: There are not as many $Values as the Table\'s primary key has columns.' );
      else {
         $Statement = array( );
         foreach( $Values as $Index => $Value )
            $Statement[ ] = new Statement( new Column( $this->PrimaryKey[ $Index ] ), new Operator( '=' ), new Value( $Value ) );
         $Data = new Data( $this, new Column( Column::AllColumns ), new Where( $Statement ) );
         return $Data->Dataset( 0 );
      }
      return null;
   }

   /// Alias of DatasetByPrimaryKey( ).
   public function __invoke( $Value ) {
      // TODO: Not working properly?
      /*
      $IndexDatasetsOrphaned = Database::Current( )->Index->Data( )->Dataset( );
      foreach( $IndexDatasetsOrphaned as $IndexDataset )
         $IndexDatasets[ ] = Database::Current( )->Index( $IndexDataset->ID );
      */
      return $this->DatasetByPrimaryKey( $Value );
   }
      
   /// Insert a new dataset in a Table.
   /// @public
   /// @param $Dataset: The dataset to be added to the
   /// Table.
   /// @note $Dataset can either contain an associative
   /// array (keys = column names) or an object
   /// (attribute names = column names). Both data
   /// structures will be looped over using foreach( ).
   public function Insert( $Dataset ) {
      if( ! \is_array( $Dataset ) && ! \is_object( $Dataset ) )
         throw new XyndravandriaDyverathException( 'The type of $Dataset has to be either an associative array or an object.' );
      else {
         $Statements = array( );
         foreach( $Dataset as $Column => $Value )
            if( ! \in_array( $Column, $this->Columns( ) ) ) {
               throw new XyndravandriaDyverathException( 'Unknown column \'' . $Column . '\' in $Dataset.' );
               return;
            } else
               $Statements[ ] = new Statement( new Column( $Column ), new Operator( '=' ), new Value( $Value ) );  
         $this->Database->Server( )->ExecuteQuery( new InsertInto( $this, new InsertIntoStatement( $Statements ) ) );
      }
      return;
   }
      
   /// Returns a \ref Table "Table's" optimised name to
   /// be used in a Query: `Database`.`Table`.
   /// @public
   /// @returns string
   /// @note Overrode ExtendedRepresentingClass::__ToString( ).
   public function __ToString( ) {
      return '`'. $this->Database( )->Name . '`.`' . $this->Name . '`';
   }
   
   /// Alias of Table::Cache( )->CurrentObject( ).
   /// @public
   /// @static
   /// @returns Table
   public static function Current( ) {
      return self::Cache( )->CurrentObject( );
   }
   
   /// Returns a @ref Table "Table's" unique identifier.
   /// @public
   /// @returns string
   /// @note Overrode ExtendedRepresentingClass::UniqueIdentifier( ).
   public function UniqueIdentifier( ) {
      return $this->Database->Name( ) . '->' . $this->Name;
   }
   
   /// Returns the declared name of a class.
   /// @public      
   /// @static      
   /// @returns string
   /// @note Required by the CacheAble interface.
   public static function ClassName( ) {
      return __CLASS__;
   }

}
?>