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