Translation update done using Pootle.
[phpmyadmin-themes.git] / libraries / Message.class.php
blob8783cdb970e984dae2b8c46c07230758b3455cdc
1 <?php
2 /* vim: set expandtab sw=4 ts=4 sts=4: */
3 /**
4 * Holds class PMA_Message
6 * @package phpMyAdmin
7 */
9 /**
10 * a single message
12 * simple usage examples:
13 * <code>
14 * // display simple error message 'Error'
15 * PMA_Message::error()->display();
17 * // get simple success message 'Success'
18 * $message = PMA_Message::success();
20 * // get special notice 'Some locale notice'
21 * $message = PMA_Message::notice('strSomeLocaleNotice');
23 * // display raw warning message 'This is a warning!'
24 * PMA_Message::rawWarning('This is a warning!')->display();
25 * </code>
27 * more advanced usage example:
28 * <code>
29 * // create a localized success message
30 * $message = PMA_Message::success('strSomeLocaleMessage');
32 * // create another message, a hint, with a localized string which expects
33 * // two parameters: $strSomeFootnote = 'Read the %smanual%s'
34 * $hint = PMA_Message::notice('strSomeFootnote');
35 * // replace %d with the following params
36 * $hint->addParam('[a@./Documentation.html#cfg_Example@_blank]');
37 * $hint->addParam('[/a]');
38 * // add this hint as a footnote
39 * $hint = PMA_showHint($hint);
41 * // add the retrieved footnote reference to the original message
42 * $message->addMessage($hint);
44 * // create another message ...
45 * $more = PMA_Message::notice('strSomeMoreLocale');
46 * $more->addString('strSomeEvenMoreLocale', '<br />');
47 * $more->addParam('parameter for strSomeMoreLocale');
48 * $more->addParam('more parameter for strSomeMoreLocale');
50 * // and add it also to the original message
51 * $message->addMessage($more);
52 * // finally add another raw message
53 * $message->addMessage('some final words', ' - ');
55 * // display() will now print all messages in the same order as they are added
56 * $message->display();
57 * // strSomeLocaleMessage <sup>1</sup> strSomeMoreLocale<br />
58 * // strSomeEvenMoreLocale - some final words
59 * </code>
60 * @package phpMyAdmin
62 class PMA_Message
64 const SUCCESS = 1; // 0001
65 const NOTICE = 2; // 0010
66 const WARNING = 4; // 0100
67 const ERROR = 8; // 1000
69 const SANITIZE_NONE = 0; // 0000 0000
70 const SANITIZE_STRING = 16; // 0001 0000
71 const SANITIZE_PARAMS = 32; // 0010 0000
72 const SANITIZE_BOOTH = 48; // 0011 0000
74 /**
75 * message levels
77 * @var array
79 static public $level = array (
80 PMA_Message::SUCCESS => 'success',
81 PMA_Message::NOTICE => 'notice',
82 PMA_Message::WARNING => 'warning',
83 PMA_Message::ERROR => 'error',
86 /**
87 * The message number
89 * @access protected
90 * @var integer
92 protected $_number = PMA_Message::NOTICE;
94 /**
95 * The locale string identifier
97 * @access protected
98 * @var string
100 protected $_string = '';
103 * The formatted message
105 * @access protected
106 * @var string
108 protected $_message = '';
111 * Whether the message was already displayed
113 * @access protected
114 * @var boolean
116 protected $_is_displayed = false;
119 * Unique id
121 * @access protected
122 * @var string
124 protected $_hash = null;
127 * holds parameters
129 * @access protected
130 * @var array
132 protected $_params = array();
135 * holds additional messages
137 * @access protected
138 * @var array
140 protected $_added_messages = array();
143 * Constructor
145 * @uses PMA_Message::setNumber()
146 * @uses PMA_Message::setString()
147 * @uses PMA_Message::setParams()
148 * @uses PMA_Message::NOTICE
149 * @uses PMA_Message::SANITIZE_NONE
150 * @uses PMA_Message::SANITIZE_STRING
151 * @uses PMA_Message::SANITIZE_PARAMS
152 * @param string $string
153 * @param integer $number
154 * @param array $$params
155 * @param boolean $sanitize
157 public function __construct($string = '', $number = PMA_Message::NOTICE,
158 $params = array(), $sanitize = PMA_Message::SANITIZE_NONE)
160 $this->setString($string, $sanitize & PMA_Message::SANITIZE_STRING);
161 $this->setNumber($number);
162 $this->setParams($params, $sanitize & PMA_Message::SANITIZE_PARAMS);
166 * magic method: return string representation for this object
168 * @uses PMA_Message::getMessage()
169 * @return string
171 public function __toString()
173 return $this->getMessage();
177 * get PMA_Message of type success
179 * shorthand for getting a simple success message
181 * @static
182 * @uses PMA_Message as returned object
183 * @uses PMA_Message::SUCCESS
184 * @param string $string a localized string e.g. __('Your SQL query has been executed successfully')
185 * @return PMA_Message
187 static public function success($string = '')
189 if (empty($string)) {
190 $string = __('Your SQL query has been executed successfully');
193 return new PMA_Message($string, PMA_Message::SUCCESS);
197 * get PMA_Message of type error
199 * shorthand for getting a simple error message
201 * @static
202 * @uses PMA_Message as returned object
203 * @uses PMA_Message::ERROR
204 * @param string $string a localized string e.g. __('Error')
205 * @return PMA_Message
207 static public function error($string = '')
209 if (empty($string)) {
210 $string = __('Error');
213 return new PMA_Message($string, PMA_Message::ERROR);
217 * get PMA_Message of type warning
219 * shorthand for getting a simple warning message
221 * @static
222 * @uses PMA_Message as returned object
223 * @uses PMA_Message::WARNING
224 * @param string $string a localized string e.g. 'strSetupWarning'
225 * @return PMA_Message
227 static public function warning($string)
229 return new PMA_Message($string, PMA_Message::WARNING);
233 * get PMA_Message of type notice
235 * shorthand for getting a simple notice message
237 * @static
238 * @uses PMA_Message as returned object
239 * @uses PMA_Message::NOTICE
240 * @param string $string a localized string e.g. __('The additional features for working with linked tables have been deactivated. To find out why click %shere%s.')
241 * @return PMA_Message
243 static public function notice($string)
245 return new PMA_Message($string, PMA_Message::NOTICE);
249 * get PMA_Message with customized content
251 * shorthand for getting a customized message
253 * @static
254 * @uses PMA_Message as returned object
255 * @uses PMA_Message::setMessage()
256 * @param string $message
257 * @param integer $type
258 * @return PMA_Message
260 static public function raw($message, $type = PMA_Message::NOTICE)
262 $r = new PMA_Message('', $type);
263 $r->setMessage($message);
264 return $r;
268 * get PMA_Message for number of affected rows
270 * shorthand for getting a customized message
272 * @static
273 * @uses PMA_Message as returned object
274 * @uses PMA_Message::success()
275 * @uses PMA_Message::addParam()
276 * @param integer $rows Number of rows
277 * @return PMA_Message
279 static public function affected_rows($rows)
281 $message = PMA_Message::success(_ngettext('%1$d row affected.', '%1$d rows affected.', $rows));
282 $message->addParam($rows);
283 return $message;
287 * get PMA_Message for number of deleted rows
289 * shorthand for getting a customized message
291 * @static
292 * @uses PMA_Message as returned object
293 * @uses PMA_Message::success()
294 * @uses PMA_Message::addParam()
295 * @param integer $rows Number of rows
296 * @return PMA_Message
298 static public function deleted_rows($rows)
300 $message = PMA_Message::success(_ngettext('%1$d row deleted.', '%1$d rows deleted.', $rows));
301 $message->addParam($rows);
302 return $message;
306 * get PMA_Message for number of inserted rows
308 * shorthand for getting a customized message
310 * @static
311 * @uses PMA_Message as returned object
312 * @uses PMA_Message::success()
313 * @uses PMA_Message::addParam()
314 * @param integer $rows Number of rows
315 * @return PMA_Message
317 static public function inserted_rows($rows)
319 $message = PMA_Message::success(_ngettext('%1$d row inserted.', '%1$d rows inserted.', $rows));
320 $message->addParam($rows);
321 return $message;
325 * get PMA_Message of type error with custom content
327 * shorthand for getting a customized error message
329 * @static
330 * @uses PMA_Message::raw()
331 * @uses PMA_Message::ERROR
332 * @param string $message
333 * @return PMA_Message
335 static public function rawError($message)
337 return PMA_Message::raw($message, PMA_Message::ERROR);
341 * get PMA_Message of type warning with custom content
343 * shorthand for getting a customized warning message
345 * @static
346 * @uses PMA_Message::raw()
347 * @uses PMA_Message::WARNING
348 * @param string $message
349 * @return PMA_Message
351 static public function rawWarning($message)
353 return PMA_Message::raw($message, PMA_Message::WARNING);
357 * get PMA_Message of type notice with custom content
359 * shorthand for getting a customized notice message
361 * @static
362 * @uses PMA_Message::raw()
363 * @uses PMA_Message::NOTICE
364 * @param string $message
365 * @return PMA_Message
367 static public function rawNotice($message)
369 return PMA_Message::raw($message, PMA_Message::NOTICE);
373 * get PMA_Message of type success with custom content
375 * shorthand for getting a customized success message
377 * @static
378 * @uses PMA_Message::raw()
379 * @uses PMA_Message::SUCCESS
380 * @param string $message
381 * @return PMA_Message
383 static public function rawSuccess($message)
385 return PMA_Message::raw($message, PMA_Message::SUCCESS);
389 * returns whether this message is a success message or not
390 * and optionaly makes this message a success message
392 * @uses PMA_Message::SUCCESS
393 * @uses PMA_Message::setNumber()
394 * @uses PMA_Message::getNumber()
395 * @param boolean $set
396 * @return boolean whether this is a success message or not
398 public function isSuccess($set = false)
400 if ($set) {
401 $this->setNumber(PMA_Message::SUCCESS);
404 return $this->getNumber() === PMA_Message::SUCCESS;
408 * returns whether this message is a notice message or not
409 * and optionally makes this message a notice message
411 * @uses PMA_Message::NOTICE
412 * @uses PMA_Message::setNumber()
413 * @uses PMA_Message::getNumber()
414 * @param boolean $set
415 * @return boolean whether this is a notice message or not
417 public function isNotice($set = false)
419 if ($set) {
420 $this->setNumber(PMA_Message::NOTICE);
423 return $this->getNumber() === PMA_Message::NOTICE;
427 * returns whether this message is a warning message or not
428 * and optionally makes this message a warning message
430 * @uses PMA_Message::WARNING
431 * @uses PMA_Message::setNumber()
432 * @uses PMA_Message::getNumber()
433 * @param boolean $set
434 * @return boolean whether this is a warning message or not
436 public function isWarning($set = false)
438 if ($set) {
439 $this->setNumber(PMA_Message::WARNING);
442 return $this->getNumber() === PMA_Message::WARNING;
446 * returns whether this message is an error message or not
447 * and optionally makes this message an error message
449 * @uses PMA_Message::ERROR
450 * @uses PMA_Message::setNumber()
451 * @uses PMA_Message::getNumber()
452 * @param boolean $set
453 * @return boolean whether this is an error message or not
455 public function isError($set = false)
457 if ($set) {
458 $this->setNumber(PMA_Message::ERROR);
461 return $this->getNumber() === PMA_Message::ERROR;
465 * set raw message (overrides string)
467 * @uses PMA_Message::$_message to set it
468 * @uses PMA_Message::sanitize()
469 * @param string $message
470 * @param boolean $sanitize whether to sanitize $message or not
472 public function setMessage($message, $sanitize = false)
474 if ($sanitize) {
475 $message = PMA_Message::sanitize($message);
477 $this->_message = $message;
481 * set string (does not take effect if raw message is set)
483 * @uses PMA_Message::$_string to set it
484 * @uses PMA_Message::sanitize()
485 * @param string $_string
486 * @param boolean $sanitize whether to sanitize $string or not
488 public function setString($_string, $sanitize = true)
490 if ($sanitize) {
491 $_string = PMA_Message::sanitize($_string);
493 $this->_string = $_string;
497 * set message type number
499 * @uses PMA_Message::$_number to set it
500 * @param integer $number
502 public function setNumber($number)
504 $this->_number = $number;
508 * add parameter, usually in conjunction with strings
510 * usage
511 * <code>
512 * $message->addParam('strLocale', false);
513 * $message->addParam('[em]some string[/em]');
514 * $message->addParam('<img src="img" />', false);
515 * </code>
517 * @uses htmlspecialchars()
518 * @uses PMA_Message::$_params to fill
519 * @uses PMA_Message::notice()
520 * @param mixed $param
521 * @param boolean $raw
523 public function addParam($param, $raw = true)
525 if ($param instanceof PMA_Message) {
526 $this->_params[] = $param;
527 } elseif ($raw) {
528 $this->_params[] = htmlspecialchars($param);
529 } else {
530 $this->_params[] = PMA_Message::notice($param);
535 * add another string to be concatenated on displaying
537 * @uses PMA_Message::$_added_messages to fill
538 * @uses PMA_Message::notice()
539 * @param string $string to be added
540 * @param string $separator to use between this and previous string/message
542 public function addString($string, $separator = ' ')
544 $this->_added_messages[] = $separator;
545 $this->_added_messages[] = PMA_Message::notice($string);
549 * add a bunch of messages at once
551 * @uses PMA_Message::addMessage()
552 * @param array $messages to be added
553 * @param string $separator to use between this and previous string/message
555 public function addMessages($messages, $separator = ' ')
557 foreach ($messages as $message) {
558 $this->addMessage($message, $separator);
563 * add another raw message to be concatenated on displaying
565 * @uses PMA_Message::$_added_messages to fill
566 * @uses PMA_Message::rawNotice()
567 * @param mixed $message to be added
568 * @param string $separator to use between this and previous string/message
570 public function addMessage($message, $separator = ' ')
572 if (strlen($separator)) {
573 $this->_added_messages[] = $separator;
576 if ($message instanceof PMA_Message) {
577 $this->_added_messages[] = $message;
578 } else {
579 $this->_added_messages[] = PMA_Message::rawNotice($message);
584 * set all params at once, usually used in conjunction with string
586 * @uses PMA_Message::sanitize()
587 * @uses PMA_Message::$_params to set
588 * @param array $params
589 * @param boolean $sanitize
591 public function setParams($params, $sanitize = false)
593 if ($sanitize) {
594 $params = PMA_Message::sanitize($params);
596 $this->_params = $params;
600 * return all parameters
602 * @uses PMA_Message::$_params as return value
603 * @return array
605 public function getParams()
607 return $this->_params;
611 * return all added messages
613 * @uses PMA_Message::$_added_messages as return value
614 * @return array
616 public function getAddedMessages()
618 return $this->_added_messages;
622 * Sanitizes $message
624 * @static
625 * @uses is_array()
626 * @uses htmlspecialchars()
627 * @uses PMA_Message::sanitize() recursiv
628 * @param mixed the message(s)
629 * @return mixed the sanitized message(s)
630 * @access public
632 static public function sanitize($message)
634 if (is_array($message)) {
635 foreach ($message as $key => $val) {
636 $message[$key] = PMA_Message::sanitize($val);
639 return $message;
642 return htmlspecialchars($message);
646 * decode $message, taking into account our special codes
647 * for formatting
649 * @static
650 * @uses PREG_SET_ORDER
651 * @uses in_array()
652 * @uses preg_match_all()
653 * @uses preg_match()
654 * @uses preg_replace()
655 * @uses substr()
656 * @uses strtr()
657 * @param string $message the message
658 * @return string the decoded message
659 * @access public
661 static public function decodeBB($message)
663 $replace_pairs = array(
664 '[i]' => '<em>', // deprecated by em
665 '[/i]' => '</em>', // deprecated by em
666 '[em]' => '<em>',
667 '[/em]' => '</em>',
668 '[b]' => '<strong>', // deprecated by strong
669 '[/b]' => '</strong>', // deprecated by strong
670 '[strong]' => '<strong>',
671 '[/strong]' => '</strong>',
672 '[tt]' => '<code>', // deprecated by CODE or KBD
673 '[/tt]' => '</code>', // deprecated by CODE or KBD
674 '[code]' => '<code>',
675 '[/code]' => '</code>',
676 '[kbd]' => '<kbd>',
677 '[/kbd]' => '</kbd>',
678 '[br]' => '<br />',
679 '[/a]' => '</a>',
680 '[sup]' => '<sup>',
681 '[/sup]' => '</sup>',
684 $message = strtr($message, $replace_pairs);
686 $pattern = '/\[a@([^"@]*)@([^]"]*)\]/';
688 if (preg_match_all($pattern, $message, $founds, PREG_SET_ORDER)) {
689 $valid_links = array(
690 'http', // default http:// links (and https://)
691 './Do', // ./Documentation
694 foreach ($founds as $found) {
695 // only http... and ./Do... allowed
696 if (! in_array(substr($found[1], 0, 4), $valid_links)) {
697 return $message;
699 // a-z and _ allowed in target
700 if (! empty($found[2]) && preg_match('/[^a-z_]+/i', $found[2])) {
701 return $message;
705 $message = preg_replace($pattern, '<a href="\1" target="\2">', $message);
708 return $message;
712 * wrapper for sprintf()
714 * @uses sprintf()
715 * @uses func_get_args()
716 * @uses is_array()
717 * @uses array_unshift()
718 * @uses call_user_func_array()
719 * @return string formatted
721 static public function format()
723 $params = func_get_args();
724 if (isset($params[1]) && is_array($params[1])) {
725 array_unshift($params[1], $params[0]);
726 $params = $params[1];
729 return call_user_func_array('sprintf', $params);
733 * returns unique PMA_Message::$_hash, if not exists it will be created
735 * @uses PMA_Message::$_hash as return value and to set it if required
736 * @uses PMA_Message::getNumber()
737 * @uses PMA_Message::$_string
738 * @uses PMA_Message::$_message
739 * @uses md5()
740 * @param string $file
741 * @return string PMA_Message::$_hash
743 public function getHash()
745 if (null === $this->_hash) {
746 $this->_hash = md5(
747 $this->getNumber() .
748 $this->_string .
749 $this->_message
753 return $this->_hash;
757 * returns compiled message
759 * @uses PMA_Message::$_message as return value
760 * @uses PMA_Message::getString()
761 * @uses PMA_Message::getParams()
762 * @uses PMA_Message::format()
763 * @uses PMA_Message::decodeBB()
764 * @uses PMA_Message::getAddedMessages()
765 * @uses strlen()
766 * @return string complete message
768 public function getMessage()
770 $message = $this->_message;
772 if (0 === strlen($message)) {
773 $string = $this->getString();
774 if (isset($GLOBALS[$string])) {
775 $message = $GLOBALS[$string];
776 } elseif (0 === strlen($string)) {
777 $message = '';
778 } else {
779 $message = $string;
783 if (count($this->getParams()) > 0) {
784 $message = PMA_Message::format($message, $this->getParams());
787 $message = PMA_Message::decodeBB($message);
789 foreach ($this->getAddedMessages() as $add_message) {
790 $message .= $add_message;
793 return $message;
797 * returns PMA_Message::$_string
799 * @uses PMA_Message::$_string as return value
800 * @return string PMA_Message::$_string
802 public function getString()
804 return $this->_string;
808 * returns PMA_Message::$_number
810 * @uses PMA_Message::$_number as return value
811 * @return integer PMA_Message::$_number
813 public function getNumber()
815 return $this->_number;
819 * returns level of message
821 * @uses PMA_Message::$level
822 * @uses PMA_Message::getNumber()
823 * @return string level of message
825 public function getLevel()
827 return PMA_Message::$level[$this->getNumber()];
831 * Displays the message in HTML
833 * @uses PMA_Message::getLevel()
834 * @uses PMA_Message::getMessage()
835 * @uses PMA_Message::isDisplayed()
837 public function display()
839 echo $this->getDisplay();
840 $this->isDisplayed(true);
844 * returns HTML code for displaying this message
846 * @return string whole message box
848 public function getDisplay()
850 return '<div class="' . $this->getLevel() . '">'
851 . $this->getMessage() . '</div>';
855 * sets and returns whether the message was displayed or not
857 * @uses PMA_Message::$_is_displayed to set it and/or return it
858 * @param boolean $is_displayed
859 * @return boolean PMA_Message::$_is_displayed
861 public function isDisplayed($is_displayed = false)
863 if ($is_displayed) {
864 $this->_is_displayed = true;
867 return $this->_is_displayed;