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