framework/main/classes/template/image/class_ImageTemplateEngine.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Template\Engine;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Factory\ObjectFactory;
   7 use Org\Mxchange\CoreFramework\Filesystem\InvalidDirectoryException;
   8 use Org\Mxchange\CoreFramework\Parser\Xml\XmlParser;
   9 use Org\Mxchange\CoreFramework\Registry\Registry;
  10 use Org\Mxchange\CoreFramework\Response\Responseable;
  11 use Org\Mxchange\CoreFramework\Template\CompileableTemplate;
  12 use Org\Mxchange\CoreFramework\Template\Engine\BaseTemplateEngine;
  13
  14 // Import SPL stuff
  15 use \SplFileInfo;
  16 use \UnexpectedValueException;
  17
  18 /**
  19  * The own template engine for loading caching and sending out images
  20  *
  21  * @author              Roland Haeder <webmaster@shipsimu.org>
  22  * @version             0.0.0
  23 <<<<<<< HEAD:framework/main/classes/template/image/class_ImageTemplateEngine.php
  24  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
  25 =======
  26  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2016 Core Developer Team
  27 >>>>>>> Some updates::inc/main/classes/template/image/class_ImageTemplateEngine.php
  28  * @license             GNU GPL 3.0 or any newer version
  29  * @link                http://www.shipsimu.org
  30  *
  31  * This program is free software: you can redistribute it and/or modify
  32  * it under the terms of the GNU General Public License as published by
  33  * the Free Software Foundation, either version 3 of the License, or
  34  * (at your option) any later version.
  35  *
  36  * This program is distributed in the hope that it will be useful,
  37  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  38  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  39  * GNU General Public License for more details.
  40  *
  41  * You should have received a copy of the GNU General Public License
  42  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  43  */
  44 class ImageTemplateEngine extends BaseTemplateEngine implements CompileableTemplate {
  45         /**
  46          * Main nodes in the XML tree ('image' is ignored)
  47          */
  48         private $mainNodes = array(
  49                 'base',
  50                 'type',
  51                 'resolution',
  52                 'background-color',
  53                 'foreground-color',
  54                 'image-string'
  55         );
  56
  57         /**
  58          * Sub nodes in the XML tree
  59          */
  60         private $subNodes = array(
  61                 'name',
  62                 'string-name',
  63                 'x',
  64                 'y',
  65                 'font-size',
  66                 'width',
  67                 'height',
  68                 'red',
  69                 'green',
  70                 'blue',
  71                 'text'
  72         );
  73
  74         /**
  75          * Current main node
  76          */
  77         private $currMainNode = '';
  78
  79         /**
  80          * Protected constructor
  81          *
  82          * @return      void
  83          */
  84         protected function __construct () {
  85                 // Call parent constructor
  86                 parent::__construct(__CLASS__);
  87         }
  88
  89         /**
  90          * Creates an instance of the class TemplateEngine and prepares it for usage
  91          *
  92          * @return      $templateInstance               An instance of TemplateEngine
  93          * @throws      UnexpectedValueException                If the provided $templateBasePath is empty or no string
  94          * @throws      InvalidDirectoryException       If $templateBasePath is no
  95          *                                                                                      directory or not found
  96          * @throws      BasePathReadProtectedException  If $templateBasePath is
  97          *                                                                                      read-protected
  98          */
  99         public static final function createImageTemplateEngine () {
 100                 // Get a new instance
 101                 $templateInstance = new ImageTemplateEngine();
 102
 103                 // Get the application instance from registry
 104                 $applicationInstance = Registry::getRegistry()->getInstance('app');
 105
 106                 // Determine base path
 107                 $templateBasePath = $templateInstance->getConfigInstance()->getConfigEntry('application_base_path') . $applicationInstance->getAppShortName(). '/';
 108
 109                 // Is the base path valid?
 110                 if (empty($templateBasePath)) {
 111                         // Base path is empty
 112                         throw new UnexpectedValueException(sprintf('[%s:%d] Variable templateBasePath is empty.', $templateInstance->__toString(), __LINE__), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
 113                 } elseif (!is_string($templateBasePath)) {
 114                         // Is not a string
 115                         throw new UnexpectedValueException(sprintf('[%s:%d] %s is not a string with a base path.', $templateInstance->__toString(), __LINE__, $templateBasePath), self::EXCEPTION_INVALID_STRING);
 116                 } elseif (!is_dir($templateBasePath)) {
 117                         // Is not a path
 118                         throw new InvalidDirectoryException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_PATH_NAME);
 119                 } elseif (!is_readable($templateBasePath)) {
 120                         // Is not readable
 121                         throw new BasePathReadProtectedException(array($templateInstance, $templateBasePath), self::EXCEPTION_READ_PROTECED_PATH);
 122                 }
 123
 124                 // Set the base path
 125                 $templateInstance->setTemplateBasePath($templateBasePath);
 126
 127                 // Set template extensions
 128                 $templateInstance->setRawTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('raw_template_extension'));
 129                 $templateInstance->setCodeTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('code_template_extension'));
 130
 131                 // Absolute output path for compiled templates
 132                 $templateInstance->setCompileOutputPath(sprintf('%s%s/',
 133                         $templateBasePath,
 134                         $templateInstance->getConfigInstance()->getConfigEntry('compile_output_path')
 135                 ));
 136
 137                 // Return the prepared instance
 138                 return $templateInstance;
 139         }
 140
 141         /**
 142          * Getter for current main node
 143          *
 144          * @return      $currMainNode   Current main node
 145          */
 146         public final function getCurrMainNode () {
 147                 return $this->currMainNode;
 148         }
 149
 150         /**
 151          * Getter for main node array
 152          *
 153          * @return      $mainNodes      Array with valid main node names
 154          */
 155         public final function getMainNodes () {
 156                 return $this->mainNodes;
 157         }
 158
 159         /**
 160          * Getter for sub node array
 161          *
 162          * @return      $subNodes       Array with valid sub node names
 163          */
 164         public final function getSubNodes () {
 165                 return $this->subNodes;
 166         }
 167
 168         /**
 169          * Handles the start element of an XML resource
 170          *
 171          * @param       $resource               XML parser resource (currently ignored)
 172          * @param       $element                The element we shall handle
 173          * @param       $attributes             All attributes
 174          * @return      void
 175          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
 176          */
 177         public function startElement ($resource, $element, array $attributes) {
 178                 // Initial method name which will never be called...
 179                 $methodName = 'initImage';
 180
 181                 // Make the element name lower-case
 182                 $element = strtolower($element);
 183
 184                 // Is the element a main node?
 185                 //* DEBUG: */ echo "START: &gt;".$element."&lt;<br />\n";
 186                 if (in_array($element, $this->mainNodes)) {
 187                         // Okay, main node found!
 188                         $methodName = 'setImage' . self::convertToClassName($element);
 189                 } elseif (in_array($element, $this->subNodes)) {
 190                         // Sub node found
 191                         $methodName = 'setImageProperty' . self::convertToClassName($element);
 192                 } elseif ($element != 'image') {
 193                         // Invalid node name found
 194                         throw new InvalidXmlNodeException(array($this, $element, $attributes), XmlParser::EXCEPTION_XML_NODE_UNKNOWN);
 195                 }
 196
 197                 // Call method
 198                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
 199                 call_user_func_array(array($this, $methodName), $attributes);
 200         }
 201
 202         /**
 203          * Ends the main or sub node by sending out the gathered data
 204          *
 205          * @param       $resource       An XML resource pointer (currently ignored)
 206          * @param       $nodeName       Name of the node we want to finish
 207          * @return      void
 208          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
 209          */
 210         public function finishElement ($resource, $nodeName) {
 211                 // Make all lower-case
 212                 $nodeName = strtolower($nodeName);
 213
 214                 // Does this match with current main node?
 215                 //* DEBUG: */ echo "END: &gt;".$nodeName."&lt;<br />\n";
 216                 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
 217                         // Did not match!
 218                         throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), XmlParser::EXCEPTION_XML_NODE_MISMATCH);
 219                 } elseif (in_array($nodeName, $this->getSubNodes())) {
 220                         // Silently ignore sub nodes
 221                         return;
 222                 }
 223
 224                 // Construct method name
 225                 $methodName = 'finish' . self::convertToClassName($nodeName);
 226
 227                 // Call the corresponding method
 228                 call_user_func_array(array($this->getImageInstance(), $methodName), array());
 229         }
 230
 231         /**
 232          * Currently not used
 233          *
 234          * @param       $resource               XML parser resource (currently ignored)
 235          * @param       $characters             Characters to handle
 236          * @return      void
 237          * @todo        Find something usefull with this!
 238          */
 239         public function characterHandler ($resource, $characters) {
 240                 // Trim all spaces away
 241                 $characters = trim($characters);
 242
 243                 // Is this string empty?
 244                 if (empty($characters)) {
 245                         // Then skip it silently
 246                         return;
 247                 } // END - if
 248
 249                 // Unfinished work!
 250                 $this->partialStub('Handling extra characters is not yet supported!');
 251         }
 252
 253         /**
 254          * Intializes the image
 255          *
 256          * @return      void
 257          * @todo        Add cache creation here
 258          */
 259         private function initImage () {
 260                 // Unfinished work!
 261         }
 262
 263         /**
 264          * Set the image type
 265          *
 266          * @param       $imageType      Code fragment or direct value holding the image type
 267          * @return      void
 268          */
 269         private function setImageType ($imageType) {
 270                 // Set group to general
 271                 $this->setVariableGroup('general');
 272
 273                 // Try to compile it first to get the value from variable stack
 274                 $imageType = $this->compileRawCode($imageType);
 275
 276                 // Now make a class name of it
 277                 $className = self::convertToClassName($imageType.'_image');
 278
 279                 // And try to initiate it
 280                 $this->setImageInstance(ObjectFactory::createObjectByName($className, array($this)));
 281
 282                 // Set current main node to type
 283                 $this->currMainNode = 'type';
 284         }
 285
 286         /**
 287          * "Setter" for resolution, we first need to collect the resolution from the
 288          * sub-nodes. So first, this method will prepare an array for it
 289          *
 290          * @return      void
 291          */
 292         private function setImageResolution () {
 293                 // Call the image class
 294                 $this->getImageInstance()->initResolution();
 295
 296                 // Current main node is resolution
 297                 $this->currMainNode = 'resolution';
 298         }
 299
 300         /**
 301          * "Setter" for base information. For more details see above method!
 302          *
 303          * @return      void
 304          * @see         ImageTemplateEngine::setImageResolution
 305          */
 306         private function setImageBase () {
 307                 // Call the image class
 308                 $this->getImageInstance()->initBase();
 309
 310                 // Current main node is resolution
 311                 $this->currMainNode = 'base';
 312         }
 313
 314         /**
 315          * "Setter" for background-color. For more details see above method!
 316          *
 317          * @return      void
 318          * @see         ImageTemplateEngine::setImageResolution
 319          */
 320         private function setImageBackgroundColor () {
 321                 // Call the image class
 322                 $this->getImageInstance()->initBackgroundColor();
 323
 324                 // Current main node is background-color
 325                 $this->currMainNode = 'background-color';
 326         }
 327
 328         /**
 329          * "Setter" for foreground-color. For more details see above method!
 330          *
 331          * @return      void
 332          * @see         ImageTemplateEngine::setImageResolution
 333          */
 334         private function setImageForegroundColor () {
 335                 // Call the image class
 336                 $this->getImageInstance()->initForegroundColor();
 337
 338                 // Current main node is foreground-color
 339                 $this->currMainNode = 'foreground-color';
 340         }
 341
 342         /**
 343          * "Setter" for image-string. For more details see above method!
 344          *
 345          * @param       $groupable      Whether this image string is groupable
 346          * @return      void
 347          * @see         ImageTemplateEngine::setImageResolution
 348          */
 349         private function setImageImageString ($groupable = 'single') {
 350                 // Call the image class
 351                 $this->getImageInstance()->initImageString($groupable);
 352
 353                 // Current main node is foreground-color
 354                 $this->currMainNode = 'image-string';
 355         }
 356
 357         /**
 358          * Setter for image name
 359          *
 360          * @param       $imageName      Name of the image
 361          * @return      void
 362          */
 363         private function setImagePropertyName ($imageName) {
 364                 // Call the image class
 365                 $this->getImageInstance()->setImageName($imageName);
 366         }
 367
 368         /**
 369          * Setter for image width
 370          *
 371          * @param       $width  Width of the image or variable
 372          * @return      void
 373          */
 374         private function setImagePropertyWidth ($width) {
 375                 // Call the image class
 376                 $this->getImageInstance()->setWidth($width);
 377         }
 378
 379         /**
 380          * Setter for image height
 381          *
 382          * @param       $height Height of the image or variable
 383          * @return      void
 384          */
 385         private function setImagePropertyHeight ($height) {
 386                 // Call the image class
 387                 $this->getImageInstance()->setHeight($height);
 388         }
 389
 390         /**
 391          * Setter for image red color
 392          *
 393          * @param       $red    Red color value
 394          * @return      void
 395          */
 396         private function setImagePropertyRed ($red) {
 397                 // Call the image class
 398                 $this->getImageInstance()->setRed($red);
 399         }
 400
 401         /**
 402          * Setter for image green color
 403          *
 404          * @param       $green  Green color value
 405          * @return      void
 406          */
 407         private function setImagePropertyGreen ($green) {
 408                 // Call the image class
 409                 $this->getImageInstance()->setGreen($green);
 410         }
 411
 412         /**
 413          * Setter for image blue color
 414          *
 415          * @param       $blue   Blue color value
 416          * @return      void
 417          */
 418         private function setImagePropertyBlue ($blue) {
 419                 // Call the image class
 420                 $this->getImageInstance()->setBlue($blue);
 421         }
 422
 423         /**
 424          * Setter for string name (identifier)
 425          *
 426          * @param       $stringName             String name (identifier)
 427          * @return      void
 428          */
 429         private function setImagePropertyStringName ($stringName) {
 430                 // Call the image class
 431                 $this->getImageInstance()->setStringName($stringName);
 432         }
 433
 434         /**
 435          * Setter for font size
 436          *
 437          * @param       $fontSize       Size of the font
 438          * @return      void
 439          */
 440         private function setImagePropertyFontSize ($fontSize) {
 441                 // Call the image class
 442                 $this->getImageInstance()->setFontSize($fontSize);
 443         }
 444
 445         /**
 446          * Setter for image string
 447          *
 448          * @param       $imageString    Image string to set
 449          * @return      void
 450          */
 451         private function setImagePropertyText ($imageString) {
 452                 // Call the image class
 453                 $this->getImageInstance()->setString($imageString);
 454         }
 455
 456         /**
 457          * Setter for X coordinate
 458          *
 459          * @param       $x      X coordinate
 460          * @return      void
 461          */
 462         private function setImagePropertyX ($x) {
 463                 // Call the image class
 464                 $this->getImageInstance()->setX($x);
 465         }
 466
 467         /**
 468          * Setter for Y coordinate
 469          *
 470          * @param       $y      Y coordinate
 471          * @return      void
 472          */
 473         private function setImagePropertyY ($y) {
 474                 // Call the image class
 475                 $this->getImageInstance()->setY($y);
 476         }
 477
 478         /**
 479          * Getter for image cache file instance
 480          *
 481          * @return      $fileInstance   An instance of a SplFileInfo class
 482          */
 483         public function getImageCacheFile () {
 484                 // Get the instance ready
 485                 $fileInstance = new SplFileInfo(sprintf('%s%s%s/%s.%s',
 486                         $this->getConfigInstance()->getConfigEntry('root_base_path'),
 487                         $this->getGenericBasePath(),
 488                         'images/_cache',
 489                         md5(
 490                                 $this->getImageInstance()->getImageName() . ':' . $this->__toString() . ':' . $this->getImageInstance()->__toString()
 491                         ),
 492                         $this->getImageInstance()->getImageType()
 493                 ));
 494
 495                 // Return it
 496                 return $fileInstance;
 497         }
 498
 499         /**
 500          * Outputs the image to the world
 501          *
 502          * @param       $responseInstance       An instance of a Responseable class
 503          * @return      void
 504          */
 505         public function transferToResponse (Responseable $responseInstance) {
 506                 // Set the image instance
 507                 $responseInstance->setImageInstance($this->getImageInstance());
 508         }
 509
 510         /**
 511          * Load a specified image template into the engine
 512          *
 513          * @param       $template       The image template we shall load which is
 514          *                                              located in 'image' by default
 515          * @return      void
 516          */
 517         public function loadImageTemplate ($template) {
 518                 // Set template type
 519                 $this->setTemplateType($this->getConfigInstance()->getConfigEntry('image_template_type'));
 520
 521                 // Load the special template
 522                 $this->loadTemplate($template);
 523         }
 524
 525 }