libraries/Message.class.php

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