src/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 htmlspecialchars;
  12 use function is_float;
  13 use function is_int;
  14 use function md5;
  15 use function sprintf;
  16
  17 use const ENT_COMPAT;
  18
  19 /**
  20  * a single message
  21  *
  22  * simple usage examples:
  23  * <code>
  24  * // display simple error message 'Error'
  25  * echo Message::error()->getDisplay();
  26  *
  27  * // get simple success message 'Success'
  28  * $message = Message::success();
  29  *
  30  * // get special notice
  31  * $message = Message::notice(__('This is a localized notice'));
  32  * </code>
  33  *
  34  * more advanced usage example:
  35  * <code>
  36  * // create another message, a hint, with a localized string which expects
  37  * $hint = Message::notice('Read the %smanual%s');
  38  * // replace placeholders with the following params
  39  * $hint->addParam('[doc@cfg_Example]');
  40  * $hint->addParam('[/doc]');
  41  * // add this hint as a tooltip
  42  * $hint = showHint($hint);
  43  *
  44  * // add the retrieved tooltip reference to the original message
  45  * $message->addMessage($hint);
  46  * </code>
  47  */
  48 class Message implements Stringable
  49 {
  50     public const SUCCESS = 1; // 0001
  51     public const NOTICE = 2; // 0010
  52     public const ERROR = 8; // 1000
  53
  54     /**
  55      * The locale string identifier
  56      */
  57     protected string $string = '';
  58
  59     /**
  60      * The formatted message
  61      */
  62     protected string $message = '';
  63
  64     /**
  65      * Whether the message was already displayed
  66      */
  67     protected bool $isDisplayed = false;
  68
  69     /**
  70      * Whether to use BB code when displaying.
  71      */
  72     protected bool $useBBCode = true;
  73
  74     /**
  75      * Unique id
  76      */
  77     protected string|null $hash = null;
  78
  79     /**
  80      * holds parameters
  81      *
  82      * @var    mixed[]
  83      */
  84     protected array $params = [];
  85
  86     /**
  87      * holds additional messages
  88      *
  89      * @var    (string|Message)[]
  90      */
  91     protected array $addedMessages = [];
  92
  93     /**
  94      * @param string  $string The message to be displayed
  95      * @param int     $type   A numeric representation of the type of message
  96      * @param mixed[] $params An array of parameters to use in the message
  97      *                        constant definitions above
  98      * @psalm-param self::SUCCESS|self::NOTICE|self::ERROR $type
  99      */
 100     public function __construct(
 101         string $string = '',
 102         private int $type = self::NOTICE,
 103         array $params = [],
 104     ) {
 105         $this->setString($string);
 106         $this->setParams($params);
 107     }
 108
 109     /**
 110      * magic method: return string representation for this object
 111      */
 112     public function __toString(): string
 113     {
 114         return $this->getMessage();
 115     }
 116
 117     /**
 118      * get Message of type success
 119      *
 120      * shorthand for getting a simple success message
 121      *
 122      * @param string $string A localized string
 123      *                       e.g. __('Your SQL query has been
 124      *                       executed successfully')
 125      */
 126     public static function success(string $string = ''): self
 127     {
 128         if ($string === '') {
 129             $string = __('Your SQL query has been executed successfully.');
 130         }
 131
 132         return new Message($string, self::SUCCESS);
 133     }
 134
 135     /**
 136      * get Message of type error
 137      *
 138      * shorthand for getting a simple error message
 139      *
 140      * @param string $string A localized string e.g. __('Error')
 141      */
 142     public static function error(string $string = ''): self
 143     {
 144         if ($string === '') {
 145             $string = __('Error');
 146         }
 147
 148         return new Message($string, self::ERROR);
 149     }
 150
 151     /**
 152      * get Message of type notice
 153      *
 154      * shorthand for getting a simple notice message
 155      *
 156      * @param string $string A localized string
 157      *                       e.g. __('The additional features for working with
 158      *                       linked tables have been deactivated. To find out
 159      *                       why click %shere%s.')
 160      */
 161     public static function notice(string $string): self
 162     {
 163         return new Message($string, self::NOTICE);
 164     }
 165
 166     /**
 167      * get Message with customized content
 168      *
 169      * shorthand for getting a customized message
 170      *
 171      * @param string $message A localized string
 172      * @param int    $type    A numeric representation of the type of message
 173      * @psalm-param self::SUCCESS|self::NOTICE|self::ERROR $type
 174      */
 175     public static function raw(string $message, int $type = self::NOTICE): self
 176     {
 177         $r = new Message('', $type);
 178         $r->setMessage($message);
 179         $r->setBBCode(false);
 180
 181         return $r;
 182     }
 183
 184     /**
 185      * get Message for type of affected rows
 186      *
 187      * shorthand for getting a customized message
 188      *
 189      * @param int $rows Number of rows
 190      */
 191     public static function getMessageForAffectedRows(int $rows): self
 192     {
 193         $message = self::success(
 194             _ngettext('%1$d row affected.', '%1$d rows affected.', $rows),
 195         );
 196         $message->addParam($rows);
 197
 198         return $message;
 199     }
 200
 201     /**
 202      * get Message for type of deleted rows
 203      *
 204      * shorthand for getting a customized message
 205      *
 206      * @param int $rows Number of rows
 207      */
 208     public static function getMessageForDeletedRows(int $rows): self
 209     {
 210         $message = self::success(
 211             _ngettext('%1$d row deleted.', '%1$d rows deleted.', $rows),
 212         );
 213         $message->addParam($rows);
 214
 215         return $message;
 216     }
 217
 218     /**
 219      * get Message for type of inserted rows
 220      *
 221      * shorthand for getting a customized message
 222      *
 223      * @param int $rows Number of rows
 224      */
 225     public static function getMessageForInsertedRows(int $rows): self
 226     {
 227         $message = self::success(
 228             _ngettext('%1$d row inserted.', '%1$d rows inserted.', $rows),
 229         );
 230         $message->addParam($rows);
 231
 232         return $message;
 233     }
 234
 235     /**
 236      * get Message of type error with custom content
 237      *
 238      * shorthand for getting a customized error message
 239      *
 240      * @param string $message A localized string
 241      */
 242     public static function rawError(string $message): self
 243     {
 244         return self::raw($message, self::ERROR);
 245     }
 246
 247     /**
 248      * get Message of type notice with custom content
 249      *
 250      * shorthand for getting a customized notice message
 251      *
 252      * @param string $message A localized string
 253      */
 254     public static function rawNotice(string $message): self
 255     {
 256         return self::raw($message);
 257     }
 258
 259     /**
 260      * get Message of type success with custom content
 261      *
 262      * shorthand for getting a customized success message
 263      *
 264      * @param string $message A localized string
 265      */
 266     public static function rawSuccess(string $message): self
 267     {
 268         return self::raw($message, self::SUCCESS);
 269     }
 270
 271     public function isSuccess(): bool
 272     {
 273         return $this->type === self::SUCCESS;
 274     }
 275
 276     public function isNotice(): bool
 277     {
 278         return $this->type === self::NOTICE;
 279     }
 280
 281     public function isError(): bool
 282     {
 283         return $this->type === self::ERROR;
 284     }
 285
 286     /**
 287      * Set whether we should use BB Code when rendering.
 288      *
 289      * @param bool $useBBCode Use BB Code?
 290      */
 291     public function setBBCode(bool $useBBCode): void
 292     {
 293         $this->useBBCode = $useBBCode;
 294     }
 295
 296     /**
 297      * set raw message (overrides string)
 298      *
 299      * @param string $message A localized string
 300      */
 301     public function setMessage(string $message): void
 302     {
 303         $this->message = $message;
 304     }
 305
 306     /**
 307      * set string (does not take effect if raw message is set)
 308      *
 309      * @param string $string string to set
 310      */
 311     public function setString(string $string): void
 312     {
 313         $this->string = $string;
 314     }
 315
 316     /**
 317      * set message type type
 318      *
 319      * @param int $type message type type to set
 320      * @psalm-param self::SUCCESS|self::NOTICE|self::ERROR $type
 321      */
 322     public function setType(int $type): void
 323     {
 324         $this->type = $type;
 325     }
 326
 327     /**
 328      * add string or Message parameter
 329      *
 330      * usage
 331      * <code>
 332      * $message->addParam('[em]some string[/em]');
 333      * </code>
 334      *
 335      * @param mixed $param parameter to add
 336      */
 337     public function addParam(mixed $param): void
 338     {
 339         if ($param instanceof self || is_float($param) || is_int($param)) {
 340             $this->params[] = $param;
 341         } else {
 342             $this->params[] = htmlspecialchars((string) $param, ENT_COMPAT);
 343         }
 344     }
 345
 346     /**
 347      * add parameter as raw HTML, usually in conjunction with strings
 348      *
 349      * usage
 350      * <code>
 351      * $message->addParamHtml('<img src="img">');
 352      * </code>
 353      *
 354      * @param string $param parameter to add
 355      */
 356     public function addParamHtml(string $param): void
 357     {
 358         $this->params[] = self::notice($param);
 359     }
 360
 361     /**
 362      * add a bunch of messages at once
 363      *
 364      * @param Message[] $messages  to be added
 365      * @param string    $separator to use between this and previous string/message
 366      */
 367     public function addMessages(array $messages, string $separator = ' '): void
 368     {
 369         foreach ($messages as $message) {
 370             $this->addMessage($message, $separator);
 371         }
 372     }
 373
 374     /**
 375      * add a bunch of messages at once
 376      *
 377      * @param string[] $messages  to be added
 378      * @param string   $separator to use between this and previous string/message
 379      */
 380     public function addMessagesString(array $messages, string $separator = ' '): void
 381     {
 382         foreach ($messages as $message) {
 383             $this->addText($message, $separator);
 384         }
 385     }
 386
 387     /**
 388      * Real implementation of adding message
 389      *
 390      * @param Message $message   to be added
 391      * @param string  $separator to use between this and previous string/message
 392      */
 393     private function addMessageToList(self $message, string $separator): void
 394     {
 395         if ($separator !== '') {
 396             $this->addedMessages[] = $separator;
 397         }
 398
 399         $this->addedMessages[] = $message;
 400     }
 401
 402     /**
 403      * add another raw message to be concatenated on displaying
 404      *
 405      * @param self   $message   to be added
 406      * @param string $separator to use between this and previous string/message
 407      */
 408     public function addMessage(self $message, string $separator = ' '): void
 409     {
 410         $this->addMessageToList($message, $separator);
 411     }
 412
 413     /**
 414      * add another raw message to be concatenated on displaying
 415      *
 416      * @param string $message   to be added
 417      * @param string $separator to use between this and previous string/message
 418      */
 419     public function addText(string $message, string $separator = ' '): void
 420     {
 421         $this->addMessageToList(self::notice(htmlspecialchars($message)), $separator);
 422     }
 423
 424     /**
 425      * add another html message to be concatenated on displaying
 426      *
 427      * @param string $message   to be added
 428      * @param string $separator to use between this and previous string/message
 429      */
 430     public function addHtml(string $message, string $separator = ' '): void
 431     {
 432         $this->addMessageToList(self::rawNotice($message), $separator);
 433     }
 434
 435     /**
 436      * set all params at once, usually used in conjunction with string
 437      *
 438      * @param mixed[] $params parameters to set
 439      */
 440     public function setParams(array $params): void
 441     {
 442         $this->params = $params;
 443     }
 444
 445     /**
 446      * return all parameters
 447      *
 448      * @return mixed[]
 449      */
 450     public function getParams(): array
 451     {
 452         return $this->params;
 453     }
 454
 455     /**
 456      * return all added messages
 457      *
 458      * @return (string|Message)[]
 459      */
 460     public function getAddedMessages(): array
 461     {
 462         return $this->addedMessages;
 463     }
 464
 465     /**
 466      * returns unique Message::$hash, if not exists it will be created
 467      *
 468      * @return string Message::$hash
 469      */
 470     public function getHash(): string
 471     {
 472         if ($this->hash === null) {
 473             $this->hash = md5($this->type . $this->string . $this->message);
 474         }
 475
 476         return $this->hash;
 477     }
 478
 479     /**
 480      * returns compiled message
 481      *
 482      * @return string complete message
 483      */
 484     public function getMessage(): string
 485     {
 486         $message = $this->message;
 487
 488         if ($message === '') {
 489             $message = $this->getString();
 490         }
 491
 492         /** @infection-ignore-all */
 493         if ($this->isDisplayed()) {
 494             $message = $this->getMessageWithIcon($message);
 495         }
 496
 497         if ($this->params !== []) {
 498             $message = sprintf($message, ...$this->params);
 499         }
 500
 501         if ($this->useBBCode) {
 502             $message = Sanitize::convertBBCode($message, true);
 503         }
 504
 505         foreach ($this->getAddedMessages() as $addMessage) {
 506             $message .= $addMessage;
 507         }
 508
 509         return $message;
 510     }
 511
 512     /**
 513      * Returns only message string without image & other HTML.
 514      */
 515     public function getOnlyMessage(): string
 516     {
 517         return $this->message;
 518     }
 519
 520     /**
 521      * returns Message::$string
 522      *
 523      * @return string Message::$string
 524      */
 525     public function getString(): string
 526     {
 527         return $this->string;
 528     }
 529
 530     /**
 531      * returns level of message
 532      *
 533      * @return string level of message
 534      */
 535     public function getLevel(): string
 536     {
 537         return match ($this->type) {
 538             self::SUCCESS => 'success',
 539             self::NOTICE => 'notice',
 540             self::ERROR => 'error'
 541         };
 542     }
 543
 544     public function getContext(): string
 545     {
 546         return match ($this->getLevel()) {
 547             'error' => 'danger',
 548             'success' => 'success',
 549             default => 'primary',
 550         };
 551     }
 552
 553     /**
 554      * returns HTML code for displaying this message
 555      *
 556      * @return string whole message box
 557      */
 558     public function getDisplay(): string
 559     {
 560         $this->isDisplayed(true);
 561
 562         $context = $this->getContext();
 563
 564         $template = new Template();
 565
 566         return $template->render('message', ['context' => $context, 'message' => $this->getMessage()]);
 567     }
 568
 569     /**
 570      * sets and returns whether the message was displayed or not
 571      *
 572      * @param bool $isDisplayed whether to set displayed flag
 573      *
 574      * @infection-ignore-all
 575      */
 576     public function isDisplayed(bool $isDisplayed = false): bool
 577     {
 578         if ($isDisplayed) {
 579             $this->isDisplayed = true;
 580         }
 581
 582         return $this->isDisplayed;
 583     }
 584
 585     /**
 586      * Returns the message with corresponding image icon
 587      *
 588      * @param string $message the message(s)
 589      *
 590      * @return string message with icon
 591      */
 592     public function getMessageWithIcon(string $message): string
 593     {
 594         $image = match ($this->getLevel()) {
 595             'error' => 's_error',
 596             'success' => 's_success',
 597             default =>'s_notice',
 598         };
 599
 600         return self::notice(Html\Generator::getImage($image)) . ' ' . $message;
 601     }
 602 }