File: Xyndravandria/Dyverath/Dataset.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\Update;
use Xyndravandria\Dyverath\Query\DeleteFrom;
use Xyndravandria\Dyverath\Query\Component\Statement\StatementListing\Where;
use Xyndravandria\Dyverath\Query\Component\Statement\StatementListing\UpdateStatement;
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 Dataset inside of a Data.
class Dataset extends RepresentingClass implements \Iterator {

   /// The Data a Dataset is inside of.
   /// <dl class = "type"><dt><b>%Type:</b></dt>
   /// <dd>Data</dd></dl>
   /// @private 
   private $Data;
   
   /// The @ref Dataset "Dataset's" value.
   /// <dl class = "type"><dt><b>%Type:</b></dt>
   /// <dd>stdClass</dd></dl>
   /// @private 
   private $Value;
   
   /// A Where being used to clearly spot the Dataset
   /// from its Table.
   /// <dl class = "type"><dt><b>%Type:</b></dt>
   /// <dd>Database</dd></dl>
   /// @private 
   private $Where;
   
   /// Generates Dataset::$Where if possible.
   /// @private
   private function GenerateWhere( ) {
      // TODO: Better algorithm to check whether the primary keys are contained within a Dataset.
      $EmptyMe = $PrimaryKey = $this->Data->Table( )->PrimaryKey( );
      foreach( \array_keys( \get_object_vars( $this->Value ) ) as $SelectedColumn )
         foreach( $EmptyMe as $Index => $EliminateMe )
            if( $SelectedColumn == $EliminateMe )
               unset( $EmptyMe[ $Index ] );
      if( empty( $EmptyMe ) ) { // The Table's primary keys are contained within a Dataset.
         $WhereComponent = array( );
         foreach( $PrimaryKey as $PrimaryKeyPart ) {
            empty( $WhereComponent ) || $WhereComponent[ ] = new Operator( 'AND' );
            $WhereComponent[ ] = new Statement( new Column( $PrimaryKeyPart ), new Operator( '=' ), new Value( $this->Value->$PrimaryKeyPart ) );
         }
         $this->Where = new Where( $WhereComponent );
      }
      return;
   }

   /// Creates a new instance of a Dataset.
   /// @public      
   /// @param stdClass $Values: The @ref Dataset
   /// "Dataset's" values.
   /// @param Data $Data: The Data a Dataset is inside of.
   public function __construct( \stdClass $Value, Data $Data ) {
      $this->Value = $Value;
      $this->ValueKeys = \array_keys( ( array )$Value );
      $this->Data = $Data;
      $this->GenerateWhere( );
      return;
   }
   
   /// Gets an element of Dataset::$Value by its column
   /// name.
   /// @public
   /// @param string $ColumnName: The column name to get
   /// the value of.
   /// @returns mixed or null
   public function Read( $ColumnName ) {
      //\settype( $ColumnName, 'string' );
      if( $this->ExceptionIfDeleted( ) )
         return;
      else
         return isset( $this->Value->$ColumnName ) ? $this->Value->$ColumnName : null;
      return;
   }

   /// Alias of Dataset::Read( ).
   public function __get( $ColumnName ) {
      return $this->Read( $ColumnName );
   }
   
   /// Sets a new value for an element of Dataset::$Value
   /// by its column name.
   /// @public
   /// @param string $ColumnName: The column name to set
   /// the value of.
   /// @param mixed $Value: The new value.
   public function Write( $ColumnName, $Value ) {
      //\settype( $ColumnName, 'string' );
      //\settype( $Value, 'string' ); // TODO: String conversion here?
      if( $this->ExceptionIfDeleted( ) )
         return;
      elseif( ! \in_array( $ColumnName, \array_keys( ( array )$this->Value ) ) )
         throw new XyndravandriaDyverathException( 'Column \'' . $ColumnName . '\' in $ColumnName is not contained in $this->Value.' );
      elseif( $this->Where == null )
         throw new XyndravandriaDyverathException( 'Unable to clearly spot this dataset from its table, since it does not contain a primary key value.' );
      elseif( \in_array( $ColumnName, $this->Data->Table( )->PrimaryKey( ) ) )
         throw new XyndravandriaDyverathException( 'Changing a primary key\'s value is not possible.' );
      else {
         $this->Data->Table( )->Database( )->Server( )->ExecuteQuery( new Update( $this->Data->Table( ), new UpdateStatement( array( new Statement( new Column( $ColumnName ), new Operator( '=' ), new Value( $Value ) ) ) ), $this->Where ) );
         $this->Value->$ColumnName = $Value;
      }
      return;
   }
   
