libraries/Message.class.php

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