<?php



/**

 * @file CAS/PGTStorage/pgt-file.php

 * Basic class for PGT file storage

 */



/**

 * @class PGTStorageFile

 * The PGTStorageFile class is a class for PGT file storage. An instance of 

 * this class is returned by CASClient::SetPGTStorageFile().

 *

 * @author Pascal Aubry <pascal.aubry at univ-rennes1.fr>

 *

 * @ingroup internalPGTStorageFile

 */



class PGTStorageFile extends PGTStorage

{

  /** 

   * @addtogroup internalPGTStorageFile 

   * @{ 

   */



  /**

   * a string telling where PGT's should be stored on the filesystem. Written by

   * PGTStorageFile::PGTStorageFile(), read by getPath().

   *

   * @private

   */

  var $_path;



  /**

   * This method returns the name of the directory where PGT's should be stored 

   * on the filesystem.

   *

   * @return the name of a directory (with leading and trailing '/')

   *

   * @private

   */

  function getPath()

    {

      return $this->_path;

    }



  /**

   * a string telling the format to use to store PGT's (plain or xml). Written by

   * PGTStorageFile::PGTStorageFile(), read by getFormat().

   *

   * @private

   */

  var $_format;



  /**

   * This method returns the format to use when storing PGT's on the filesystem.

   *

   * @return a string corresponding to the format used (plain or xml).

   *

   * @private

   */

  function getFormat()

    {

      return $this->_format;

    }



  // ########################################################################

  //  DEBUGGING

  // ########################################################################

  

  /**

   * This method returns an informational string giving the type of storage

   * used by the object (used for debugging purposes).

   *

   * @return an informational string.

   * @public

   */

  function getStorageType()

    {

      return "file";

    }



  /**

   * This method returns an informational string giving informations on the

   * parameters of the storage.(used for debugging purposes).

   *

   * @return an informational string.

   * @public

   */

  function getStorageInfo()

    {

      return 'path=`'.$this->getPath().'\', format=`'.$this->getFormat().'\'';

    }



  // ########################################################################

  //  CONSTRUCTOR

  // ########################################################################

  

  /**

   * The class constructor, called by CASClient::SetPGTStorageFile().

   *

   * @param $cas_parent the CASClient instance that creates the object.

   * @param $format the format used to store the PGT's (`plain' and `xml' allowed).

   * @param $path the path where the PGT's should be stored

   *

   * @public

   */

  function PGTStorageFile($cas_parent,$format,$path)

    {

      phpCAS::traceBegin();

      // call the ancestor's constructor

      $this->PGTStorage($cas_parent);



      if (empty($format) ) $format = CAS_PGT_STORAGE_FILE_DEFAULT_FORMAT;

      if (empty($path) ) $path = CAS_PGT_STORAGE_FILE_DEFAULT_PATH;



      // check that the path is an absolute path

      if ( $path[0] != '/' ) {

	phpCAS::error('an absolute path is needed for PGT storage to file');

      }



      // store the path (with a leading and trailing '/')      

      $path = preg_replace('|[/]*$|','/',$path);

      $path = preg_replace('|^[/]*|','/',$path);

      $this->_path = $path;



      // check the format and store it

      switch ($format) {

      case CAS_PGT_STORAGE_FILE_FORMAT_PLAIN:

      case CAS_PGT_STORAGE_FILE_FORMAT_XML:

	$this->_format = $format;

	break;

      default:

	phpCAS::error('unknown PGT file storage format (`'.CAS_PGT_STORAGE_FILE_FORMAT_PLAIN.'\' and `'.CAS_PGT_STORAGE_FILE_FORMAT_XML.'\' allowed)');

      }

      phpCAS::traceEnd();      

    }



  // ########################################################################

  //  INITIALIZATION

  // ########################################################################

  

  /**

   * This method is used to initialize the storage. Halts on error.

   *

   * @public

   */

  function init()

    {

      phpCAS::traceBegin();

      // if the storage has already been initialized, return immediatly

      if ( $this->isInitialized() )

	return;

      // call the ancestor's method (mark as initialized)

      parent::init();

      phpCAS::traceEnd();      

    }



  // ########################################################################

  //  PGT I/O

  // ########################################################################



  /**

   * This method returns the filename corresponding to a PGT Iou.

   *

   * @param $pgt_iou the PGT iou.

   *

   * @return a filename

   * @private

   */

  function getPGTIouFilename($pgt_iou)

    {

      phpCAS::traceBegin();

      $filename = $this->getPath().$pgt_iou.'.'.$this->getFormat();



      phpCAS::traceEnd($filename);

      return $filename;

    }

  

  /**

   * This method stores a PGT and its corresponding PGT Iou into a file. Echoes a

   * warning on error.

   *

   * @param $pgt the PGT

   * @param $pgt_iou the PGT iou

   *

   * @public

   */

  function write($pgt,$pgt_iou)

    {

      phpCAS::traceBegin();

      $fname = $this->getPGTIouFilename($pgt_iou);

      if ( $f=fopen($fname,"w") ) {

	if ( fputs($f,$pgt) === FALSE ) {

	  phpCAS::error('could not write PGT to `'.$fname.'\'');

	}

	fclose($f);

      } else {

	phpCAS::error('could not open `'.$fname.'\'');

      }

      phpCAS::traceEnd();      

    }



  /**

   * This method reads a PGT corresponding to a PGT Iou and deletes the 

   * corresponding file.

   *

   * @param $pgt_iou the PGT iou

   *

   * @return the corresponding PGT, or FALSE on error

   *

   * @public

   */

  function read($pgt_iou)

    {

      phpCAS::traceBegin();

      $pgt = FALSE;

      $fname = $this->getPGTIouFilename($pgt_iou);



      if ( !($f=fopen($fname,"r")) ) {

	phpCAS::trace('could not open `'.$fname.'\'');

      } else {

	if ( ($pgt=fgets($f)) === FALSE ) {

	  phpCAS::trace('could not read PGT from `'.$fname.'\'');

	} 

	fclose($f);

      }



      // delete the PGT file

      @unlink($fname);



      phpCAS::traceEnd($pgt);

      return $pgt;

    }

  

  /** @} */

  

}



  

?>