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   boolean $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 a warning message or not
 428      * and optionally makes this message a warning message
 429      *
 430      * @uses    PMA_Message::WARNING
 431      * @uses    PMA_Message::setNumber()
 432      * @uses    PMA_Message::getNumber()
 433      * @param   boolean $set
 434      * @return  boolean whether this is a warning message or not
 435      */
 436     public function isWarning($set = false)
 437     {
 438         if ($set) {
 439             $this->setNumber(PMA_Message::WARNING);
 440         }
 441
 442         return $this->getNumber() === PMA_Message::WARNING;
 443     }
 444
 445     /**
 446      * returns whether this message is an error message or not
 447      * and optionally makes this message an error message
 448      *
 449      * @uses    PMA_Message::ERROR
 450      * @uses    PMA_Message::setNumber()
 451      * @uses    PMA_Message::getNumber()
 452      * @param   boolean $set
 453      * @return  boolean whether this is an error message or not
 454      */
 455     public function isError($set = false)
 456     {
 457         if ($set) {
 458             $this->setNumber(PMA_Message::ERROR);
 459         }
 460
 461         return $this->getNumber() === PMA_Message::ERROR;
 462     }
 463
 464     /**
 465      * set raw message (overrides string)
 466      *
 467      * @uses    PMA_Message::$_message to set it
 468      * @uses    PMA_Message::sanitize()
 469      * @param   string  $message
 470      * @param   boolean $sanitize whether to sanitize $message or not
 471      */
 472     public function setMessage($message, $sanitize = false)
 473     {
 474         if ($sanitize) {
 475             $message = PMA_Message::sanitize($message);
 476         }
 477         $this->_message = $message;
 478     }
 479
 480     /**
 481      * set string (does not take effect if raw message is set)
 482      *
 483      * @uses    PMA_Message::$_string to set it
 484      * @uses    PMA_Message::sanitize()
 485      * @param   string  $_string
 486      * @param   boolean $sanitize whether to sanitize $string or not
 487      */
 488     public function setString($_string, $sanitize = true)
 489     {
 490         if ($sanitize) {
 491             $_string = PMA_Message::sanitize($_string);
 492         }
 493         $this->_string = $_string;
 494     }
 495
 496     /**
 497      * set message type number
 498      *
 499      * @uses    PMA_Message::$_number to set it
 500      * @param   integer $number
 501      */
 502     public function setNumber($number)
 503     {
 504         $this->_number = $number;
 505     }
 506
 507     /**
 508      * add parameter, usually in conjunction with strings
 509      *
 510      * usage
 511      * <code>
 512      * $message->addParam('strLocale', false);
 513      * $message->addParam('[em]some string[/em]');
 514      * $message->addParam('<img src="img" />', false);
 515      * </code>
 516      *
 517      * @uses    htmlspecialchars()
 518      * @uses    PMA_Message::$_params to fill
 519      * @uses    PMA_Message::notice()
 520      * @param   mixed   $param
 521      * @param   boolean $raw
 522      */
 523     public function addParam($param, $raw = true)
 524     {
 525         if ($param instanceof PMA_Message) {
 526             $this->_params[] = $param;
 527         } elseif ($raw) {
 528             $this->_params[] = htmlspecialchars($param);
 529         } else {
 530             $this->_params[] = PMA_Message::notice($param);
 531         }
 532     }
 533
 534     /**
 535      * add another string to be concatenated on displaying
 536      *
 537      * @uses    PMA_Message::$_added_messages to fill
 538      * @uses    PMA_Message::notice()
 539      * @param   string  $string    to be added
 540      * @param   string  $separator to use between this and previous string/message
 541      */
 542     public function addString($string, $separator = ' ')
 543     {
 544         $this->_added_messages[] = $separator;
 545         $this->_added_messages[] = PMA_Message::notice($string);
 546     }
 547
 548     /**
 549      * add a bunch of messages at once
 550      *
 551      * @uses    PMA_Message::addMessage()
 552      * @param   array   $messages  to be added
 553      * @param   string  $separator to use between this and previous string/message
 554      */
 555     public function addMessages($messages, $separator = ' ')
 556     {
 557         foreach ($messages as $message) {
 558             $this->addMessage($message, $separator);
 559         }
 560     }
 561
 562     /**
 563      * add another raw message to be concatenated on displaying
 564      *
 565      * @uses    PMA_Message::$_added_messages to fill
 566      * @uses    PMA_Message::rawNotice()
 567      * @param   mixed   $message   to be added
 568      * @param   string  $separator to use between this and previous string/message
 569      */
 570     public function addMessage($message, $separator = ' ')
 571     {
 572         if (strlen($separator)) {
 573             $this->_added_messages[] = $separator;
 574         }
 575
 576         if ($message instanceof PMA_Message) {
 577             $this->_added_messages[] = $message;
 578         } else {
 579             $this->_added_messages[] = PMA_Message::rawNotice($message);
 580         }
 581     }
 582
 583     /**
 584      * set all params at once, usually used in conjunction with string
 585      *
 586      * @uses    PMA_Message::sanitize()
 587      * @uses    PMA_Message::$_params to set
 588      * @param   array   $params
 589      * @param   boolean $sanitize
 590      */
 591     public function setParams($params, $sanitize = false)
 592     {
 593         if ($sanitize) {
 594             $params = PMA_Message::sanitize($params);
 595         }
 596         $this->_params = $params;
 597     }
 598
 599     /**
 600      * return all parameters
 601      *
 602      * @uses    PMA_Message::$_params as return value
 603      * @return array
 604      */
 605     public function getParams()
 606     {
 607         return $this->_params;
 608     }
 609
 610     /**
 611      * return all added messages
 612      *
 613      * @uses    PMA_Message::$_added_messages as return value
 614      * @return array
 615      */
 616     public function getAddedMessages()
 617     {
 618         return $this->_added_messages;
 619     }
 620
 621     /**
 622      * Sanitizes $message
 623      *
 624      * @static
 625      * @uses    is_array()
 626      * @uses    htmlspecialchars()
 627      * @uses    PMA_Message::sanitize() recursiv
 628      * @param   mixed   the message(s)
 629      * @return  mixed   the sanitized message(s)
 630      * @access  public
 631      */
 632     static public function sanitize($message)
 633     {
 634         if (is_array($message)) {
 635             foreach ($message as $key => $val) {
 636                 $message[$key] = PMA_Message::sanitize($val);
 637             }
 638
 639             return $message;
 640         }
 641
 642         return htmlspecialchars($message);
 643     }
 644
 645     /**
 646      * decode $message, taking into account our special codes
 647      * for formatting
 648      *
 649      * @static
 650      * @uses    PMA_sanitize
 651      * @param   string  $message the message
 652      * @return  string  the decoded message
 653      * @access  public
 654      */
 655     static public function decodeBB($message)
 656     {
 657         return PMA_sanitize($message, false, true);
 658     }
 659
 660     /**
 661      * wrapper for sprintf()
 662      *
 663      * @uses    sprintf()
 664      * @uses    func_get_args()
 665      * @uses    is_array()
 666      * @uses    array_unshift()
 667      * @uses    call_user_func_array()
 668      * @return  string formatted
 669      */
 670     static public function format()
 671     {
 672         $params = func_get_args();
 673         if (isset($params[1]) && is_array($params[1])) {
 674             array_unshift($params[1], $params[0]);
 675             $params = $params[1];
 676         }
 677
 678         return call_user_func_array('sprintf', $params);
 679     }
 680
 681     /**
 682      * returns unique PMA_Message::$_hash, if not exists it will be created
 683      *
 684      * @uses    PMA_Message::$_hash as return value and to set it if required
 685      * @uses    PMA_Message::getNumber()
 686      * @uses    PMA_Message::$_string
 687      * @uses    PMA_Message::$_message
 688      * @uses    md5()
 689      * @param   string $file
 690      * @return  string PMA_Message::$_hash
 691      */
 692     public function getHash()
 693     {
 694         if (null === $this->_hash) {
 695             $this->_hash = md5(
 696                 $this->getNumber() .
 697                 $this->_string .
 698                 $this->_message
 699             );
 700         }
 701
 702         return $this->_hash;
 703     }
 704
 705     /**
 706      * returns compiled message
 707      *
 708      * @uses    PMA_Message::$_message as return value
 709      * @uses    PMA_Message::getString()
 710      * @uses    PMA_Message::getParams()
 711      * @uses    PMA_Message::format()
 712      * @uses    PMA_Message::decodeBB()
 713      * @uses    PMA_Message::getAddedMessages()
 714      * @uses    strlen()
 715      * @return  string complete message
 716      */
 717     public function getMessage()
 718     {
 719         $message = $this->_message;
 720
 721         if (0 === strlen($message)) {
 722             $string = $this->getString();
 723             if (isset($GLOBALS[$string])) {
 724                 $message = $GLOBALS[$string];
 725             } elseif (0 === strlen($string)) {
 726                 $message = '';
 727             } else {
 728                 $message = $string;
 729             }
 730         }
 731
 732         if (count($this->getParams()) > 0) {
 733             $message = PMA_Message::format($message, $this->getParams());
 734         }
 735
 736         $message = PMA_Message::decodeBB($message);
 737
 738         foreach ($this->getAddedMessages() as $add_message) {
 739             $message .= $add_message;
 740         }
 741
 742         return $message;
 743     }
 744
 745     /**
 746      * returns PMA_Message::$_string
 747      *
 748      * @uses    PMA_Message::$_string as return value
 749      * @return  string PMA_Message::$_string
 750      */
 751     public function getString()
 752     {
 753         return $this->_string;
 754     }
 755
 756     /**
 757      * returns PMA_Message::$_number
 758      *
 759      * @uses    PMA_Message::$_number as return value
 760      * @return  integer PMA_Message::$_number
 761      */
 762     public function getNumber()
 763     {
 764         return $this->_number;
 765     }
 766
 767     /**
 768      * returns level of message
 769      *
 770      * @uses    PMA_Message::$level
 771      * @uses    PMA_Message::getNumber()
 772      * @return  string  level of message
 773      */
 774     public function getLevel()
 775     {
 776         return PMA_Message::$level[$this->getNumber()];
 777     }
 778
 779     /**
 780      * Displays the message in HTML
 781      *
 782      * @uses    PMA_Message::getLevel()
 783      * @uses    PMA_Message::getMessage()
 784      * @uses    PMA_Message::isDisplayed()
 785      */
 786     public function display()
 787     {
 788         echo $this->getDisplay();
 789         $this->isDisplayed(true);
 790     }
 791
 792     /**
 793      * returns HTML code for displaying this message
 794      *
 795      * @return string whole message box
 796      */
 797     public function getDisplay()
 798     {
 799         return '<div class="' . $this->getLevel() . '">'
 800             . $this->getMessage() . '</div>';
 801     }
 802
 803     /**
 804      * sets and returns whether the message was displayed or not
 805      *
 806      * @uses    PMA_Message::$_is_displayed to set it and/or return it
 807      * @param   boolean $is_displayed
 808      * @return  boolean PMA_Message::$_is_displayed
 809      */
 810     public function isDisplayed($is_displayed = false)
 811     {
 812         if ($is_displayed) {
 813             $this->_is_displayed = true;
 814         }
 815
 816         return $this->_is_displayed;
 817     }
 818 }
 819 ?>