libraries/Message.class.php

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