[Sommaire] [Imprimer]

   1  <?php
   2  /*

   3   *  $Id: Lob.php,v 1.10 2004/03/20 04:16:50 hlellelid Exp $

   4   *

   5   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

   6   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

   7   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

   8   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

   9   * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

  10   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

  11   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

  12   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

  13   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

  14   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

  15   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  16   *

  17   * This software consists of voluntary contributions made by many individuals

  18   * and is licensed under the LGPL. For more information please see

  19   * <http://creole.phpdb.org>.

  20   */
  21  
  22  /**

  23   * An abstract class for handling LOB (Locator Object) columns.

  24   * 

  25   * @author    Hans Lellelid <hans@xmpl.org>

  26   * @version   $Revision: 1.10 $

  27   * @package   creole.util

  28   */
  29  abstract class Lob {
  30  
  31      /** 

  32       * The contents of the Lob.

  33       * DO NOT SET DIRECTLY (or you will disrupt the

  34       * ability of isModified() to give accurate results).

  35       * @var string

  36       */
  37      protected $data;
  38      
  39      /** 

  40       * File that blob should be written out to.

  41       * @var string

  42       */
  43      protected $outFile;
  44      
  45      /** 

  46       * File that blob should be read in from 

  47       * @var string

  48       */
  49      protected $inFile;
  50      
  51      /**

  52       * This is a 3-state value indicating whether column has been

  53       * modified.

  54       * Initially it is NULL.  Once first call to setContents() is made

  55       * it is FALSE, because this will be initial state of Lob.  Once

  56       * a subsequent call to setContents() is made it is TRUE.

  57       * @var boolean

  58       */
  59      private $modified = null;
  60      
  61      /**

  62       * Construct a new Lob.

  63       * @param sttring $data The data contents of the Lob.

  64       * @see setContents()

  65       */
  66      public function __construct($data = null)
  67      {
  68          if ($data !== null) {
  69              $this->setContents($data);
  70          }
  71      }
  72      
  73      /**

  74       * Get the contents of the LOB.

  75       * @return string The characters in this LOB.

  76       * @throws Exception

  77       */
  78      public function getContents()
  79      {
  80          if ($this->data === null && $this->isFromFile()) {
  81              $this->readFromFile();
  82          }
  83          return $this->data;
  84      }
  85      
  86      /**

  87       * Set the contents of this LOB.

  88       * Sets the modified flag to FALSE if this is the first call

  89       * to setContents() for this object.  Sets the bit to TRUE if

  90       * this any subsequent call to setContents().

  91       * @param string $bytes

  92       */
  93      public function setContents($data)
  94      {
  95          $this->data = $data;
  96                 
  97          if ($this->modified === null) {
  98               // if modified bit hasn't been set yet,

  99              // then it should now be set to FALSE, since

 100              // we just did inital population

 101              $this->modified = false;
 102          } elseif ($this->modified === false) {
 103              // if it was already FALSE, then it should

 104              // now be set to TRUE, since this is a subsequent

 105              // modfiication.

 106              $this->modified = true;
 107          }
 108      }
 109          
 110      /**

 111       * Dump the contents of the file to stdout.

 112       * Must be implemented by subclasses so that binary status is handled

 113       * correctly. (i.e. ignored for Clob, handled for Blob)

 114       * @return void

 115       * @throws Exception if no file or contents.

 116       */
 117      abstract public function dump();
 118      
 119      /**

 120       * Specify the file that we want this LOB read from.

 121       * @param string $filePath The location of the file.

 122       * @return void

 123       */
 124      public function setInputFile($filePath)
 125      {
 126          $this->inFile = $filePath;
 127      }    
 128  
 129      /**

 130       * Get the file that we want this LOB read from.

 131       * @return string The location of the file.

 132       */
 133      public function getInputFile()
 134      {
 135          return $this->inFile;
 136      }    
 137      
 138      /**

 139       * Specify the file that we want this LOB saved to.

 140       * @param string $filePath The location of the file.

 141       * @return void

 142       */
 143      public function setOutputFile($filePath)
 144      {
 145          $this->outFile = $filePath;        
 146      }
 147      
 148      /**

 149       * Get the file that we want this LOB saved to.

 150       * @return string $filePath The location of the file.

 151       */
 152      public function getOutputFile()
 153      {
 154          return $this->outFile;
 155      }
 156  
 157      /**

 158       * Returns whether this Lob is loaded from file.

 159       * This is useful for bypassing need to read in the contents of the Lob.

 160       * @return boolean Whether this LOB is to be read from a file.

 161       */
 162      public function isFromFile()
 163      {
 164          return ($this->inFile !== null);
 165      }
 166      
 167      /**

 168       * Read LOB data from file (binary safe).

 169       * (Implementation may need to be moved into Clob / Blob subclasses, but 

 170       * since file_get_contents() is binary-safe, it hasn't been necessary so far.)

 171       * @param string $file Filename may also be specified here (if not specified using setInputFile()).

 172       * @return void

 173       * @throws Exception - if no file specified or error on read.

 174       * @see setInputFile()

 175       */
 176      public function readFromFile($file = null)
 177      {
 178          if ($file !== null) {
 179              $this->setInputFile($file);
 180          }
 181          if (!$this->inFile) {
 182              throw Exception('No file specified for read.');
 183          }        
 184          $data = @file_get_contents($this->inFile);
 185          if ($data === false) {
 186              throw new Exception('Unable to read from file: '.$this->inFile);
 187          }        
 188          $this->setContents($data);                
 189      }
 190      
 191      
 192      /**

 193       * Write LOB data to file (binary safe).

 194       * (Impl may need to move into subclasses, but so far not necessary.)

 195       * @param string $file Filename may also be specified here (if not set using setOutputFile()).

 196       * @throws Exception - if no file specified, no contents to write, or error on write.

 197       * @see setOutputFile()

 198       */
 199      public function writeToFile($file = null)
 200      {
 201          if ($file !== null) {
 202              $this->setOutputFile($file);
 203          }        
 204          if (!$this->outFile) {
 205              throw new Exception('No file specified for write');
 206          }
 207          if ($this->data === null) {
 208              throw new Exception('No data to write to file');
 209          }        
 210          if (false === @file_put_contents($this->outFile, $this->data)) {
 211              throw new Exception('Unable to write to file: '.$this->outFile);
 212          }
 213      }
 214      
 215      /**

 216       * Convenience method to get contents of LOB as string.

 217       * @return string

 218       */
 219      public function __toString()
 220      {
 221          return $this->getContents();
 222      }
 223      
 224      /**

 225       * Set whether LOB contents have been modified after initial setting.

 226       * @param boolean $b

 227       */
 228      public function setModified($b)
 229      {
 230          $this->modified = $b;
 231      }
 232      
 233      /**

 234       * Whether LOB contents have been modified after initial setting.

 235       * @return boolean TRUE if the contents have been modified after initial setting. 

 236       *                  FALSE if contents have not been modified or if no contents have bene set.

 237       */
 238      public function isModified()
 239      {
 240          // cast it so that NULL will also eval to false

 241          return (boolean) $this->modified;
 242      }
 243  }