www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/imagemagick/src/ImagemagickExecArguments.php

   1 <?php
   2
   3 namespace Drupal\imagemagick;
   4
   5 /**
   6  * Stores arguments for execution of ImageMagick/GraphicsMagick commands.
   7  */
   8 class ImagemagickExecArguments {
   9
  10   /**
  11    * An identifier to be used for arguments internal to the toolkit.
  12    *
  13    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Do not prefix arguments
  14    *   to mark them internal, add them with ImageMagickExecArguments::INTERNAL
  15    *   instead.
  16    *
  17    * @see https://www.drupal.org/project/imagemagick/issues/2925780
  18    */
  19   const INTERNAL_ARGUMENT_IDENTIFIER = '>!>';
  20
  21   /**
  22    * Default index for adding arguments.
  23    */
  24   const APPEND = -1;
  25
  26   /**
  27    * Mode for arguments to be placed before the source path.
  28    */
  29   const PRE_SOURCE = 0;
  30
  31   /**
  32    * Mode for arguments to be placed after the source path.
  33    */
  34   const POST_SOURCE = 1;
  35
  36   /**
  37    * Mode for arguments not to be placed on the command line.
  38    */
  39   const INTERNAL = 2;
  40
  41   /**
  42    * The ImageMagick execution manager service.
  43    *
  44    * @var \Drupal\imagemagick\ImagemagickExecManagerInterface
  45    */
  46   protected $execManager;
  47
  48   /**
  49    * The array of command line arguments to be used by 'convert'.
  50    *
  51    * @var string[]
  52    */
  53   protected $arguments = [];
  54
  55   /**
  56    * Path of the image file.
  57    *
  58    * @var string
  59    */
  60   protected $source = '';
  61
  62   /**
  63    * The local filesystem path to the source image file.
  64    *
  65    * @var string
  66    */
  67   protected $sourceLocalPath = '';
  68
  69   /**
  70    * The source image format.
  71    *
  72    * @var string
  73    */
  74   protected $sourceFormat = '';
  75
  76   /**
  77    * The source image frames to access.
  78    *
  79    * @var string
  80    */
  81   protected $sourceFrames;
  82
  83   /**
  84    * The image destination URI/path on saving.
  85    *
  86    * @var string
  87    */
  88   protected $destination = NULL;
  89
  90   /**
  91    * The local filesystem path to the image destination.
  92    *
  93    * @var string
  94    */
  95   protected $destinationLocalPath = '';
  96
  97   /**
  98    * The image destination format on saving.
  99    *
 100    * @var string
 101    */
 102   protected $destinationFormat = '';
 103
 104   /**
 105    * Constructs an ImagemagickExecArguments object.
 106    *
 107    * @param \Drupal\imagemagick\ImagemagickExecManagerInterface $exec_manager
 108    *   The ImageMagick execution manager service.
 109    */
 110   public function __construct(ImagemagickExecManagerInterface $exec_manager) {
 111     $this->execManager = $exec_manager;
 112   }
 113
 114   /**
 115    * Gets the command line arguments for the binary.
 116    *
 117    * @return string[]
 118    *   The array of command line arguments.
 119    *
 120    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use
 121    *   ImagemagickExecArguments methods to manipulate arguments directly.
 122    *
 123    * @see https://www.drupal.org/project/imagemagick/issues/2925780
 124    */
 125   public function getArguments() {
 126     @trigger_error('getArguments() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ImagemagickExecArguments methods to manipulate arguments directly. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 127     $ret = [];
 128     foreach ($this->arguments as $i => $a) {
 129       if (in_array($a['mode'], [self::POST_SOURCE, self::INTERNAL])) {
 130         $ret[$i] = ($a['mode'] === self::INTERNAL ? self::INTERNAL_ARGUMENT_IDENTIFIER : '') . $a['argument'];
 131       }
 132     }
 133     return $ret;
 134   }
 135
 136   /**
 137    * Gets the command line arguments string for the binary.
 138    *
 139    * Removes any argument used internally within the toolkit.
 140    *
 141    * @return string
 142    *   The sring of command line arguments.
 143    *
 144    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::toString()
 145    *   instead.
 146    *
 147    * @see https://www.drupal.org/project/imagemagick/issues/2925780
 148    */
 149   public function getStringForBinary() {
 150     @trigger_error('getStringForBinary() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::toString() instead. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 151     return $this->toString(self::POST_SOURCE);
 152   }
 153
 154   /**
 155    * Gets a portion of the command line arguments string.
 156    *
 157    * @param int $mode
 158    *   The mode of the string on the command line. Can be self::PRE_SOURCE or
 159    *   self::POST_SOURCE.
 160    *
 161    * @return string
 162    *   The sring of command line arguments.
 163    */
 164   public function toString($mode) {
 165     if (!$this->arguments) {
 166       return '';
 167     }
 168     $ret = [];
 169     foreach ($this->arguments as $a) {
 170       if ($a['mode'] === $mode) {
 171         $ret[] = $a['argument'];
 172       }
 173     }
 174     return implode(' ', $ret);
 175   }
 176
 177   /**
 178    * Adds a command line argument.
 179    *
 180    * @param string $arg
 181    *   The command line argument to be added.
 182    *
 183    * @return $this
 184    *
 185    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::add() instead.
 186    *
 187    * @see https://www.drupal.org/project/imagemagick/issues/2925780
 188    */
 189   public function addArgument($arg) {
 190     @trigger_error('addArgument() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::add() instead. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 191     if (strpos($arg, self::INTERNAL_ARGUMENT_IDENTIFIER) === 0) {
 192       @trigger_error('Adding internal arguments prefixing them with ImagemagickExecArguments::INTERNAL_ARGUMENT_IDENTIFIER is deprecated in 8.x-2.3, will be removed in 8.x-3.0. ::add() them with ImageMagickExecArguments::INTERNAL instead. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 193       return $this->add(substr($arg, strlen(self::INTERNAL_ARGUMENT_IDENTIFIER)), self::INTERNAL);
 194     }
 195     return $this->add($arg);
 196   }
 197
 198   /**
 199    * Prepends a command line argument.
 200    *
 201    * @param string $arg
 202    *   The command line argument to be prepended.
 203    *
 204    * @return $this
 205    *
 206    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::add() instead.
 207    *
 208    * @see https://www.drupal.org/project/imagemagick/issues/2925780
 209    */
 210   public function prependArgument($arg) {
 211     @trigger_error('prependArgument() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::add() instead. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 212     if (strpos($arg, self::INTERNAL_ARGUMENT_IDENTIFIER) === 0) {
 213       @trigger_error('Adding internal arguments prefixing them with ImagemagickExecArguments::INTERNAL_ARGUMENT_IDENTIFIER is deprecated in 8.x-2.3, will be removed in 8.x-3.0. ::add() them with ImageMagickExecArguments::INTERNAL instead. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 214       return $this->add(substr($arg, strlen(self::INTERNAL_ARGUMENT_IDENTIFIER)), self::INTERNAL, 0);
 215     }
 216     return $this->add($arg, self::POST_SOURCE, 0);
 217   }
 218
 219   /**
 220    * Adds a command line argument.
 221    *
 222    * @param string $argument
 223    *   The command line argument to be added.
 224    * @param int $mode
 225    *   (optional) The mode of the argument in the command line. Determines if
 226    *   the argument should be placed before or after the source image file path.
 227    *   Defaults to self::POST_SOURCE.
 228    * @param int $index
 229    *   (optional) The position of the argument in the arguments array.
 230    *   Reflects the sequence of arguments in the command line. Defaults to
 231    *   self::APPEND.
 232    * @param array $info
 233    *   (optional) An optional array with information about the argument.
 234    *   Defaults to an empty array.
 235    *
 236    * @return $this
 237    */
 238   public function add($argument, $mode = self::POST_SOURCE, $index = self::APPEND, array $info = []) {
 239     $argument = [
 240       'argument' => $argument,
 241       'mode' => $mode,
 242       'info' => $info,
 243     ];
 244     if ($index === self::APPEND) {
 245       $this->arguments[] = $argument;
 246     }
 247     elseif ($index === 0) {
 248       array_unshift($this->arguments, $argument);
 249     }
 250     else {
 251       array_splice($this->arguments, $index, 0, [$argument]);
 252     }
 253     return $this;
 254   }
 255
 256   /**
 257    * Finds if a command line argument exists.
 258    *
 259    * @param string $arg
 260    *   The command line argument to be found.
 261    *
 262    * @return bool
 263    *   Returns the array key for the argument if it is found in the array,
 264    *   FALSE otherwise.
 265    *
 266    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::find() instead.
 267    *
 268    * @see https://www.drupal.org/project/imagemagick/issues/2925780
 269    */
 270   public function findArgument($arg) {
 271     @trigger_error('findArgument() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::find() instead. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 272     if (strpos($arg, self::INTERNAL_ARGUMENT_IDENTIFIER) === 0) {
 273       @trigger_error('Adding internal arguments prefixing them with ImagemagickExecArguments::INTERNAL_ARGUMENT_IDENTIFIER is deprecated in 8.x-2.3, will be removed in 8.x-3.0. ::add() them with ImageMagickExecArguments::INTERNAL instead. See https://www.drupal.org/project/imagemagick/issues/2925780.', E_USER_DEPRECATED);
 274       foreach ($this->getArguments() as $i => $a) {
 275         if (strpos($a, $arg) === 0) {
 276           return $i;
 277         }
 278       }
 279       return FALSE;
 280     }
 281     $matches = $this->find('/^' . preg_quote($arg, '/') . '/', self::POST_SOURCE);
 282     if (!empty($matches)) {
 283       $keys = array_keys($matches);
 284       return $keys[0];
 285     }
 286     return FALSE;
 287   }
 288
 289   /**
 290    * Returns an array of the indexes of arguments matching specific criteria.
 291    *
 292    * @param string $regex
 293    *   The regular expression pattern to be matched in the argument.
 294    * @param int $mode
 295    *   (optional) If set, limits the search to the mode of the argument.
 296    *   Defaults to NULL.
 297    * @param array $info
 298    *   (optional) If set, limits the search to the arguments whose $info array
 299    *   key/values match the key/values specified. Defaults to an empty array.
 300    *
 301    * @return array
 302    *   Returns an array with the matching arguments.
 303    */
 304   public function find($regex, $mode = NULL, array $info = []) {
 305     $ret = [];
 306     foreach ($this->arguments as $i => $a) {
 307       if ($mode !== NULL && $a['mode'] !== $mode) {
 308         continue;
 309
 310       }
 311       if (!empty($info)) {
 312         $intersect = array_intersect($info, $a['info']);
 313         if ($intersect != $info) {
 314           continue;
 315
 316         }
 317       }
 318       if (preg_match($regex, $a['argument']) === 1) {
 319         $ret[$i] = $a;
 320       }
 321     }
 322     return $ret;
 323   }
 324
 325   /**
 326    * Removes a command line argument.
 327    *
 328    * @param int $index
 329    *   The index of the command line argument to be removed.
 330    *
 331    * @return $this
 332    *
 333    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::remove() instead.
 334    *
 335    * @see https://www.drupal.org/project/imagemagick/issues/2936615
 336    */
 337   public function removeArgument($index) {
 338     @trigger_error('removeArgument() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::remove() instead. See https://www.drupal.org/project/imagemagick/issues/2936615.', E_USER_DEPRECATED);
 339     return $this->remove($index);
 340   }
 341
 342   /**
 343    * Removes a command line argument.
 344    *
 345    * @param int $index
 346    *   The index of the command line argument to be removed.
 347    *
 348    * @return $this
 349    */
 350   public function remove($index) {
 351     if (isset($this->arguments[$index])) {
 352       unset($this->arguments[$index]);
 353     }
 354     return $this;
 355   }
 356
 357   /**
 358    * Resets the command line arguments.
 359    *
 360    * @return $this
 361    *
 362    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::reset() instead.
 363    *
 364    * @see https://www.drupal.org/project/imagemagick/issues/2936615
 365    */
 366   public function resetArguments() {
 367     @trigger_error('resetArguments() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::reset() instead. See https://www.drupal.org/project/imagemagick/issues/2936615.', E_USER_DEPRECATED);
 368     return $this->reset();
 369   }
 370
 371   /**
 372    * Resets the command line arguments.
 373    *
 374    * @return $this
 375    */
 376   public function reset() {
 377     $this->arguments = [];
 378     return $this;
 379   }
 380
 381   /**
 382    * Returns the count of command line arguments.
 383    *
 384    * @return $this
 385    *
 386    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::find() instead,
 387    *   then count the result.
 388    *
 389    * @see https://www.drupal.org/project/imagemagick/issues/2936615
 390    */
 391   public function countArguments() {
 392     @trigger_error('countArguments() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::find() instead, then count the result. See https://www.drupal.org/project/imagemagick/issues/2936615.', E_USER_DEPRECATED);
 393     return count($this->arguments);
 394   }
 395
 396   /**
 397    * Sets the path of the source image file.
 398    *
 399    * @param string $source
 400    *   The source path of the image file.
 401    *
 402    * @return $this
 403    */
 404   public function setSource($source) {
 405     $this->source = $source;
 406     return $this;
 407   }
 408
 409   /**
 410    * Gets the path of the source image file.
 411    *
 412    * @return string
 413    *   The source path of the image file, or an empty string if the source is
 414    *   not set.
 415    */
 416   public function getSource() {
 417     return $this->source;
 418   }
 419
 420   /**
 421    * Sets the local filesystem path to the image file.
 422    *
 423    * @param string $path
 424    *   A filesystem path.
 425    *
 426    * @return $this
 427    */
 428   public function setSourceLocalPath($path) {
 429     $this->sourceLocalPath = $path;
 430     return $this;
 431   }
 432
 433   /**
 434    * Gets the local filesystem path to the image file.
 435    *
 436    * @return string
 437    *   A filesystem path.
 438    */
 439   public function getSourceLocalPath() {
 440     return $this->sourceLocalPath;
 441   }
 442
 443   /**
 444    * Sets the source image format.
 445    *
 446    * @param string $format
 447    *   The image format.
 448    *
 449    * @return $this
 450    */
 451   public function setSourceFormat($format) {
 452     $this->sourceFormat = $this->execManager->getFormatMapper()->isFormatEnabled($format) ? $format : '';
 453     return $this;
 454   }
 455
 456   /**
 457    * Sets the source image format from an image file extension.
 458    *
 459    * @param string $extension
 460    *   The image file extension.
 461    *
 462    * @return $this
 463    */
 464   public function setSourceFormatFromExtension($extension) {
 465     $this->sourceFormat = $this->execManager->getFormatMapper()->getFormatFromExtension($extension) ?: '';
 466     return $this;
 467   }
 468
 469   /**
 470    * Gets the source image format.
 471    *
 472    * @return string
 473    *   The source image format.
 474    */
 475   public function getSourceFormat() {
 476     return $this->sourceFormat;
 477   }
 478
 479   /**
 480    * Sets the source image frames to access.
 481    *
 482    * @param string $frames
 483    *   The frames in '[n]' string format.
 484    *
 485    * @return $this
 486    *
 487    * @see http://www.imagemagick.org/script/command-line-processing.php
 488    */
 489   public function setSourceFrames($frames) {
 490     $this->sourceFrames = $frames;
 491     return $this;
 492   }
 493
 494   /**
 495    * Gets the source image frames to access.
 496    *
 497    * @return string
 498    *   The frames in '[n]' string format.
 499    *
 500    * @see http://www.imagemagick.org/script/command-line-processing.php
 501    */
 502   public function getSourceFrames() {
 503     return $this->sourceFrames;
 504   }
 505
 506   /**
 507    * Sets the image destination URI/path on saving.
 508    *
 509    * @param string $destination
 510    *   The image destination URI/path.
 511    *
 512    * @return $this
 513    */
 514   public function setDestination($destination) {
 515     $this->destination = $destination;
 516     return $this;
 517   }
 518
 519   /**
 520    * Gets the image destination URI/path on saving.
 521    *
 522    * @return string
 523    *   The image destination URI/path.
 524    */
 525   public function getDestination() {
 526     return $this->destination;
 527   }
 528
 529   /**
 530    * Sets the local filesystem path to the destination image file.
 531    *
 532    * @param string $path
 533    *   A filesystem path.
 534    *
 535    * @return $this
 536    */
 537   public function setDestinationLocalPath($path) {
 538     $this->destinationLocalPath = $path;
 539     return $this;
 540   }
 541
 542   /**
 543    * Gets the local filesystem path to the destination image file.
 544    *
 545    * @return string
 546    *   A filesystem path.
 547    */
 548   public function getDestinationLocalPath() {
 549     return $this->destinationLocalPath;
 550   }
 551
 552   /**
 553    * Sets the image destination format.
 554    *
 555    * When set, it is passed to the convert binary in the syntax
 556    * "[format]:[destination]", where [format] is a string denoting an
 557    * ImageMagick's image format.
 558    *
 559    * @param string $format
 560    *   The image destination format.
 561    *
 562    * @return $this
 563    */
 564   public function setDestinationFormat($format) {
 565     $this->destinationFormat = $format;
 566     return $this;
 567   }
 568
 569   /**
 570    * Sets the image destination format from an image file extension.
 571    *
 572    * When set, it is passed to the convert binary in the syntax
 573    * "[format]:[destination]", where [format] is a string denoting an
 574    * ImageMagick's image format.
 575    *
 576    * @param string $extension
 577    *   The destination image file extension.
 578    *
 579    * @return $this
 580    */
 581   public function setDestinationFormatFromExtension($extension) {
 582     $this->destinationFormat = $this->execManager->getFormatMapper()->getFormatFromExtension($extension) ?: '';
 583     return $this;
 584   }
 585
 586   /**
 587    * Gets the image destination format.
 588    *
 589    * When set, it is passed to the convert binary in the syntax
 590    * "[format]:[destination]", where [format] is a string denoting an
 591    * ImageMagick's image format.
 592    *
 593    * @return string
 594    *   The image destination format.
 595    */
 596   public function getDestinationFormat() {
 597     return $this->destinationFormat;
 598   }
 599
 600   /**
 601    * Escapes a string.
 602    *
 603    * @param string $arg
 604    *   The string to escape.
 605    *
 606    * @return string
 607    *   An escaped string for use in the
 608    *   ImagemagickExecManagerInterface::execute method.
 609    *
 610    * @deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::escape()
 611    *   instead.
 612    *
 613    * @see https://www.drupal.org/project/imagemagick/issues/2936680
 614    */
 615   public function escapeShellArg($arg) {
 616     @trigger_error('escapeShellArg() is deprecated in 8.x-2.3, will be removed in 8.x-3.0. Use ::escape() instead. See https://www.drupal.org/project/imagemagick/issues/2936680.', E_USER_DEPRECATED);
 617     return $this->escape($arg);
 618   }
 619
 620   /**
 621    * Escapes a string.
 622    *
 623    * @param string $argument
 624    *   The string to escape.
 625    *
 626    * @return string
 627    *   An escaped string for use in the
 628    *   ImagemagickExecManagerInterface::execute method.
 629    */
 630   public function escape($argument) {
 631     return $this->execManager->escapeShellArg($argument);
 632   }
 633
 634 }