libraries/classes/Message.php

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