   /// Alias of Dataset::Write( ).
   public function __set( $ColumnName, $Value ) {
      $this->Write( $ColumnName, $Value );
      return;
   }
        
   /// Deletes a Dataset.
   /// @public
   public function Delete( ) {
      if( $this->ExceptionIfDeleted( ) )
         return;
      elseif( $this->Where == null )
         throw new XyndravandriaDyverathException( 'Unable to clearly spot this dataset from its table, since it does not contain a primary key value.' );
      else {
         $this->Data->Table( )->Database( )->Server( )->ExecuteQuery( new DeleteFrom( $this->Data->Table( ), $this->Where ) );
         $this->Data->DeleteDataset( $this, false );
         $this->Data = null;
      }
      return;
   }
   
   /// Throws an exception if the Datatset is deleted.
   /// @public
   /// @returns boolean
   private function ExceptionIfDeleted( ) {
      if( $this->Data == null ) {
         throw new XyndravandriaDyverathException( 'This dataset has already been deleted.' );
         return true;
      } else
         return false;
   }
   
   /// Returns Dataset::$Value;
   /// @public 
   /// @returns stdClass
   public function ToStdClass( ) {
      if( $this->ExceptionIfDeleted( ) )
         return;
      else
         return $this->Value;  
   }
      
   /// Returns ( array )Dataset::$Value.
   /// @public
   /// @returns array of mixed
   public function ToArray( ) {
      if( $this->ExceptionIfDeleted( ) )
         return;
      else
         return ( array )$this->Value;
   }
   
   /// The keys of Dataset::$Value.
   /// <dl class = "return"><dt><b>%Type:</b></dt>
   /// <dd>array of string</dd></dl>
   /// @private 
   private $ValueKeys;
   
   /// The current position.
   /// <dl class = "return"><dt><b>%Type:</b></dt>
   /// <dd>integer</dd></dl>
   /// @private
   /// @note Required by the Iterator interface.
   private $Position = 0;

   /// Returns the current value.
   /// @public 
   /// @return Dataset or null
   /// @note Required by the Iterator interface.
   public function current( ) {
      if( $this->ExceptionIfDeleted( ) )
         return;
      else
         return isset( $this->Value->{$this->ValueKeys[ $this->Position ]} ) ? $this->Value->{$this->ValueKeys[ $this->Position ]} : null;
   }
   
   /// Returns the current position.
   /// @public
   /// @returns integer
   /// @note Required by the Iterator interface.
   public function key( ) {
      if( $this->ExceptionIfDeleted( ) )
         return;
      else
         return $this->ValueKeys[ $this->Position ];  
   }
   
   /// Moves forward to next element.
   /// @public 
   /// @note Required by the Iterator interface.
   public function next( ) {
      $this->ExceptionIfDeleted( ) || $this->Position < \count( $this->ValueKeys ) && ++$this->Position;
      return;
   }
   
   /// Rewinds the Iterator to the first element.
   /// @public
   /// @note Required by the Iterator interface.
   public function rewind( ) {
      $this->ExceptionIfDeleted( ) || $this->Position = 0;
      return;
   }
   
   /// Checks if current position is valid.
   /// @public 
   /// @return boolean
   /// @note Required by the Iterator interface.
   public function valid( ) {
      if( $this->ExceptionIfDeleted( ) )
         return;
      else
         return isset( $this->ValueKeys[ $this->Position ] );
   }
   
}
?>