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      * @param   string  $string
 141      * @param   integer $number
 142      * @param   array   $params
 143      * @param   integer $sanitize
 144      */
 145     public function __construct($string = '', $number = PMA_Message::NOTICE,
 146         $params = array(), $sanitize = PMA_Message::SANITIZE_NONE)
 147     {
 148         $this->setString($string, $sanitize & PMA_Message::SANITIZE_STRING);
 149         $this->setNumber($number);
 150         $this->setParams($params, $sanitize & PMA_Message::SANITIZE_PARAMS);
 151     }
 152
 153     /**
 154      * magic method: return string representation for this object
 155      *
 156      * @return string
 157      */
 158     public function __toString()
 159     {
 160         return $this->getMessage();
 161     }
 162
 163     /**
 164      * get PMA_Message of type success
 165      *
 166      * shorthand for getting a simple success message
 167      *
 168      * @static
 169      * @param   string $string a localized string e.g. __('Your SQL query has been executed successfully')
 170      * @return  PMA_Message
 171      */
 172     static public function success($string = '')
 173     {
 174         if (empty($string)) {
 175             $string = __('Your SQL query has been executed successfully');
 176         }
 177
 178         return new PMA_Message($string, PMA_Message::SUCCESS);
 179     }
 180
 181     /**
 182      * get PMA_Message of type error
 183      *
 184      * shorthand for getting a simple error message
 185      *
 186      * @static
 187      * @param   string $string a localized string e.g. __('Error')
 188      * @return  PMA_Message
 189      */
 190     static public function error($string = '')
 191     {
 192         if (empty($string)) {
 193             $string = __('Error');
 194         }
 195
 196         return new PMA_Message($string, PMA_Message::ERROR);
 197     }
 198
 199     /**
 200      * get PMA_Message of type notice
 201      *
 202      * shorthand for getting a simple notice message
 203      *
 204      * @static
 205      * @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.')
 206      * @return  PMA_Message
 207      */
 208     static public function notice($string)
 209     {
 210         return new PMA_Message($string, PMA_Message::NOTICE);
 211     }
 212
 213     /**
 214      * get PMA_Message with customized content
 215      *
 216      * shorthand for getting a customized message
 217      *
 218      * @static
 219      * @param   string    $message
 220      * @param   integer   $type
 221      * @return  PMA_Message
 222      */
 223     static public function raw($message, $type = PMA_Message::NOTICE)
 224     {
 225         $r = new PMA_Message('', $type);
 226         $r->setMessage($message);
 227         return $r;
 228     }
 229
 230     /**
 231      * get PMA_Message for number of affected rows
 232      *
 233      * shorthand for getting a customized message
 234      *
 235      * @static
 236      * @param   integer   $rows Number of rows
 237      * @return  PMA_Message
 238      */
 239     static public function affected_rows($rows)
 240     {
 241         $message = PMA_Message::success(_ngettext('%1$d row affected.', '%1$d rows affected.', $rows));
 242         $message->addParam($rows);
 243         return $message;
 244     }
 245
 246     /**
 247      * get PMA_Message for number of deleted rows
 248      *
 249      * shorthand for getting a customized message
 250      *
 251      * @static
 252      * @param   integer   $rows Number of rows
 253      * @return  PMA_Message
 254      */
 255     static public function deleted_rows($rows)
 256     {
 257         $message = PMA_Message::success(_ngettext('%1$d row deleted.', '%1$d rows deleted.', $rows));
 258         $message->addParam($rows);
 259         return $message;
 260     }
 261
 262     /**
 263      * get PMA_Message for number of inserted rows
 264      *
 265      * shorthand for getting a customized message
 266      *
 267      * @static
 268      * @param   integer   $rows Number of rows
 269      * @return  PMA_Message
 270      */
 271     static public function inserted_rows($rows)
 272     {
 273         $message = PMA_Message::success(_ngettext('%1$d row inserted.', '%1$d rows inserted.', $rows));
 274         $message->addParam($rows);
 275         return $message;
 276     }
 277
 278     /**
 279      * get PMA_Message of type error with custom content
 280      *
 281      * shorthand for getting a customized error message
 282      *
 283      * @static
 284      * @param   string  $message
 285      * @return  PMA_Message
 286      */
 287     static public function rawError($message)
 288     {
 289         return PMA_Message::raw($message, PMA_Message::ERROR);
 290     }
 291
 292     /**
 293      * get PMA_Message of type notice with custom content
 294      *
 295      * shorthand for getting a customized notice message
 296      *
 297      * @static
 298      * @param   string  $message
 299      * @return  PMA_Message
 300      */
 301     static public function rawNotice($message)
 302     {
 303         return PMA_Message::raw($message, PMA_Message::NOTICE);
 304     }
 305
 306     /**
 307      * get PMA_Message of type success with custom content
 308      *
 309      * shorthand for getting a customized success message
 310      *
 311      * @static
 312      * @param   string  $message
 313      * @return  PMA_Message
 314      */
 315     static public function rawSuccess($message)
 316     {
 317         return PMA_Message::raw($message, PMA_Message::SUCCESS);
 318     }
 319
 320     /**
 321      * returns whether this message is a success message or not
 322      * and optionaly makes this message a success message
 323      *
 324      * @param   boolean $set
 325      * @return  boolean whether this is a success message or not
 326      */
 327     public function isSuccess($set = false)
 328     {
 329         if ($set) {
 330             $this->setNumber(PMA_Message::SUCCESS);
 331         }
 332
 333         return $this->getNumber() === PMA_Message::SUCCESS;
 334     }
 335
 336     /**
 337      * returns whether this message is a notice message or not
 338      * and optionally makes this message a notice message
 339      *
 340      * @param   boolean $set
 341      * @return  boolean whether this is a notice message or not
 342      */
 343     public function isNotice($set = false)
 344     {
 345         if ($set) {
 346             $this->setNumber(PMA_Message::NOTICE);
 347         }
 348
 349         return $this->getNumber() === PMA_Message::NOTICE;
 350     }
 351
 352     /**
 353      * returns whether this message is an error message or not
 354      * and optionally makes this message an error message
 355      *
 356      * @param   boolean $set
 357      * @return  boolean whether this is an error message or not
 358      */
 359     public function isError($set = false)
 360     {
 361         if ($set) {
 362             $this->setNumber(PMA_Message::ERROR);
 363         }
 364
 365         return $this->getNumber() === PMA_Message::ERROR;
 366     }
 367
 368     /**
 369      * set raw message (overrides string)
 370      *
 371      * @param   string  $message
 372      * @param   boolean $sanitize whether to sanitize $message or not
 373      */
 374     public function setMessage($message, $sanitize = false)
 375     {
 376         if ($sanitize) {
 377             $message = PMA_Message::sanitize($message);
 378         }
 379         $this->_message = $message;
 380     }
 381
 382     /**
 383      * set string (does not take effect if raw message is set)
 384      *
 385      * @param   string  $_string
 386      * @param   boolean $sanitize whether to sanitize $string or not
 387      */
 388     public function setString($_string, $sanitize = true)
 389     {
 390         if ($sanitize) {
 391             $_string = PMA_Message::sanitize($_string);
 392         }
 393         $this->_string = $_string;
 394     }
 395
 396     /**
 397      * set message type number
 398      *
 399      * @param   integer $number
 400      */
 401     public function setNumber($number)
 402     {
 403         $this->_number = $number;
 404     }
 405
 406     /**
 407      * add parameter, usually in conjunction with strings
 408      *
 409      * usage
 410      * <code>
 411      * $message->addParam('strLocale', false);
 412      * $message->addParam('[em]some string[/em]');
 413      * $message->addParam('<img src="img" />', false);
 414      * </code>
 415      *
 416      * @param   mixed   $param
 417      * @param   boolean $raw
 418      */
 419     public function addParam($param, $raw = true)
 420     {
 421         if ($param instanceof PMA_Message) {
 422             $this->_params[] = $param;
 423         } elseif ($raw) {
 424             $this->_params[] = htmlspecialchars($param);
 425         } else {
 426             $this->_params[] = PMA_Message::notice($param);
 427         }
 428     }
 429
 430     /**
 431      * add another string to be concatenated on displaying
 432      *
 433      * @param   string  $string    to be added
 434      * @param   string  $separator to use between this and previous string/message
 435      */
 436     public function addString($string, $separator = ' ')
 437     {
 438         $this->_added_messages[] = $separator;
 439         $this->_added_messages[] = PMA_Message::notice($string);
 440     }
 441
 442     /**
 443      * add a bunch of messages at once
 444      *
 445      * @param   array   $messages  to be added
 446      * @param   string  $separator to use between this and previous string/message
 447      */
 448     public function addMessages($messages, $separator = ' ')
 449     {
 450         foreach ($messages as $message) {
 451             $this->addMessage($message, $separator);
 452         }
 453     }
 454
 455     /**
 456      * add another raw message to be concatenated on displaying
 457      *
 458      * @param   mixed   $message   to be added
 459      * @param   string  $separator to use between this and previous string/message
 460      */
 461     public function addMessage($message, $separator = ' ')
 462     {
 463         if (strlen($separator)) {
 464             $this->_added_messages[] = $separator;
 465         }
 466
 467         if ($message instanceof PMA_Message) {
 468             $this->_added_messages[] = $message;
 469         } else {
 470             $this->_added_messages[] = PMA_Message::rawNotice($message);
 471         }
 472     }
 473
 474     /**
 475      * set all params at once, usually used in conjunction with string
 476      *
 477      * @param   array   $params
 478      * @param   boolean $sanitize
 479      */
 480     public function setParams($params, $sanitize = false)
 481     {
 482         if ($sanitize) {
 483             $params = PMA_Message::sanitize($params);
 484         }
 485         $this->_params = $params;
 486     }
 487
 488     /**
 489      * return all parameters
 490      *
 491      * @return array
 492      */
 493     public function getParams()
 494     {
 495         return $this->_params;
 496     }
 497
 498     /**
 499      * return all added messages
 500      *
 501      * @return array
 502      */
 503     public function getAddedMessages()
 504     {
 505         return $this->_added_messages;
 506     }
 507
 508     /**
 509      * Sanitizes $message
 510      *
 511      * @static
 512      * @param   mixed  $message the message(s)
 513      * @return  mixed  the sanitized message(s)
 514      * @access  public
 515      */
 516     static public function sanitize($message)
 517     {
 518         if (is_array($message)) {
 519             foreach ($message as $key => $val) {
 520                 $message[$key] = PMA_Message::sanitize($val);
 521             }
 522
 523             return $message;
 524         }
 525
 526         return htmlspecialchars($message);
 527     }
 528
 529     /**
 530      * decode $message, taking into account our special codes
 531      * for formatting
 532      *
 533      * @static
 534      * @param   string  $message the message
 535      * @return  string  the decoded message
 536      * @access  public
 537      */
 538     static public function decodeBB($message)
 539     {
 540         return PMA_sanitize($message, false, true);
 541     }
 542
 543     /**
 544      * wrapper for sprintf()
 545      *
 546      * @return  string formatted
 547      */
 548     static public function format()
 549     {
 550         $params = func_get_args();
 551         if (isset($params[1]) && is_array($params[1])) {
 552             array_unshift($params[1], $params[0]);
 553             $params = $params[1];
 554         }
 555
 556         return call_user_func_array('sprintf', $params);
 557     }
 558
 559     /**
 560      * returns unique PMA_Message::$_hash, if not exists it will be created
 561      *
 562      * @return  string PMA_Message::$_hash
 563      */
 564     public function getHash()
 565     {
 566         if (null === $this->_hash) {
 567             $this->_hash = md5(
 568                 $this->getNumber() .
 569                 $this->_string .
 570                 $this->_message
 571             );
 572         }
 573
 574         return $this->_hash;
 575     }
 576
 577     /**
 578      * returns compiled message
 579      *
 580      * @return  string complete message
 581      */
 582     public function getMessage()
 583     {
 584         $message = $this->_message;
 585
 586         if (0 === strlen($message)) {
 587             $string = $this->getString();
 588             if (isset($GLOBALS[$string])) {
 589                 $message = $GLOBALS[$string];
 590             } elseif (0 === strlen($string)) {
 591                 $message = '';
 592             } else {
 593                 $message = $string;
 594             }
 595         }
 596
 597         if (count($this->getParams()) > 0) {
 598             $message = PMA_Message::format($message, $this->getParams());
 599         }
 600
 601         $message = PMA_Message::decodeBB($message);
 602
 603         foreach ($this->getAddedMessages() as $add_message) {
 604             $message .= $add_message;
 605         }
 606
 607         return $message;
 608     }
 609
 610     /**
 611      * returns PMA_Message::$_string
 612      *
 613      * @return  string PMA_Message::$_string
 614      */
 615     public function getString()
 616     {
 617         return $this->_string;
 618     }
 619
 620     /**
 621      * returns PMA_Message::$_number
 622      *
 623      * @return  integer PMA_Message::$_number
 624      */
 625     public function getNumber()
 626     {
 627         return $this->_number;
 628     }
 629
 630     /**
 631      * returns level of message
 632      *
 633      * @return  string  level of message
 634      */
 635     public function getLevel()
 636     {
 637         return PMA_Message::$level[$this->getNumber()];
 638     }
 639
 640     /**
 641      * Displays the message in HTML
 642      *
 643      */
 644     public function display()
 645     {
 646         echo $this->getDisplay();
 647         $this->isDisplayed(true);
 648     }
 649
 650     /**
 651      * returns HTML code for displaying this message
 652      *
 653      *
 654      * @return string whole message box
 655      */
 656     public function getDisplay()
 657     {
 658         return '<div class="' . $this->getLevel() . '">'
 659             . $this->getMessage() . '</div>';
 660     }
 661
 662     /**
 663      * sets and returns whether the message was displayed or not
 664      *
 665      * @param   boolean $is_displayed
 666      * @return  boolean PMA_Message::$_is_displayed
 667      */
 668     public function isDisplayed($is_displayed = false)
 669     {
 670         if ($is_displayed) {
 671             $this->_is_displayed = true;
 672         }
 673
 674         return $this->_is_displayed;
 675     }
 676 }
 677 ?>