libraries/classes/Message.php

   1 <?php
   2
   3 declare(strict_types=1);
   4
   5 namespace PhpMyAdmin;
   6
   7 use function array_unshift;
   8 use function count;
   9 use function htmlspecialchars;
  10 use function is_array;
  11 use function is_float;
  12 use function is_int;
  13 use function md5;
  14 use function sprintf;
  15 use function strlen;
  16
  17 /**
  18  * a single message
  19  *
  20  * simple usage examples:
  21  * <code>
  22  * // display simple error message 'Error'
  23  * echo Message::error()->getDisplay();
  24  *
  25  * // get simple success message 'Success'
  26  * $message = Message::success();
  27  *
  28  * // get special notice
  29  * $message = Message::notice(__('This is a localized notice'));
  30  * </code>
  31  *
  32  * more advanced usage example:
  33  * <code>
  34  * // create another message, a hint, with a localized string which expects
  35  * $hint = Message::notice('Read the %smanual%s');
  36  * // replace placeholders with the following params
  37  * $hint->addParam('[doc@cfg_Example]');
  38  * $hint->addParam('[/doc]');
  39  * // add this hint as a tooltip
  40  * $hint = showHint($hint);
  41  *
  42  * // add the retrieved tooltip reference to the original message
  43  * $message->addMessage($hint);
  44  * </code>
  45  */
  46 class Message
  47 {
  48     public const SUCCESS = 1; // 0001
  49     public const NOTICE  = 2; // 0010
  50     public const ERROR   = 8; // 1000
  51
  52     public const SANITIZE_NONE   = 0;  // 0000 0000
  53     public const SANITIZE_STRING = 16; // 0001 0000
  54     public const SANITIZE_PARAMS = 32; // 0010 0000
  55     public const SANITIZE_BOOTH  = 48; // 0011 0000
  56
  57     /**
  58      * message levels
  59      *
  60      * @var array
  61      */
  62     public static $level =  [
  63         self::SUCCESS => 'success',
  64         self::NOTICE  => 'notice',
  65         self::ERROR   => 'error',
  66     ];
  67
  68     /**
  69      * The message number
  70      *
  71      * @access protected
  72      * @var int
  73      */
  74     protected $number = self::NOTICE;
  75
  76     /**
  77      * The locale string identifier
  78      *
  79      * @access protected
  80      * @var    string
  81      */
  82     protected $string = '';
  83
  84     /**
  85      * The formatted message
  86      *
  87      * @access protected
  88      * @var    string
  89      */
  90     protected $message = '';
  91
  92     /**
  93      * Whether the message was already displayed
  94      *
  95      * @access protected
  96      * @var bool
  97      */
  98     protected $isDisplayed = false;
  99
 100     /**
 101      * Whether to use BB code when displaying.
 102      *
 103      * @access protected
 104      * @var bool
 105      */
 106     protected $useBBCode = true;
 107
 108     /**
 109      * Unique id
 110      *
 111      * @access protected
 112      * @var string
 113      */
 114     protected $hash = null;
 115
 116     /**
 117      * holds parameters
 118      *
 119      * @access protected
 120      * @var    array
 121      */
 122     protected $params = [];
 123
 124     /**
 125      * holds additional messages
 126      *
 127      * @access protected
 128      * @var    array
 129      */
 130     protected $addedMessages = [];
 131
 132     /**
 133      * @param string $string   The message to be displayed
 134      * @param int    $number   A numeric representation of the type of message
 135      * @param array  $params   An array of parameters to use in the message
 136      * @param int    $sanitize A flag to indicate what to sanitize, see
 137      *                         constant definitions above
 138      */
 139     public function __construct(
 140         string $string = '',
 141         int $number = self::NOTICE,
 142         array $params = [],
 143         int $sanitize = self::SANITIZE_NONE
 144     ) {
 145         $this->setString($string, $sanitize & self::SANITIZE_STRING);
 146         $this->setNumber($number);
 147         $this->setParams($params, $sanitize & self::SANITIZE_PARAMS);
 148     }
 149
 150     /**
 151      * magic method: return string representation for this object
 152      */
 153     public function __toString(): string
 154     {
 155         return $this->getMessage();
 156     }
 157
 158     /**
 159      * get Message of type success
 160      *
 161      * shorthand for getting a simple success message
 162      *
 163      * @param string $string A localized string
 164      *                       e.g. __('Your SQL query has been
 165      *                       executed successfully')
 166      *
 167      * @return Message
 168      *
 169      * @static
 170      */
 171     public static function success(string $string = ''): self
 172     {
 173         if (empty($string)) {
 174             $string = __('Your SQL query has been executed successfully.');
 175         }
 176
 177         return new Message($string, self::SUCCESS);
 178     }
 179
 180     /**
 181      * get Message of type error
 182      *
 183      * shorthand for getting a simple error message
 184      *
 185      * @param string $string A localized string e.g. __('Error')
 186      *
 187      * @return Message
 188      *
 189      * @static
 190      */
 191     public static function error(string $string = ''): self
 192     {
 193         if (empty($string)) {
 194             $string = __('Error');
 195         }
 196
 197         return new Message($string, self::ERROR);
 198     }
 199
 200     /**
 201      * get Message of type notice
 202      *
 203      * shorthand for getting a simple notice message
 204      *
 205      * @param string $string A localized string
 206      *                       e.g. __('The additional features for working with
 207      *                       linked tables have been deactivated. To find out
 208      *                       why click %shere%s.')
 209      *
 210      * @return Message
 211      *
 212      * @static
 213      */
 214     public static function notice(string $string): self
 215     {
 216         return new Message($string, self::NOTICE);
 217     }
 218
 219     /**
 220      * get Message with customized content
 221      *
 222      * shorthand for getting a customized message
 223      *
 224      * @param string $message A localized string
 225      * @param int    $type    A numeric representation of the type of message
 226      *
 227      * @return Message
 228      *
 229      * @static
 230      */
 231     public static function raw(string $message, int $type = self::NOTICE): self
 232     {
 233         $r = new Message('', $type);
 234         $r->setMessage($message);
 235         $r->setBBCode(false);
 236
 237         return $r;
 238     }
 239
 240     /**
 241      * get Message for number of affected rows
 242      *
 243      * shorthand for getting a customized message
 244      *
 245      * @param int $rows Number of rows
 246      *
 247      * @return Message
 248      *
 249      * @static
 250      */
 251     public static function getMessageForAffectedRows(int $rows): self
 252     {
 253         $message = self::success(
 254             _ngettext('%1$d row affected.', '%1$d rows affected.', $rows)
 255         );
 256         $message->addParam($rows);
 257
 258         return $message;
 259     }
 260
 261     /**
 262      * get Message for number of deleted rows
 263      *
 264      * shorthand for getting a customized message
 265      *
 266      * @param int $rows Number of rows
 267      *
 268      * @return Message
 269      *
 270      * @static
 271      */
 272     public static function getMessageForDeletedRows(int $rows): self
 273     {
 274         $message = self::success(
 275             _ngettext('%1$d row deleted.', '%1$d rows deleted.', $rows)
 276         );
 277         $message->addParam($rows);
 278
 279         return $message;
 280     }
 281
 282     /**
 283      * get Message for number of inserted rows
 284      *
 285      * shorthand for getting a customized message
 286      *
 287      * @param int $rows Number of rows
 288      *
 289      * @return Message
 290      *
 291      * @static
 292      */
 293     public static function getMessageForInsertedRows(int $rows): self
 294     {
 295         $message = self::success(
 296             _ngettext('%1$d row inserted.', '%1$d rows inserted.', $rows)
 297         );
 298         $message->addParam($rows);
 299
 300         return $message;
 301     }
 302
 303     /**
 304      * get Message of type error with custom content
 305      *
 306      * shorthand for getting a customized error message
 307      *
 308      * @param string $message A localized string
 309      *
 310      * @return Message
 311      *
 312      * @static
 313      */
 314     public static function rawError(string $message): self
 315     {
 316         return self::raw($message, self::ERROR);
 317     }
 318
 319     /**
 320      * get Message of type notice with custom content
 321      *
 322      * shorthand for getting a customized notice message
 323      *
 324      * @param string $message A localized string
 325      *
 326      * @return Message
 327      *
 328      * @static
 329      */
 330     public static function rawNotice(string $message): self
 331     {
 332         return self::raw($message, self::NOTICE);
 333     }
 334
 335     /**
 336      * get Message of type success with custom content
 337      *
 338      * shorthand for getting a customized success message
 339      *
 340      * @param string $message A localized string
 341      *
 342      * @return Message
 343      *
 344      * @static
 345      */
 346     public static function rawSuccess(string $message): self
 347     {
 348         return self::raw($message, self::SUCCESS);
 349     }
 350
 351     /**
 352      * returns whether this message is a success message or not
 353      * and optionally makes this message a success message
 354      *
 355      * @param bool $set Whether to make this message of SUCCESS type
 356      *
 357      * @return bool whether this is a success message or not
 358      */
 359     public function isSuccess(bool $set = false): bool
 360     {
 361         if ($set) {
 362             $this->setNumber(self::SUCCESS);
 363         }
 364
 365         return $this->getNumber() === self::SUCCESS;
 366     }
 367
 368     /**
 369      * returns whether this message is a notice message or not
 370      * and optionally makes this message a notice message
 371      *
 372      * @param bool $set Whether to make this message of NOTICE type
 373      *
 374      * @return bool whether this is a notice message or not
 375      */
 376     public function isNotice(bool $set = false): bool
 377     {
 378         if ($set) {
 379             $this->setNumber(self::NOTICE);
 380         }
 381
 382         return $this->getNumber() === self::NOTICE;
 383     }
 384
 385     /**
 386      * returns whether this message is an error message or not
 387      * and optionally makes this message an error message
 388      *
 389      * @param bool $set Whether to make this message of ERROR type
 390      *
 391      * @return bool Whether this is an error message or not
 392      */
 393     public function isError(bool $set = false): bool
 394     {
 395         if ($set) {
 396             $this->setNumber(self::ERROR);
 397         }
 398
 399         return $this->getNumber() === self::ERROR;
 400     }
 401
 402     /**
 403      * Set whether we should use BB Code when rendering.
 404      *
 405      * @param bool $useBBCode Use BB Code?
 406      */
 407     public function setBBCode(bool $useBBCode): void
 408     {
 409         $this->useBBCode = $useBBCode;
 410     }
 411
 412     /**
 413      * set raw message (overrides string)
 414      *
 415      * @param string $message  A localized string
 416      * @param bool   $sanitize Whether to sanitize $message or not
 417      */
 418     public function setMessage(string $message, bool $sanitize = false): void
 419     {
 420         if ($sanitize) {
 421             $message = self::sanitize($message);
 422         }
 423         $this->message = $message;
 424     }
 425
 426     /**
 427      * set string (does not take effect if raw message is set)
 428      *
 429      * @param string   $string   string to set
 430      * @param bool|int $sanitize whether to sanitize $string or not
 431      */
 432     public function setString(string $string, $sanitize = true): void
 433     {
 434         if ($sanitize) {
 435             $string = self::sanitize($string);
 436         }
 437         $this->string = $string;
 438     }
 439
 440     /**
 441      * set message type number
 442      *
 443      * @param int $number message type number to set
 444      */
 445     public function setNumber(int $number): void
 446     {
 447         $this->number = $number;
 448     }
 449
 450     /**
 451      * add string or Message parameter
 452      *
 453      * usage
 454      * <code>
 455      * $message->addParam('[em]some string[/em]');
 456      * </code>
 457      *
 458      * @param mixed $param parameter to add
 459      */
 460     public function addParam($param): void
 461     {
 462         if ($param instanceof self || is_float($param) || is_int($param)) {
 463             $this->params[] = $param;
 464         } else {
 465             $this->params[] = htmlspecialchars((string) $param);
 466         }
 467     }
 468
 469     /**
 470      * add parameter as raw HTML, usually in conjunction with strings
 471      *
 472      * usage
 473      * <code>
 474      * $message->addParamHtml('<img src="img">');
 475      * </code>
 476      *
 477      * @param string $param parameter to add
 478      */
 479     public function addParamHtml(string $param): void
 480     {
 481         $this->params[] = self::notice($param);
 482     }
 483
 484     /**
 485      * add a bunch of messages at once
 486      *
 487      * @param Message[] $messages  to be added
 488      * @param string    $separator to use between this and previous string/message
 489      */
 490     public function addMessages(array $messages, string $separator = ' '): void
 491     {
 492         foreach ($messages as $message) {
 493             $this->addMessage($message, $separator);
 494         }
 495     }
 496
 497     /**
 498      * add a bunch of messages at once
 499      *
 500      * @param string[] $messages  to be added
 501      * @param string   $separator to use between this and previous string/message
 502      */
 503     public function addMessagesString(array $messages, string $separator = ' '): void
 504     {
 505         foreach ($messages as $message) {
 506             $this->addText($message, $separator);
 507         }
 508     }
 509
 510     /**
 511      * Real implementation of adding message
 512      *
 513      * @param Message $message   to be added
 514      * @param string  $separator to use between this and previous string/message
 515      */
 516     private function addMessageToList(self $message, string $separator): void
 517     {
 518         if (! empty($separator)) {
 519             $this->addedMessages[] = $separator;
 520         }
 521         $this->addedMessages[] = $message;
 522     }
 523
 524     /**
 525      * add another raw message to be concatenated on displaying
 526      *
 527      * @param self   $message   to be added
 528      * @param string $separator to use between this and previous string/message
 529      */
 530     public function addMessage(self $message, string $separator = ' '): void
 531     {
 532         $this->addMessageToList($message, $separator);
 533     }
 534
 535     /**
 536      * add another raw message to be concatenated on displaying
 537      *
 538      * @param string $message   to be added
 539      * @param string $separator to use between this and previous string/message
 540      */
 541     public function addText(string $message, string $separator = ' '): void
 542     {
 543         $this->addMessageToList(self::notice(htmlspecialchars($message)), $separator);
 544     }
 545
 546     /**
 547      * add another html message to be concatenated on displaying
 548      *
 549      * @param string $message   to be added
 550      * @param string $separator to use between this and previous string/message
 551      */
 552     public function addHtml(string $message, string $separator = ' '): void
 553     {
 554         $this->addMessageToList(self::rawNotice($message), $separator);
 555     }
 556
 557     /**
 558      * set all params at once, usually used in conjunction with string
 559      *
 560      * @param array    $params   parameters to set
 561      * @param bool|int $sanitize whether to sanitize params
 562      */
 563     public function setParams(array $params, $sanitize = false): void
 564     {
 565         if ($sanitize) {
 566             $params = self::sanitize($params);
 567         }
 568         $this->params = $params;
 569     }
 570
 571     /**
 572      * return all parameters
 573      *
 574      * @return array
 575      */
 576     public function getParams(): array
 577     {
 578         return $this->params;
 579     }
 580
 581     /**
 582      * return all added messages
 583      *
 584      * @return array
 585      */
 586     public function getAddedMessages(): array
 587     {
 588         return $this->addedMessages;
 589     }
 590
 591     /**
 592      * Sanitizes $message
 593      *
 594      * @param mixed $message the message(s)
 595      *
 596      * @return mixed  the sanitized message(s)
 597      *
 598      * @access public
 599      * @static
 600      */
 601     public static function sanitize($message)
 602     {
 603         if (is_array($message)) {
 604             foreach ($message as $key => $val) {
 605                 $message[$key] = self::sanitize($val);
 606             }
 607
 608             return $message;
 609         }
 610
 611         return htmlspecialchars((string) $message);
 612     }
 613
 614     /**
 615      * decode $message, taking into account our special codes
 616      * for formatting
 617      *
 618      * @param string $message the message
 619      *
 620      * @return string  the decoded message
 621      *
 622      * @access public
 623      * @static
 624      */
 625     public static function decodeBB(string $message): string
 626     {
 627         return Sanitize::sanitizeMessage($message, false, true);
 628     }
 629
 630     /**
 631      * wrapper for sprintf()
 632      *
 633      * @param mixed[] ...$params Params
 634      *
 635      * @return string formatted
 636      */
 637     public static function format(...$params): string
 638     {
 639         if (isset($params[1]) && is_array($params[1])) {
 640             array_unshift($params[1], $params[0]);
 641             $params = $params[1];
 642         }
 643
 644         return sprintf(...$params);
 645     }
 646
 647     /**
 648      * returns unique Message::$hash, if not exists it will be created
 649      *
 650      * @return string Message::$hash
 651      */
 652     public function getHash(): string
 653     {
 654         if ($this->hash === null) {
 655             $this->hash = md5(
 656                 $this->getNumber() .
 657                 $this->string .
 658                 $this->message
 659             );
 660         }
 661
 662         return $this->hash;
 663     }
 664
 665     /**
 666      * returns compiled message
 667      *
 668      * @return string complete message
 669      */
 670     public function getMessage(): string
 671     {
 672         $message = $this->message;
 673
 674         if (strlen($message) === 0) {
 675             $string = $this->getString();
 676             if (strlen($string) === 0) {
 677                 $message = '';
 678             } else {
 679                 $message = $string;
 680             }
 681         }
 682
 683         if ($this->isDisplayed()) {
 684             $message = $this->getMessageWithIcon($message);
 685         }
 686         if (count($this->getParams()) > 0) {
 687             $message = self::format($message, $this->getParams());
 688         }
 689
 690         if ($this->useBBCode) {
 691             $message = self::decodeBB($message);
 692         }
 693
 694         foreach ($this->getAddedMessages() as $add_message) {
 695             $message .= $add_message;
 696         }
 697
 698         return $message;
 699     }
 700
 701     /**
 702      * Returns only message string without image & other HTML.
 703      */
 704     public function getOnlyMessage(): string
 705     {
 706         return $this->message;
 707     }
 708
 709     /**
 710      * returns Message::$string
 711      *
 712      * @return string Message::$string
 713      */
 714     public function getString(): string
 715     {
 716         return $this->string;
 717     }
 718
 719     /**
 720      * returns Message::$number
 721      *
 722      * @return int Message::$number
 723      */
 724     public function getNumber(): int
 725     {
 726         return $this->number;
 727     }
 728
 729     /**
 730      * returns level of message
 731      *
 732      * @return string level of message
 733      */
 734     public function getLevel(): string
 735     {
 736         return self::$level[$this->getNumber()];
 737     }
 738
 739     /**
 740      * returns HTML code for displaying this message
 741      *
 742      * @return string whole message box
 743      */
 744     public function getDisplay(): string
 745     {
 746         $this->isDisplayed(true);
 747
 748         $context = 'primary';
 749         $level = $this->getLevel();
 750         if ($level === 'error') {
 751             $context = 'danger';
 752         } elseif ($level === 'success') {
 753             $context = 'success';
 754         }
 755
 756         $template = new Template();
 757
 758         return $template->render('message', [
 759             'context' => $context,
 760             'message' => $this->getMessage(),
 761         ]);
 762     }
 763
 764     /**
 765      * sets and returns whether the message was displayed or not
 766      *
 767      * @param bool $isDisplayed whether to set displayed flag
 768      *
 769      * @return bool Message::$isDisplayed
 770      */
 771     public function isDisplayed(bool $isDisplayed = false): bool
 772     {
 773         if ($isDisplayed) {
 774             $this->isDisplayed = true;
 775         }
 776
 777         return $this->isDisplayed;
 778     }
 779
 780     /**
 781      * Returns the message with corresponding image icon
 782      *
 783      * @param string $message the message(s)
 784      *
 785      * @return string message with icon
 786      */
 787     public function getMessageWithIcon(string $message): string
 788     {
 789         if ($this->getLevel() === 'error') {
 790             $image = 's_error';
 791         } elseif ($this->getLevel() === 'success') {
 792             $image = 's_success';
 793         } else {
 794             $image = 's_notice';
 795         }
 796         $message = self::notice(Html\Generator::getImage($image)) . ' ' . $message;
 797
 798         return $message;
 799     }
 800 }