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