PageRenderTime 48ms CodeModel.GetById 21ms RepoModel.GetById 0ms app.codeStats 0ms

/src/frapi/library/Zend/Translate/Adapter.php

http://github.com/frapi/frapi
PHP | 780 lines | 423 code | 87 blank | 270 comment | 112 complexity | 649985bb2c2a98fba3ac7f6eb6dda216 MD5 | raw file
Possible License(s): BSD-2-Clause
  1. <?php
  2. /**
  3. * Zend Framework
  4. *
  5. * LICENSE
  6. *
  7. * This source file is subject to the new BSD license that is bundled
  8. * with this package in the file LICENSE.txt.
  9. * It is also available through the world-wide-web at this URL:
  10. * http://framework.zend.com/license/new-bsd
  11. * If you did not receive a copy of the license and are unable to
  12. * obtain it through the world-wide-web, please send an email
  13. * to license@zend.com so we can send you a copy immediately.
  14. *
  15. * @category Zend
  16. * @package Zend_Translate
  17. * @subpackage Zend_Translate_Adapter
  18. * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  19. * @license http://framework.zend.com/license/new-bsd New BSD License
  20. * @version $Id: Adapter.php 20403 2010-01-18 21:29:52Z thomas $
  21. */
  22. /**
  23. * @see Zend_Locale
  24. */
  25. // require_once 'Zend/Locale.php';
  26. /**
  27. * @see Zend_Translate_Plural
  28. */
  29. // require_once 'Zend/Translate/Plural.php';
  30. /**
  31. * Basic adapter class for each translation source adapter
  32. *
  33. * @category Zend
  34. * @package Zend_Translate
  35. * @subpackage Zend_Translate_Adapter
  36. * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  37. * @license http://framework.zend.com/license/new-bsd New BSD License
  38. */
  39. abstract class Zend_Translate_Adapter {
  40. /**
  41. * Shows if locale detection is in automatic level
  42. * @var boolean
  43. */
  44. private $_automatic = true;
  45. /**
  46. * Internal cache for all adapters
  47. * @var Zend_Cache_Core
  48. */
  49. protected static $_cache = null;
  50. /**
  51. * Scans for the locale within the name of the directory
  52. * @constant integer
  53. */
  54. const LOCALE_DIRECTORY = 'directory';
  55. /**
  56. * Scans for the locale within the name of the file
  57. * @constant integer
  58. */
  59. const LOCALE_FILENAME = 'filename';
  60. /**
  61. * Array with all options, each adapter can have own additional options
  62. * 'clear' => when true, clears already loaded data when adding new files
  63. * 'disableNotices' => when true, omits notices from being displayed
  64. * 'ignore' => a prefix for files and directories which are not being added
  65. * 'locale' => the actual set locale to use
  66. * 'log' => a instance of Zend_Log where logs are written to
  67. * 'logMessage' => message to be logged
  68. * 'logUntranslated' => when true, untranslated messages are not logged
  69. * 'reload' => reloads the cache by reading the content again
  70. * 'scan' => searches for translation files using the LOCALE constants
  71. *
  72. * @var array
  73. */
  74. protected $_options = array(
  75. 'clear' => false,
  76. 'disableNotices' => false,
  77. 'ignore' => '.',
  78. 'locale' => 'auto',
  79. 'log' => null,
  80. 'logMessage' => "Untranslated message within '%locale%': %message%",
  81. 'logUntranslated' => false,
  82. 'reload' => false,
  83. 'scan' => null
  84. );
  85. /**
  86. * Translation table
  87. * @var array
  88. */
  89. protected $_translate = array();
  90. /**
  91. * Generates the adapter
  92. *
  93. * @param string|array $data OPTIONAL Translation data or filename for this adapter
  94. * @param string|Zend_Locale $locale OPTIONAL Locale/Language to set, identical with Locale
  95. * identifiers see Zend_Locale for more information
  96. * @param array $options OPTIONAL Options for the adaptor
  97. * @throws Zend_Translate_Exception
  98. * @return void
  99. */
  100. public function __construct($data = null, $locale = null, array $options = array())
  101. {
  102. if (isset(self::$_cache)) {
  103. $id = 'Zend_Translate_' . $this->toString() . '_Options';
  104. $result = self::$_cache->load($id);
  105. if ($result) {
  106. $this->_options = $result;
  107. }
  108. }
  109. if (($locale === "auto") or ($locale === null)) {
  110. $this->_automatic = true;
  111. } else {
  112. $this->_automatic = false;
  113. }
  114. $this->setOptions($options);
  115. if ($data !== null) {
  116. $this->addTranslation($data, $locale, $options);
  117. }
  118. if ($this->getLocale() !== (string) $locale) {
  119. $this->setLocale($locale);
  120. }
  121. }
  122. /**
  123. * Add translation data
  124. *
  125. * It may be a new language or additional data for existing language
  126. * If $clear parameter is true, then translation data for specified
  127. * language is replaced and added otherwise
  128. *
  129. * @param array|string $data Translation data
  130. * @param string|Zend_Locale $locale (optional) Locale/Language to add data for, identical
  131. * with locale identifier, see Zend_Locale for more information
  132. * @param array $options (optional) Option for this Adapter
  133. * @throws Zend_Translate_Exception
  134. * @return Zend_Translate_Adapter Provides fluent interface
  135. */
  136. public function addTranslation($data, $locale = null, array $options = array())
  137. {
  138. $originate = (string) $locale;
  139. if (array_key_exists('locale', $options)) {
  140. if ($locale == null) {
  141. $locale = $options['locale'];
  142. }
  143. unset($options['locale']);
  144. }
  145. if ((array_key_exists('log', $options)) && !($options['log'] instanceof Zend_Log)) {
  146. // require_once 'Zend/Translate/Exception.php';
  147. throw new Zend_Translate_Exception('Instance of Zend_Log expected for option log');
  148. }
  149. try {
  150. $locale = Zend_Locale::findLocale($locale);
  151. } catch (Zend_Locale_Exception $e) {
  152. // require_once 'Zend/Translate/Exception.php';
  153. throw new Zend_Translate_Exception("The given Language '{$locale}' does not exist", 0, $e);
  154. }
  155. $options = $options + $this->_options;
  156. if (is_string($data) and is_dir($data)) {
  157. $data = realpath($data);
  158. $prev = '';
  159. foreach (new RecursiveIteratorIterator(
  160. new RecursiveDirectoryIterator($data, RecursiveDirectoryIterator::KEY_AS_PATHNAME),
  161. RecursiveIteratorIterator::SELF_FIRST) as $directory => $info) {
  162. $file = $info->getFilename();
  163. if (strpos($directory, DIRECTORY_SEPARATOR . $options['ignore']) !== false) {
  164. // ignore files matching first characters from option 'ignore' and all files below
  165. continue;
  166. }
  167. if ($info->isDir()) {
  168. // pathname as locale
  169. if (($options['scan'] === self::LOCALE_DIRECTORY) and (Zend_Locale::isLocale($file, true, false))) {
  170. $locale = $file;
  171. $prev = (string) $locale;
  172. }
  173. } else if ($info->isFile()) {
  174. // filename as locale
  175. if ($options['scan'] === self::LOCALE_FILENAME) {
  176. $filename = explode('.', $file);
  177. array_pop($filename);
  178. $filename = implode('.', $filename);
  179. if (Zend_Locale::isLocale((string) $filename, true, false)) {
  180. $locale = (string) $filename;
  181. } else {
  182. $parts = explode('.', $file);
  183. $parts2 = array();
  184. foreach($parts as $token) {
  185. $parts2 += explode('_', $token);
  186. }
  187. $parts = array_merge($parts, $parts2);
  188. $parts2 = array();
  189. foreach($parts as $token) {
  190. $parts2 += explode('-', $token);
  191. }
  192. $parts = array_merge($parts, $parts2);
  193. $parts = array_unique($parts);
  194. $prev = '';
  195. foreach($parts as $token) {
  196. if (Zend_Locale::isLocale($token, true, false)) {
  197. if (strlen($prev) <= strlen($token)) {
  198. $locale = $token;
  199. $prev = $token;
  200. }
  201. }
  202. }
  203. }
  204. }
  205. try {
  206. $this->_addTranslationData($info->getPathname(), (string) $locale, $options);
  207. } catch (Zend_Translate_Exception $e) {
  208. // ignore failed sources while scanning
  209. }
  210. }
  211. }
  212. } else {
  213. $this->_addTranslationData($data, (string) $locale, $options);
  214. }
  215. if ((isset($this->_translate[$originate]) === true) and (count($this->_translate[$originate]) > 0)) {
  216. $this->setLocale($originate);
  217. }
  218. return $this;
  219. }
  220. /**
  221. * Sets new adapter options
  222. *
  223. * @param array $options Adapter options
  224. * @throws Zend_Translate_Exception
  225. * @return Zend_Translate_Adapter Provides fluent interface
  226. */
  227. public function setOptions(array $options = array())
  228. {
  229. $change = false;
  230. $locale = null;
  231. foreach ($options as $key => $option) {
  232. if ($key == 'locale') {
  233. $locale = $option;
  234. } else if ((isset($this->_options[$key]) and ($this->_options[$key] != $option)) or
  235. !isset($this->_options[$key])) {
  236. if (($key == 'log') && !($option instanceof Zend_Log)) {
  237. // require_once 'Zend/Translate/Exception.php';
  238. throw new Zend_Translate_Exception('Instance of Zend_Log expected for option log');
  239. }
  240. $this->_options[$key] = $option;
  241. $change = true;
  242. }
  243. }
  244. if ($locale !== null) {
  245. $this->setLocale($locale);
  246. }
  247. if (isset(self::$_cache) and ($change == true)) {
  248. $id = 'Zend_Translate_' . $this->toString() . '_Options';
  249. self::$_cache->save($this->_options, $id, array('Zend_Translate'));
  250. }
  251. return $this;
  252. }
  253. /**
  254. * Returns the adapters name and it's options
  255. *
  256. * @param string|null $optionKey String returns this option
  257. * null returns all options
  258. * @return integer|string|array|null
  259. */
  260. public function getOptions($optionKey = null)
  261. {
  262. if ($optionKey === null) {
  263. return $this->_options;
  264. }
  265. if (isset($this->_options[$optionKey]) === true) {
  266. return $this->_options[$optionKey];
  267. }
  268. return null;
  269. }
  270. /**
  271. * Gets locale
  272. *
  273. * @return Zend_Locale|string|null
  274. */
  275. public function getLocale()
  276. {
  277. return $this->_options['locale'];
  278. }
  279. /**
  280. * Sets locale
  281. *
  282. * @param string|Zend_Locale $locale Locale to set
  283. * @throws Zend_Translate_Exception
  284. * @return Zend_Translate_Adapter Provides fluent interface
  285. */
  286. public function setLocale($locale)
  287. {
  288. if (($locale === "auto") or ($locale === null)) {
  289. $this->_automatic = true;
  290. } else {
  291. $this->_automatic = false;
  292. }
  293. try {
  294. $locale = Zend_Locale::findLocale($locale);
  295. } catch (Zend_Locale_Exception $e) {
  296. // require_once 'Zend/Translate/Exception.php';
  297. throw new Zend_Translate_Exception("The given Language ({$locale}) does not exist", 0, $e);
  298. }
  299. if (!isset($this->_translate[$locale])) {
  300. $temp = explode('_', $locale);
  301. if (!isset($this->_translate[$temp[0]]) and !isset($this->_translate[$locale])) {
  302. if (!$this->_options['disableNotices']) {
  303. if ($this->_options['log']) {
  304. $this->_options['log']->notice("The language '{$locale}' has to be added before it can be used.");
  305. } else {
  306. trigger_error("The language '{$locale}' has to be added before it can be used.", E_USER_NOTICE);
  307. }
  308. }
  309. }
  310. $locale = $temp[0];
  311. }
  312. if (empty($this->_translate[$locale])) {
  313. if (!$this->_options['disableNotices']) {
  314. if ($this->_options['log']) {
  315. $this->_options['log']->notice("No translation for the language '{$locale}' available.");
  316. } else {
  317. trigger_error("No translation for the language '{$locale}' available.", E_USER_NOTICE);
  318. }
  319. }
  320. }
  321. if ($this->_options['locale'] != $locale) {
  322. $this->_options['locale'] = $locale;
  323. if (isset(self::$_cache)) {
  324. $id = 'Zend_Translate_' . $this->toString() . '_Options';
  325. self::$_cache->save($this->_options, $id, array('Zend_Translate'));
  326. }
  327. }
  328. return $this;
  329. }
  330. /**
  331. * Returns the available languages from this adapter
  332. *
  333. * @return array
  334. */
  335. public function getList()
  336. {
  337. $list = array_keys($this->_translate);
  338. $result = null;
  339. foreach($list as $value) {
  340. if (!empty($this->_translate[$value])) {
  341. $result[$value] = $value;
  342. }
  343. }
  344. return $result;
  345. }
  346. /**
  347. * Returns all available message ids from this adapter
  348. * If no locale is given, the actual language will be used
  349. *
  350. * @param string|Zend_Locale $locale (optional) Language to return the message ids from
  351. * @return array
  352. */
  353. public function getMessageIds($locale = null)
  354. {
  355. if (empty($locale) or !$this->isAvailable($locale)) {
  356. $locale = $this->_options['locale'];
  357. }
  358. return array_keys($this->_translate[(string) $locale]);
  359. }
  360. /**
  361. * Returns all available translations from this adapter
  362. * If no locale is given, the actual language will be used
  363. * If 'all' is given the complete translation dictionary will be returned
  364. *
  365. * @param string|Zend_Locale $locale (optional) Language to return the messages from
  366. * @return array
  367. */
  368. public function getMessages($locale = null)
  369. {
  370. if ($locale === 'all') {
  371. return $this->_translate;
  372. }
  373. if ((empty($locale) === true) or ($this->isAvailable($locale) === false)) {
  374. $locale = $this->_options['locale'];
  375. }
  376. return $this->_translate[(string) $locale];
  377. }
  378. /**
  379. * Is the wished language available ?
  380. *
  381. * @see Zend_Locale
  382. * @param string|Zend_Locale $locale Language to search for, identical with locale identifier,
  383. * @see Zend_Locale for more information
  384. * @return boolean
  385. */
  386. public function isAvailable($locale)
  387. {
  388. $return = isset($this->_translate[(string) $locale]);
  389. return $return;
  390. }
  391. /**
  392. * Load translation data
  393. *
  394. * @param mixed $data
  395. * @param string|Zend_Locale $locale
  396. * @param array $options (optional)
  397. * @return array
  398. */
  399. abstract protected function _loadTranslationData($data, $locale, array $options = array());
  400. /**
  401. * Internal function for adding translation data
  402. *
  403. * It may be a new language or additional data for existing language
  404. * If $clear parameter is true, then translation data for specified
  405. * language is replaced and added otherwise
  406. *
  407. * @see Zend_Locale
  408. * @param array|string $data Translation data
  409. * @param string|Zend_Locale $locale Locale/Language to add data for, identical with locale identifier,
  410. * @see Zend_Locale for more information
  411. * @param array $options (optional) Option for this Adapter
  412. * @throws Zend_Translate_Exception
  413. * @return Zend_Translate_Adapter Provides fluent interface
  414. */
  415. private function _addTranslationData($data, $locale, array $options = array())
  416. {
  417. try {
  418. $locale = Zend_Locale::findLocale($locale);
  419. } catch (Zend_Locale_Exception $e) {
  420. // require_once 'Zend/Translate/Exception.php';
  421. throw new Zend_Translate_Exception("The given Language '{$locale}' does not exist", 0, $e);
  422. }
  423. if ($options['clear'] || !isset($this->_translate[$locale])) {
  424. $this->_translate[$locale] = array();
  425. }
  426. $read = true;
  427. if (isset(self::$_cache)) {
  428. $id = 'Zend_Translate_' . md5(serialize($data)) . '_' . $this->toString();
  429. $temp = self::$_cache->load($id);
  430. if ($temp) {
  431. $read = false;
  432. }
  433. }
  434. if ($options['reload']) {
  435. $read = true;
  436. }
  437. if ($read) {
  438. $temp = $this->_loadTranslationData($data, $locale, $options);
  439. }
  440. if (empty($temp)) {
  441. $temp = array();
  442. }
  443. $keys = array_keys($temp);
  444. foreach($keys as $key) {
  445. if (!isset($this->_translate[$key])) {
  446. $this->_translate[$key] = array();
  447. }
  448. if (array_key_exists($key, $temp) && is_array($temp[$key])) {
  449. $this->_translate[$key] = $temp[$key] + $this->_translate[$key];
  450. }
  451. }
  452. if ($this->_automatic === true) {
  453. $find = new Zend_Locale($locale);
  454. $browser = $find->getEnvironment() + $find->getBrowser();
  455. arsort($browser);
  456. foreach($browser as $language => $quality) {
  457. if (isset($this->_translate[$language])) {
  458. $this->_options['locale'] = $language;
  459. break;
  460. }
  461. }
  462. }
  463. if (($read) and (isset(self::$_cache))) {
  464. $id = 'Zend_Translate_' . md5(serialize($data)) . '_' . $this->toString();
  465. self::$_cache->save($temp, $id, array('Zend_Translate'));
  466. }
  467. return $this;
  468. }
  469. /**
  470. * Translates the given string
  471. * returns the translation
  472. *
  473. * @see Zend_Locale
  474. * @param string|array $messageId Translation string, or Array for plural translations
  475. * @param string|Zend_Locale $locale (optional) Locale/Language to use, identical with
  476. * locale identifier, @see Zend_Locale for more information
  477. * @return string
  478. */
  479. public function translate($messageId, $locale = null)
  480. {
  481. if ($locale === null) {
  482. $locale = $this->_options['locale'];
  483. }
  484. $plural = null;
  485. if (is_array($messageId)) {
  486. if (count($messageId) > 2) {
  487. $number = array_pop($messageId);
  488. if (!is_numeric($number)) {
  489. $plocale = $number;
  490. $number = array_pop($messageId);
  491. } else {
  492. $plocale = 'en';
  493. }
  494. $plural = $messageId;
  495. $messageId = $messageId[0];
  496. } else {
  497. $messageId = $messageId[0];
  498. }
  499. }
  500. if (!Zend_Locale::isLocale($locale, true, false)) {
  501. if (!Zend_Locale::isLocale($locale, false, false)) {
  502. // language does not exist, return original string
  503. $this->_log($messageId, $locale);
  504. if ($plural === null) {
  505. return $messageId;
  506. }
  507. $rule = Zend_Translate_Plural::getPlural($number, $plocale);
  508. if (!isset($plural[$rule])) {
  509. $rule = 0;
  510. }
  511. return $plural[$rule];
  512. }
  513. $locale = new Zend_Locale($locale);
  514. }
  515. $locale = (string) $locale;
  516. if ((is_string($messageId) || is_int($messageId)) && isset($this->_translate[$locale][$messageId])) {
  517. // return original translation
  518. if ($plural === null) {
  519. return $this->_translate[$locale][$messageId];
  520. }
  521. $rule = Zend_Translate_Plural::getPlural($number, $locale);
  522. if (isset($this->_translate[$locale][$plural[0]][$rule])) {
  523. return $this->_translate[$locale][$plural[0]][$rule];
  524. }
  525. } else if (strlen($locale) != 2) {
  526. // faster than creating a new locale and separate the leading part
  527. $locale = substr($locale, 0, -strlen(strrchr($locale, '_')));
  528. if ((is_string($messageId) || is_int($messageId)) && isset($this->_translate[$locale][$messageId])) {
  529. // return regionless translation (en_US -> en)
  530. if ($plural === null) {
  531. return $this->_translate[$locale][$messageId];
  532. }
  533. $rule = Zend_Translate_Plural::getPlural($number, $locale);
  534. if (isset($this->_translate[$locale][$plural[0]][$rule])) {
  535. return $this->_translate[$locale][$plural[0]][$rule];
  536. }
  537. }
  538. }
  539. $this->_log($messageId, $locale);
  540. if ($plural === null) {
  541. return $messageId;
  542. }
  543. $rule = Zend_Translate_Plural::getPlural($number, $plocale);
  544. if (!isset($plural[$rule])) {
  545. $rule = 0;
  546. }
  547. return $plural[$rule];
  548. }
  549. /**
  550. * Translates the given string using plural notations
  551. * Returns the translated string
  552. *
  553. * @see Zend_Locale
  554. * @param string $singular Singular translation string
  555. * @param string $plural Plural translation string
  556. * @param integer $number Number for detecting the correct plural
  557. * @param string|Zend_Locale $locale (Optional) Locale/Language to use, identical with
  558. * locale identifier, @see Zend_Locale for more information
  559. * @return string
  560. */
  561. public function plural($singular, $plural, $number, $locale = null)
  562. {
  563. return $this->translate(array($singular, $plural, $number), $locale);
  564. }
  565. /**
  566. * Logs a message when the log option is set
  567. *
  568. * @param string $message Message to log
  569. * @param String $locale Locale to log
  570. */
  571. protected function _log($message, $locale) {
  572. if ($this->_options['logUntranslated']) {
  573. $message = str_replace('%message%', $message, $this->_options['logMessage']);
  574. $message = str_replace('%locale%', $locale, $message);
  575. if ($this->_options['log']) {
  576. $this->_options['log']->notice($message);
  577. } else {
  578. trigger_error($message, E_USER_NOTICE);
  579. }
  580. }
  581. }
  582. /**
  583. * Translates the given string
  584. * returns the translation
  585. *
  586. * @param string $messageId Translation string
  587. * @param string|Zend_Locale $locale (optional) Locale/Language to use, identical with locale
  588. * identifier, @see Zend_Locale for more information
  589. * @return string
  590. */
  591. public function _($messageId, $locale = null)
  592. {
  593. return $this->translate($messageId, $locale);
  594. }
  595. /**
  596. * Checks if a string is translated within the source or not
  597. * returns boolean
  598. *
  599. * @param string $messageId Translation string
  600. * @param boolean $original (optional) Allow translation only for original language
  601. * when true, a translation for 'en_US' would give false when it can
  602. * be translated with 'en' only
  603. * @param string|Zend_Locale $locale (optional) Locale/Language to use, identical with locale identifier,
  604. * see Zend_Locale for more information
  605. * @return boolean
  606. */
  607. public function isTranslated($messageId, $original = false, $locale = null)
  608. {
  609. if (($original !== false) and ($original !== true)) {
  610. $locale = $original;
  611. $original = false;
  612. }
  613. if ($locale === null) {
  614. $locale = $this->_options['locale'];
  615. }
  616. if (!Zend_Locale::isLocale($locale, true, false)) {
  617. if (!Zend_Locale::isLocale($locale, false, false)) {
  618. // language does not exist, return original string
  619. return false;
  620. }
  621. $locale = new Zend_Locale($locale);
  622. }
  623. $locale = (string) $locale;
  624. if ((is_string($messageId) || is_int($messageId)) && isset($this->_translate[$locale][$messageId])) {
  625. // return original translation
  626. return true;
  627. } else if ((strlen($locale) != 2) and ($original === false)) {
  628. // faster than creating a new locale and separate the leading part
  629. $locale = substr($locale, 0, -strlen(strrchr($locale, '_')));
  630. if ((is_string($messageId) || is_int($messageId)) && isset($this->_translate[$locale][$messageId])) {
  631. // return regionless translation (en_US -> en)
  632. return true;
  633. }
  634. }
  635. // No translation found, return original
  636. return false;
  637. }
  638. /**
  639. * Returns the set cache
  640. *
  641. * @return Zend_Cache_Core The set cache
  642. */
  643. public static function getCache()
  644. {
  645. return self::$_cache;
  646. }
  647. /**
  648. * Sets a cache for all Zend_Translate_Adapters
  649. *
  650. * @param Zend_Cache_Core $cache Cache to store to
  651. */
  652. public static function setCache(Zend_Cache_Core $cache)
  653. {
  654. self::$_cache = $cache;
  655. }
  656. /**
  657. * Returns true when a cache is set
  658. *
  659. * @return boolean
  660. */
  661. public static function hasCache()
  662. {
  663. if (self::$_cache !== null) {
  664. return true;
  665. }
  666. return false;
  667. }
  668. /**
  669. * Removes any set cache
  670. *
  671. * @return void
  672. */
  673. public static function removeCache()
  674. {
  675. self::$_cache = null;
  676. }
  677. /**
  678. * Clears all set cache data
  679. *
  680. * @return void
  681. */
  682. public static function clearCache()
  683. {
  684. // require_once 'Zend/Cache.php';
  685. self::$_cache->clean(Zend_Cache::CLEANING_MODE_MATCHING_TAG, array('Zend_Translate'));
  686. }
  687. /**
  688. * Returns the adapter name
  689. *
  690. * @return string
  691. */
  692. abstract public function toString();
  693. }