f297db74122d5f41ec0c7d49af7c2076891c85c5
[core.git] / inc / classes / main / class_BaseFrameworkSystem.php
1 <?php
2 /**
3  * The simulator system class is the super class of all other classes. This
4  * class handles saving of games etc.
5  *
6  * @author              Roland Haeder <webmaster@ship-simu.org>
7  * @version             0.0.0
8  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 Core Developer Team
9  * @license             GNU GPL 3.0 or any newer version
10  * @link                http://www.ship-simu.org
11  *
12  * This program is free software: you can redistribute it and/or modify
13  * it under the terms of the GNU General Public License as published by
14  * the Free Software Foundation, either version 3 of the License, or
15  * (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program. If not, see <http://www.gnu.org/licenses/>.
24  */
25 class BaseFrameworkSystem extends stdClass implements FrameworkInterface {
26         /**
27          * Instance of a request class
28          */
29         private $requestInstance = null;
30
31         /**
32          * Instance of a response class
33          */
34         private $responseInstance = null;
35
36         /**
37          * Search criteria instance
38          */
39         private $searchInstance = null;
40
41         /**
42          * Update criteria instance
43          */
44         private $updateInstance = null;
45
46         /**
47          * The file I/O instance for the template loader
48          */
49         private $fileIoInstance = null;
50
51         /**
52          * Resolver instance
53          */
54         private $resolverInstance = null;
55
56         /**
57          * Template engine instance
58          */
59         private $templateInstance = null;
60
61         /**
62          * Database result instance
63          */
64         private $resultInstance = null;
65
66         /**
67          * Instance for user class
68          */
69         private $userInstance = null;
70
71         /**
72          * A controller instance
73          */
74         private $controllerInstance = null;
75
76         /**
77          * Instance of a RNG
78          */
79         private $rngInstance = null;
80
81         /**
82          * Instance of an Iterator class
83          */
84         private $iteratorInstance = null;
85
86         /**
87          * Instance of the list
88          */
89         private $listInstance = null;
90
91         /**
92          * Instance of a menu
93          */
94         private $menuInstance = null;
95
96         /**
97          * The real class name
98          */
99         private $realClass      = 'BaseFrameworkSystem';
100
101         /**
102          * Thousands seperator
103          */
104         private $thousands = '.'; // German
105
106         /**
107          * Decimal seperator
108          */
109         private $decimals  = ','; // German
110
111         /***********************
112          * Exception codes.... *
113          ***********************/
114         // @todo Try to clean these constants up
115         const EXCEPTION_IS_NULL_POINTER              = 0x001;
116         const EXCEPTION_IS_NO_OBJECT                 = 0x002;
117         const EXCEPTION_IS_NO_ARRAY                  = 0x003;
118         const EXCEPTION_MISSING_METHOD               = 0x004;
119         const EXCEPTION_CLASSES_NOT_MATCHING         = 0x005;
120         const EXCEPTION_INDEX_OUT_OF_BOUNDS          = 0x006;
121         const EXCEPTION_DIMENSION_ARRAY_INVALID      = 0x007;
122         const EXCEPTION_ITEM_NOT_TRADEABLE           = 0x008;
123         const EXCEPTION_ITEM_NOT_IN_PRICE_LIST       = 0x009;
124         const EXCEPTION_GENDER_IS_WRONG              = 0x00a;
125         const EXCEPTION_BIRTH_DATE_IS_INVALID        = 0x00b;
126         const EXCEPTION_EMPTY_STRUCTURES_ARRAY       = 0x00c;
127         const EXCEPTION_HAS_ALREADY_PERSONELL_LIST   = 0x00d;
128         const EXCEPTION_NOT_ENOUGTH_UNEMPLOYEES      = 0x00e;
129         const EXCEPTION_TOTAL_PRICE_NOT_CALCULATED   = 0x00f;
130         const EXCEPTION_HARBOR_HAS_NO_SHIPYARDS      = 0x010;
131         const EXCEPTION_CONTRACT_PARTNER_INVALID     = 0x011;
132         const EXCEPTION_CONTRACT_PARTNER_MISMATCH    = 0x012;
133         const EXCEPTION_CONTRACT_ALREADY_SIGNED      = 0x013;
134         const EXCEPTION_UNEXPECTED_EMPTY_STRING      = 0x014;
135         const EXCEPTION_PATH_NOT_FOUND               = 0x015;
136         const EXCEPTION_INVALID_PATH_NAME            = 0x016;
137         const EXCEPTION_READ_PROTECED_PATH           = 0x017;
138         const EXCEPTION_WRITE_PROTECED_PATH          = 0x018;
139         const EXCEPTION_DIR_POINTER_INVALID          = 0x019;
140         const EXCEPTION_FILE_POINTER_INVALID         = 0x01a;
141         const EXCEPTION_INVALID_RESOURCE             = 0x01b;
142         const EXCEPTION_UNEXPECTED_OBJECT            = 0x01c;
143         const EXCEPTION_LIMIT_ELEMENT_IS_UNSUPPORTED = 0x01d;
144         const EXCEPTION_GETTER_IS_MISSING            = 0x01e;
145         const EXCEPTION_ARRAY_EXPECTED               = 0x01f;
146         const EXCEPTION_ARRAY_HAS_INVALID_COUNT      = 0x020;
147         const EXCEPTION_ID_IS_INVALID_FORMAT         = 0x021;
148         const EXCEPTION_MD5_CHECKSUMS_MISMATCH       = 0x022;
149         const EXCEPTION_UNEXPECTED_STRING_SIZE       = 0x023;
150         const EXCEPTION_SIMULATOR_ID_INVALID         = 0x024;
151         const EXCEPTION_MISMATCHING_COMPRESSORS      = 0x025;
152         const EXCEPTION_CONTAINER_ITEM_IS_NULL       = 0x026;
153         const EXCEPTION_ITEM_IS_NO_ARRAY             = 0x027;
154         const EXCEPTION_CONTAINER_MAYBE_DAMAGED      = 0x028;
155         const EXCEPTION_INVALID_STRING               = 0x029;
156         const EXCEPTION_VARIABLE_NOT_SET             = 0x02a;
157         const EXCEPTION_ATTRIBUTES_ARE_MISSING       = 0x02b;
158         const EXCEPTION_ARRAY_ELEMENTS_MISSING       = 0x02c;
159         const EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED  = 0x02d;
160         const EXCEPTION_MISSING_LANGUAGE_HANDLER     = 0x02e;
161         const EXCEPTION_MISSING_FILE_IO_HANDLER      = 0x02f;
162         const EXCEPTION_MISSING_ELEMENT              = 0x030;
163         const EXCEPTION_HEADERS_ALREADY_SENT         = 0x031;
164         const EXCEPTION_DEFAULT_CONTROLLER_GONE      = 0x032;
165         const EXCEPTION_CLASS_NOT_FOUND              = 0x033;
166         const EXCEPTION_REQUIRED_INTERFACE_MISSING   = 0x034;
167         const EXCEPTION_FATAL_ERROR                  = 0x035;
168         const EXCEPTION_FILE_NOT_FOUND               = 0x036;
169         const EXCEPTION_ASSERTION_FAILED             = 0x037;
170         const EXCEPTION_FILE_CANNOT_BE_READ          = 0x038;
171         const EXCEPTION_DATABASE_UPDATED_NOT_ALLOWED = 0x039;
172         const EXCEPTION_FILTER_CHAIN_INTERCEPTED     = 0x040;
173
174         /**
175          * Protected super constructor
176          *
177          * @param       $className      Name of the class
178          * @return      void
179          */
180         protected function __construct ($className) {
181                 // Set real class
182                 $this->setRealClass($className);
183
184                 // Set configuration instance if no registry
185                 if (!$this instanceof Register) {
186                         // Because registries doesn't need to be configured
187                         $this->setConfigInstance(FrameworkConfiguration::getInstance());
188                 } // END - if
189         }
190
191         /**
192          * Destructor reached...
193          *
194          * @return      void
195          * @todo        This is old code. Do we still need this old lost code?
196          */
197         public function __destruct() {
198                 // Flush any updated entries to the database
199                 $this->flushPendingUpdates();
200
201                 // Is this object already destroyed?
202                 if ($this->__toString() != 'DestructedObject') {
203                         // Destroy all informations about this class but keep some text about it alive
204                         $this->setRealClass('DestructedObject');
205                 } elseif ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
206                         // Already destructed object
207                         $this->debugOutput(sprintf("[%s:] The object <span class=\"object_name\">%s</span> is already destroyed.",
208                                 __CLASS__,
209                                 $this->__toString()
210                         ));
211                 }
212         }
213
214         /**
215          * The call method where all non-implemented methods end up
216          *
217          * @return      void
218          */
219         public final function __call ($methodName, $args) {
220                 // Implode all given arguments
221                 $argsString = '';
222                 if (empty($args)) {
223                         // No arguments
224                         $argsString = 'NULL';
225                 } elseif (is_array($args)) {
226                         // Some arguments are there
227                         foreach ($args as $arg) {
228                                 // Add the type
229                                 $argsString .= $arg . ' (' . gettype($arg);
230
231                                 // Add length if type is string
232                                 if (gettype($arg) == 'string') $argsString .= ', '.strlen($arg);
233
234                                 // Closing bracket
235                                 $argsString .= '), ';
236                         } // END - foreach
237
238                         // Remove last comma
239                         if (substr($argsString, -2, 1) == ',') {
240                                 $argsString = substr($argsString, 0, -2);
241                         } // END - if
242                 } else {
243                         // Invalid arguments!
244                         $argsString = '!INVALID:' . gettype($args) . '!';
245                 }
246
247                 // Output stub message
248                 $this->debugOutput(sprintf("[%s-&gt;%s] Stub! Args: %s",
249                         $this->__toString(),
250                         $methodName,
251                         $argsString
252                 ));
253
254                 // Return nothing
255                 return null;
256         }
257
258         /**
259          * Setter for database result instance
260          *
261          * @param       $resultInstance         An instance of a database result class
262          * @return      void
263          * @todo        SearchableResult and UpdateableResult shall have a super interface to use here
264          */
265         protected final function setResultInstance (SearchableResult $resultInstance) {
266                 $this->resultInstance =  $resultInstance;
267         }
268
269         /**
270          * Getter for database result instance
271          *
272          * @return      $resultInstance         An instance of a database result class
273          */
274         public final function getResultInstance () {
275                 return $this->resultInstance;
276         }
277
278         /**
279          * Setter for template engine instances
280          *
281          * @param       $templateInstance       An instance of a template engine class
282          * @return      void
283          */
284         protected final function setTemplateInstance (CompileableTemplate $templateInstance) {
285                 $this->templateInstance = $templateInstance;
286         }
287
288         /**
289          * Getter for template engine instances
290          *
291          * @return      $templateInstance       An instance of a template engine class
292          */
293         protected final function getTemplateInstance () {
294                 return $this->templateInstance;
295         }
296
297         /**
298          * Setter for search instance
299          *
300          * @param       $searchInstance         Searchable criteria instance
301          * @return      void
302          */
303         public final function setSearchInstance (LocalSearchCriteria $searchInstance) {
304                 $this->searchInstance = $searchInstance;
305         }
306
307         /**
308          * Getter for search instance
309          *
310          * @return      $searchInstance         Searchable criteria instance
311          */
312         public final function getSearchInstance () {
313                 return $this->searchInstance;
314         }
315
316         /**
317          * Setter for update instance
318          *
319          * @param       $updateInstance         Searchable criteria instance
320          * @return      void
321          */
322         public final function setUpdateInstance (LocalUpdateCriteria $updateInstance) {
323                 $this->updateInstance = $updateInstance;
324         }
325
326         /**
327          * Getter for update instance
328          *
329          * @return      $updateInstance         Updateable criteria instance
330          */
331         public final function getUpdateInstance () {
332                 return $this->updateInstance;
333         }
334
335         /**
336          * Setter for resolver instance
337          *
338          * @param       $resolverInstance               Instance of a command resolver class
339          * @return      void
340          */
341         public final function setResolverInstance (Resolver $resolverInstance) {
342                 $this->resolverInstance = $resolverInstance;
343         }
344
345         /**
346          * Getter for resolver instance
347          *
348          * @return      $resolverInstance               Instance of a command resolver class
349          */
350         public final function getResolverInstance () {
351                 return $this->resolverInstance;
352         }
353
354         /**
355          * Setter for language instance
356          *
357          * @param       $configInstance         The configuration instance which shall
358          *                                                              be FrameworkConfiguration
359          * @return      void
360          */
361         public final function setConfigInstance (FrameworkConfiguration $configInstance) {
362                 Registry::getRegistry()->addInstance('config', $configInstance);
363         }
364
365         /**
366          * Getter for configuration instance
367          *
368          * @return      $configInstance         Configuration instance
369          */
370         public final function getConfigInstance () {
371                 $configInstance = Registry::getRegistry()->getInstance('config');
372                 return $configInstance;
373         }
374
375         /**
376          * Setter for debug instance
377          *
378          * @param       $debugInstance  The instance for debug output class
379          * @return      void
380          */
381         public final function setDebugInstance (DebugMiddleware $debugInstance) {
382                 Registry::getRegistry()->addInstance('debug', $debugInstance);
383         }
384
385         /**
386          * Getter for debug instance
387          *
388          * @return      $debugInstance  Instance to class DebugConsoleOutput or DebugWebOutput
389          */
390         public final function getDebugInstance () {
391                 // Get debug instance
392                 $debugInstance = Registry::getRegistry()->getInstance('debug');
393
394                 // Return it
395                 return $debugInstance;
396         }
397
398         /**
399          * Setter for web output instance
400          *
401          * @param               $webInstance    The instance for web output class
402          * @return      void
403          */
404         public final function setWebOutputInstance (OutputStreamer $webInstance) {
405                 Registry::getRegistry()->addInstance('web_output', $webInstance);
406         }
407
408         /**
409          * Getter for web output instance
410          *
411          * @return      $webOutputInstance - Instance to class WebOutput
412          */
413         public final function getWebOutputInstance () {
414                 $webOutputInstance = Registry::getRegistry()->getInstance('web_output');
415                 return $webOutputInstance;
416         }
417
418         /**
419          * Setter for database instance
420          *
421          * @param               $dbInstance     The instance for the database connection
422          *                                      (forced DatabaseConnection)
423          * @return      void
424          */
425         public final function setDatabaseInstance (DatabaseConnection $dbInstance) {
426                 Registry::getRegistry()->addInstance('db_instance', $dbInstance);
427         }
428
429         /**
430          * Getter for database layer
431          *
432          * @return      $dbInstance     The database layer instance
433          */
434         public final function getDatabaseInstance () {
435                 // Get instance
436                 $dbInstance = Registry::getRegistry()->getInstance('db_instance');
437
438                 // Return instance
439                 return $dbInstance;
440         }
441
442         /**
443          * Setter for compressor channel
444          *
445          * @param               $compressorInstance             An instance of CompressorChannel
446          * @return      void
447          */
448         public final function setCompressorChannel (CompressorChannel $compressorInstance) {
449                 Registry::getRegistry()->addInstance('compressor', $compressorInstance);
450         }
451
452         /**
453          * Getter for compressor channel
454          *
455          * @return      $compressorInstance             The compressor channel
456          */
457         public final function getCompressorChannel () {
458                 $compressorInstance = Registry::getRegistry()->getInstance('compressor');
459                 return $compressorInstance;
460         }
461
462         /**
463          * Protected getter for a manageable application helper class
464          *
465          * @return      $applicationInstance    An instance of a manageable application helper class
466          */
467         protected final function getApplicationInstance () {
468                 $applicationInstance = Registry::getRegistry()->getInstance('application');
469                 return $applicationInstance;
470         }
471
472         /**
473          * Setter for a manageable application helper class
474          *
475          * @param       $applicationInstance    An instance of a manageable application helper class
476          * @return      void
477          */
478         public final function setApplicationInstance (ManageableApplication $applicationInstance) {
479                 Registry::getRegistry()->addInstance('application', $applicationInstance);
480         }
481
482         /**
483          * Setter for request instance
484          *
485          * @param       $requestInstance        An instance of a Requestable class
486          * @return      void
487          */
488         public final function setRequestInstance (Requestable $requestInstance) {
489                 $this->requestInstance = $requestInstance;
490         }
491
492         /**
493          * Getter for request instance
494          *
495          * @return      $requestInstance        An instance of a Requestable class
496          */
497         public final function getRequestInstance () {
498                 return $this->requestInstance;
499         }
500
501         /**
502          * Setter for response instance
503          *
504          * @param       $responseInstance       An instance of a Responseable class
505          * @return      void
506          */
507         public final function setResponseInstance (Responseable $responseInstance) {
508                 $this->responseInstance = $responseInstance;
509         }
510
511         /**
512          * Getter for response instance
513          *
514          * @return      $responseInstance       An instance of a Responseable class
515          */
516         public final function getResponseInstance () {
517                 return $this->responseInstance;
518         }
519
520         /**
521          * Getter for $realClass
522          *
523          * @return      $realClass The name of the real class (not BaseFrameworkSystem)
524          */
525         public final function __toString () {
526                 return $this->realClass;
527         }
528
529         /**
530          * Setter for the real class name
531          *
532          * @param               $realClass      Class name (string)
533          * @return      void
534          */
535         public final function setRealClass ($realClass) {
536                 // Cast to string
537                 $realClass = (string) $realClass;
538
539                 // Set real class
540                 $this->realClass = $realClass;
541         }
542
543         /**
544          * Checks wether an object equals this object. You should overwrite this
545          * method to implement own equality checks
546          *
547          * @param       $objectInstance         An instance of a FrameworkInterface object
548          * @return      $equals                         Wether both objects equals
549          */
550         public function equals (FrameworkInterface $objectInstance) {
551                 // Now test it
552                 $equals = ((
553                         $this->__toString() == $objectInstance->__toString()
554                 ) && (
555                         $this->hashCode() == $objectInstance->hashCode()
556                 ));
557
558                 // Return the result
559                 return $result;
560         }
561
562         /**
563          * Formats computer generated price values into human-understandable formats
564          * with thousand and decimal seperators.
565          *
566          * @param       $value          The in computer format value for a price
567          * @param       $currency       The currency symbol (use HTML-valid characters!)
568          * @param       $decNum         Number of decimals after commata
569          * @return      $price          The for the current language formated price string
570          * @throws      MissingDecimalsThousandsSeperatorException      If decimals or
571          *                                                                                              thousands seperator
572          *                                                                                              is missing
573          */
574         public function formatCurrency ($value, $currency = '&euro;', $decNum = 2) {
575                 // Are all required attriutes set?
576                 if ((!isset($this->decimals)) || (!isset($this->thousands))) {
577                         // Throw an exception
578                         throw new MissingDecimalsThousandsSeperatorException($this, self::EXCEPTION_ATTRIBUTES_ARE_MISSING);
579                 }
580
581                 // Cast the number
582                 $value = (float) $value;
583
584                 // Reformat the US number
585                 $price = number_format($value, $decNum, $this->decimals, $this->thousands) . $currency;
586
587                 // Return as string...
588                 return $price;
589         }
590
591         /**
592          * Private getter for language instance
593          *
594          * @return      $langInstance   An instance to the language sub-system
595          */
596         protected final function getLanguageInstance () {
597                 $langInstance = Registry::getRegistry()->getInstance('language');
598                 return $langInstance;
599         }
600
601         /**
602          * Setter for language instance
603          *
604          * @param       $langInstance   An instance to the language sub-system
605          * @return      void
606          * @see         LanguageSystem
607          */
608         public final function setLanguageInstance (ManageableLanguage $langInstance) {
609                 Registry::getRegistry()->addInstance('language', $langInstance);
610         }
611
612         /**
613          * Appends a trailing slash to a string
614          *
615          * @param       $str            A string (maybe) without trailing slash
616          * @return      $str            A string with an auto-appended trailing slash
617          */
618         public final function addMissingTrailingSlash ($str) {
619                 // Is there a trailing slash?
620                 if (substr($str, -1, 1) != '/') $str .= '/';
621                 return $str;
622         }
623
624         /**
625          * Private getter for file IO instance
626          *
627          * @return      $fileIoInstance An instance to the file I/O sub-system
628          */
629         protected final function getFileIoInstance () {
630                 return $this->fileIoInstance;
631         }
632
633         /**
634          * Setter for file I/O instance
635          *
636          * @param       $fileIoInstance An instance to the file I/O sub-system
637          * @return      void
638          */
639         public final function setFileIoInstance (FileIoHandler $fileIoInstance) {
640                 $this->fileIoInstance = $fileIoInstance;
641         }
642
643         /**
644          * Prepare the template engine (WebTemplateEngine by default) for a given
645          * application helper instance (ApplicationHelper by default).
646          *
647          * @param               $appInstance                    An application helper instance or
648          *                                                                              null if we shall use the default
649          * @return              $templateInstance                               The template engine instance
650          * @throws              NullPointerException    If the template engine could not
651          *                                                                              be initialized
652          * @throws              UnsupportedTemplateEngineException      If $templateInstance is an
653          *                                                                              unsupported template engine
654          * @throws              MissingLanguageHandlerException If the language sub-system
655          *                                                                              is not yet initialized
656          * @throws              NullPointerException    If the discovered application
657          *                                                                              instance is still null
658          */
659         protected function prepareTemplateInstance (FrameworkInterface $appInstance=null) {
660                 // Is the application instance set?
661                 if (is_null($appInstance)) {
662                         // Get the current instance
663                         $appInstance = $this->getApplicationInstance();
664
665                         // Still null?
666                         if (is_null($appInstance)) {
667                                 // Thrown an exception
668                                 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
669                         } // END - if
670                 } // END - if
671
672                 // Are both instances set?
673                 if ($appInstance->getLanguageInstance() === null) {
674                         // Invalid language instance
675                         throw new MissingLanguageHandlerException($appInstance, self::EXCEPTION_MISSING_LANGUAGE_HANDLER);
676                 } elseif ($appInstance->getFileIoInstance() === null) {
677                         // Invalid language instance
678                         throw new MissingFileIoHandlerException($appInstance, self::EXCEPTION_MISSING_FILE_IO_HANDLER);
679                 }
680
681                 // Initialize the template engine
682                 $templateInstance = ObjectFactory::createObjectByConfiguredName('template_class', array($appInstance));
683
684                 // Return the prepared instance
685                 return $templateInstance;
686         }
687
688         /**
689          * Debugs this instance by putting out it's full content
690          *
691          * @param       $message        Optional message to show in debug output
692          * @return      void
693          */
694         public final function debugInstance ($message = '') {
695                 // Restore the error handler to avoid trouble with missing array elements or undeclared variables
696                 restore_error_handler();
697
698                 // Init content
699                 $content = '';
700
701                 // Is a message set?
702                 if (!empty($message)) {
703                         // Construct message
704                         $content = sprintf("<div class=\"debug_message\">Message: %s</div>\n", $message);
705                 } // END - if
706
707                 // Generate the output
708                 $content .= sprintf("<pre>%s</pre>",
709                         trim(
710                                 htmlentities(
711                                         print_r($this, true)
712                                 )
713                         )
714                 );
715
716                 // Output it
717                 ApplicationEntryPoint::app_die(sprintf("<div class=\"debug_header\">%s debug output:</div><div class=\"debug_content\">%s</div>\nLoaded includes: <div class=\"debug_include_list\">%s</div>",
718                         $this->__toString(),
719                         $content,
720                         ClassLoader::getInstance()->getPrintableIncludeList()
721                 ));
722         }
723
724         /**
725          * Output a partial stub message for the caller method
726          *
727          * @param       $message        An optional message to display
728          * @return      void
729          */
730         protected function partialStub ($message = '') {
731                 // Get the backtrace
732                 $backtrace = debug_backtrace();
733
734                 // Generate the class::method string
735                 $methodName = 'UnknownClass-&gt;unknownMethod';
736                 if ((isset($backtrace[1]['class'])) && (isset($backtrace[1]['function']))) {
737                         $methodName = $backtrace[1]['class']."-&gt;".$backtrace[1]['function'];
738                 } // END - if
739
740                 // Construct the full message
741                 $stubMessage = sprintf("[%s:] Partial stub!",
742                         $methodName
743                 );
744
745                 // Is the extra message given?
746                 if (!empty($message)) {
747                         // Then add it as well
748                         $stubMessage .= sprintf(" Message: <span id=\"stub_message\">%s</span>", $message);
749                 } // END - if
750
751                 // Debug instance is there?
752                 if (!is_null($this->getDebugInstance())) {
753                         // Output stub message
754                         $this->debugOutput($stubMessage);
755                 } else {
756                         // Trigger an error
757                         trigger_error($stubMessage."<br />\n");
758                 }
759         }
760
761         /**
762          * Outputs a debug backtrace and stops further script execution
763          *
764          * @return      void
765          */
766         public function debugBackTrace () {
767                 // Sorry, there is no other way getting this nice backtrace
768                 print("<pre>\n");
769                 debug_print_backtrace();
770                 print("</pre>");
771                 exit();
772         }
773
774         /**
775          * Outputs a debug message wether to debug instance (should be set!) or dies with or pints the message
776          *
777          * @param       $message        Message we shall send out...
778          * @param       $doPrint        Wether we shall print or die here which first is the default
779          * @return      void
780          */
781         public function debugOutput ($message, $doPrint = true) {
782                 // Get debug instance
783                 $debugInstance = $this->getDebugInstance();
784
785                 // Is the debug instance there?
786                 if (is_object($debugInstance)) {
787                         // Use debug output handler
788                         $debugInstance->output($message);
789                         if ($doPrint === false) die(); // Die here if not printed
790                 } else {
791                         // Put directly out
792                         if ($doPrint === true) {
793                                 print($message);
794                         } else {
795                                 // DO NOT REWRITE THIS TO app_die() !!!
796                                 die($message);
797                         }
798                 }
799         }
800
801         /**
802          * Converts e.g. a command from URL to a valid class by keeping out bad characters
803          *
804          * @param       $str            The string, what ever it is needs to be converted
805          * @return      $className      Generated class name
806          */
807         public function convertToClassName ($str) {
808                 // Init class name
809                 $className = '';
810
811                 // Convert all dashes in underscores
812                 $str = $this->convertDashesToUnderscores($str);
813
814                 // Now use that underscores to get classname parts for hungarian style
815                 foreach (explode('_', $str) as $strPart) {
816                         // Make the class name part lower case and first upper case
817                         $className .= ucfirst(strtolower($strPart));
818                 } // END - foreach
819
820                 // Return class name
821                 return $className;
822         }
823
824         /**
825          * Converts dashes to underscores, e.g. useable for configuration entries
826          *
827          * @param       $str    The string with maybe dashes inside
828          * @return      $str    The converted string with no dashed, but underscores
829          */
830         public final function convertDashesToUnderscores ($str) {
831                 // Convert them all
832                 $str = str_replace('-', '_', $str);
833
834                 // Return converted string
835                 return $str;
836         }
837
838         /**
839          * Marks up the code by adding e.g. line numbers
840          *
841          * @param       $phpCode                Unmarked PHP code
842          * @return      $markedCode             Marked PHP code
843          */
844         public function markupCode ($phpCode) {
845                 // Init marked code
846                 $markedCode = '';
847
848                 // Get last error
849                 $errorArray = error_get_last();
850
851                 // Init the code with error message
852                 if (is_array($errorArray)) {
853                         // Get error infos
854                         $markedCode = sprintf("<div id=\"error_header\">File: <span id=\"error_data\">%s</span>, Line: <span id=\"error_data\">%s</span>, Message: <span id=\"error_data\">%s</span>, Type: <span id=\"error_data\">%s</span></div>",
855                                 basename($errorArray['file']),
856                                 $errorArray['line'],
857                                 $errorArray['message'],
858                                 $errorArray['type']
859                         );
860                 } // END - if
861
862                 // Add line number to the code
863                 foreach (explode("\n", $phpCode) as $lineNo => $code) {
864                         // Add line numbers
865                         $markedCode .= sprintf("<span id=\"code_line\">%s</span>: %s\n",
866                                 ($lineNo + 1),
867                                 htmlentities($code, ENT_QUOTES)
868                         );
869                 } // END - foreach
870
871                 // Return the code
872                 return $markedCode;
873         }
874
875         /**
876          * Filter a given GMT timestamp (non Uni* stamp!) to make it look more
877          * beatiful for web-based front-ends. If null is given a message id
878          * null_timestamp will be resolved and returned.
879          *
880          * @param       $timestamp      Timestamp to prepare (filter) for display
881          * @return      $readable       A readable timestamp
882          */
883         public function doFilterFormatTimestamp ($timestamp) {
884                 // Default value to return
885                 $readable = '???';
886
887                 // Is the timestamp null?
888                 if (is_null($timestamp)) {
889                         // Get a message string
890                         $readable = $this->getLanguageInstance()->getMessage('null_timestamp');
891                 } else {
892                         switch ($this->getLanguageInstance()->getLanguageCode()) {
893                                 case 'de': // German format is a bit different to default
894                                         // Split the GMT stamp up
895                                         $dateTime  = explode(' ', $timestamp  );
896                                         $dateArray = explode('-', $dateTime[0]);
897                                         $timeArray = explode(':', $dateTime[1]);
898
899                                         // Construct the timestamp
900                                         $readable = sprintf($this->getConfigInstance()->getConfigEntry('german_date_time'),
901                                                 $dateArray[0],
902                                                 $dateArray[1],
903                                                 $dateArray[2],
904                                                 $timeArray[0],
905                                                 $timeArray[1],
906                                                 $timeArray[2]
907                                         );
908                                         break;
909
910                                 default: // Default is pass-through
911                                         $readable = $timestamp;
912                                         break;
913                         } // END - switch
914                 }
915
916                 // Return the stamp
917                 return $readable;
918         }
919
920         /**
921          * Filter a given number into a localized number
922          *
923          * @param       $value          The raw value from e.g. database
924          * @return      $localized      Localized value
925          */
926         public function doFilterFormatNumber ($value) {
927                 // Generate it from config and localize depencies
928                 switch ($this->getLanguageInstance()->getLanguageCode()) {
929                         case 'de': // German format is a bit different to default
930                                 $localized = number_format($value, $this->getConfigInstance()->getConfigEntry('decimals'), ',', '.');
931                                 break;
932
933                         default: // US, etc.
934                                 $localized = number_format($value, $this->getConfigInstance()->getConfigEntry('decimals'), '.', ',');
935                                 break;
936                 } // END - switch
937
938                 // Return it
939                 return $localized;
940         }
941
942         /**
943          * "Getter" for databse entry
944          *
945          * @return      $entry  An array with database entries
946          * @throws      NullPointerException    If the database result is not found
947          * @throws      InvalidDatabaseResultException  If the database result is invalid
948          */
949         protected final function getDatabaseEntry () {
950                 // Is there an instance?
951                 if (is_null($this->getResultInstance())) {
952                         // Throw an exception here
953                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
954                 } // END - if
955
956                 // Rewind it
957                 $this->getResultInstance()->rewind();
958
959                 // Do we have an entry?
960                 if ($this->getResultInstance()->valid() === false) {
961                         throw new InvalidDatabaseResultException(array($this, $this->getResultInstance()), DatabaseResult::EXCEPTION_INVALID_DATABASE_RESULT);
962                 } // END - if
963
964                 // Get next entry
965                 $this->getResultInstance()->next();
966
967                 // Fetch it
968                 $entry = $this->getResultInstance()->current();
969
970                 // And return it
971                 return $entry;
972         }
973
974         /**
975          * Getter for field name
976          *
977          * @param       $fieldName              Field name which we shall get
978          * @return      $fieldValue             Field value from the user
979          * @throws      NullPointerException    If the result instance is null
980          */
981         public final function getField ($fieldName) {
982                 // Default field value
983                 $fieldValue = null;
984
985                 // Get result instance
986                 $resultInstance = $this->getResultInstance();
987
988                 // Is this instance null?
989                 if (is_null($resultInstance)) {
990                         // Then the user instance is no longer valid (expired cookies?)
991                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
992                 } // END - if
993
994                 // Get current array
995                 $fieldArray = $resultInstance->current();
996                 //* DEBUG: */ $this->debugOutput($fieldName.':<pre>'.print_r($fieldArray, true).'</pre>');
997
998                 // Does the field exist?
999                 if (isset($fieldArray[$fieldName])) {
1000                         // Get it
1001                         $fieldValue = $fieldArray[$fieldName];
1002                 } // END - if
1003
1004                 // Return it
1005                 return $fieldValue;
1006         }
1007
1008         /**
1009          * Protected setter for user instance
1010          *
1011          * @param       $userInstance   An instance of a user class
1012          * @return      void
1013          */
1014         protected final function setUserInstance (ManageableAccount $userInstance) {
1015                 $this->userInstance = $userInstance;
1016         }
1017
1018         /**
1019          * Getter for user instance
1020          *
1021          * @return      $userInstance   An instance of a user class
1022          */
1023         public final function getUserInstance () {
1024                 return $this->userInstance;
1025         }
1026
1027         /**
1028          * Setter for controller instance (this surely breaks a bit the MVC patterm)
1029          *
1030          * @param       $controllerInstance             An instance of the controller
1031          * @return      void
1032          */
1033         public final function setControllerInstance (Controller $controllerInstance) {
1034                 $this->controllerInstance = $controllerInstance;
1035         }
1036
1037         /**
1038          * Getter for controller instance (this surely breaks a bit the MVC patterm)
1039          *
1040          * @return      $controllerInstance             An instance of the controller
1041          */
1042         public final function getControllerInstance () {
1043                 return $this->controllerInstance;
1044         }
1045
1046         /**
1047          * Flushs all pending updates to the database layer
1048          *
1049          * @return      void
1050          */
1051         public function flushPendingUpdates () {
1052                 // Get result instance
1053                 $resultInstance = $this->getResultInstance();
1054
1055                 // Do we have data to update?
1056                 if ((is_object($resultInstance)) && ($resultInstance->ifDataNeedsFlush())) {
1057                         // Get wrapper class name config entry
1058                         $configEntry = $resultInstance->getUpdateInstance()->getWrapperConfigEntry();
1059
1060                         // Create object instance
1061                         $wrapperInstance = ObjectFactory::createObjectByConfiguredName($configEntry);
1062
1063                         // Yes, then send the whole result to the database layer
1064                         $wrapperInstance->doUpdateByResult($this->getResultInstance());
1065                 } // END - if
1066         }
1067
1068         /**
1069          * Outputs a deprecation warning to the developer.
1070          *
1071          * @param       $message        The message we shall output to the developer
1072          * @return      void
1073          * @todo        Write a logging mechanism for productive mode
1074          */
1075         public function deprecationWarning ($message) {
1076                 // Is developer mode active?
1077                 if (defined('DEVELOPER')) {
1078                         // Debug instance is there?
1079                         if (!is_null($this->getDebugInstance())) {
1080                                 // Output stub message
1081                                 $this->debugOutput($message);
1082                         } else {
1083                                 // Trigger an error
1084                                 trigger_error($message."<br />\n");
1085                         }
1086                 } else {
1087                         // @TODO Finish this part!
1088                         $this->partialStub('Developer mode inactive. Message:' . $message);
1089                 }
1090         }
1091
1092         /**
1093          * Generates a generic hash code of this class. You should really overwrite
1094          * this method with your own hash code generator code. But keep KISS in mind.
1095          *
1096          * @return      $hashCode       A generic hash code respresenting this whole class
1097          */
1098         public function hashCode () {
1099                 // Simple hash code
1100                 return crc32($this->__toString());
1101         }
1102
1103         /**
1104          * Checks wether the given PHP extension is loaded
1105          *
1106          * @param       $phpExtension   The PHP extension we shall check
1107          * @return      $isLoaded       Wether the PHP extension is loaded
1108          */
1109         public final function isPhpExtensionLoaded ($phpExtension) {
1110                 // Is it loaded?
1111                 $isLoaded = in_array($phpExtension, get_loaded_extensions());
1112
1113                 // Return result
1114                 return $isLoaded;
1115         }
1116
1117         /**
1118          * Setter for RNG instance
1119          *
1120          * @param       $rngInstance    An instance of a random number generator (RNG)
1121          * @return      void
1122          */
1123         protected final function setRngInstance (RandomNumberGenerator $rngInstance) {
1124                 $this->rngInstance = $rngInstance;
1125         }
1126
1127         /**
1128          * Getter for RNG instance
1129          *
1130          * @return      $rngInstance    An instance of a random number generator (RNG)
1131          */
1132         public final function getRngInstance () {
1133                 return $this->rngInstance;
1134         }
1135
1136         /**
1137          * Setter for Iterator instance
1138          *
1139          * @param       $iteratorInstance       An instance of an Iterator
1140          * @return      void
1141          */
1142         protected final function setIteratorInstance (Iterator $iteratorInstance) {
1143                 $this->iteratorInstance = $iteratorInstance;
1144         }
1145
1146         /**
1147          * Getter for Iterator instance
1148          *
1149          * @return      $iteratorInstance       An instance of an Iterator
1150          */
1151         public final function getIteratorInstance () {
1152                 return $this->iteratorInstance;
1153         }
1154
1155         /**
1156          * "Getter" as a time() replacement but with milliseconds. You should use this
1157          * method instead of the encapsulated getimeofday() function.
1158          *
1159          * @return      $milliTime      Timestamp with milliseconds
1160          */
1161         public function getMilliTime () {
1162                 // Get the time of day as float
1163                 $milliTime = gettimeofday(true);
1164
1165                 // Return it
1166                 return $milliTime;
1167         }
1168
1169         /**
1170          * Idles (sleeps) for given milliseconds
1171          *
1172          * @return      $hasSlept       Wether it goes fine
1173          */
1174         public function idle ($milliSeconds) {
1175                 // Sleep is fine by default
1176                 $hasSlept = true;
1177
1178                 // Idle so long with found function
1179                 if (function_exists('time_sleep_until')) {
1180                         // Get current time and add idle time
1181                         $sleepUntil = $this->getMilliTime() + abs($milliSeconds) / 1000;
1182
1183                         // New PHP 5.1.0 function found
1184                         $hasSlept = time_sleep_until($sleepUntil);
1185                 } else {
1186                         // My Sun Station doesn't have that function even with latest PHP
1187                         // package. :(
1188                         usleep($milliSeconds * 1000);
1189                 }
1190
1191                 // Return result
1192                 return $hasSlept;
1193         }
1194
1195         /**
1196          * Setter for the list instance
1197          *
1198          * @param       $listInstance   A list of Listable
1199          * @return      void
1200          */
1201         protected final function setListInstance (Listable $listInstance) {
1202                 $this->listInstance = $listInstance;
1203         }
1204
1205         /**
1206          * Getter for the list instance
1207          *
1208          * @return      $listInstance   A list of Listable
1209          */
1210         protected final function getListInstance () {
1211                 return $this->listInstance;
1212         }
1213
1214         /**
1215          * Setter for the menu instance
1216          *
1217          * @param       $menuInstance   A RenderableMenu instance
1218          * @return      void
1219          */
1220         protected final function setMenuInstance (RenderableMenu $menuInstance) {
1221                 $this->menuInstance = $menuInstance;
1222         }
1223
1224         /**
1225          * Getter for the menu instance
1226          *
1227          * @return      $menuInstance   A RenderableMenu instance
1228          */
1229         protected final function getMenuInstance () {
1230                 return $this->menuInstance;
1231         }
1232 }
1233
1234 // [EOF]
1235 ?>