libraries/classes/Message.php

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