Registration stub added, naming convention applied, support for PHP code (keep it...
[shipsimu.git] / application / selector / class_ApplicationSelector.php
1 <?php
2 /**
3  * The application selector class.
4  *
5  * Please remember that this include file is being loaded *before* the class
6  * loader is loading classes from "exceptions", "interfaces" and "main"!
7  *
8  * @author              Roland Haeder <webmaster@ship-simu.org>
9  * @version             0.0.0
10  * @copyright   Copyright(c) 2007, 2008 Roland Haeder, this is free software
11  * @license             GNU GPL 3.0 or any newer version
12  * @link                http://www.ship-simu.org
13  *
14  * This program is free software: you can redistribute it and/or modify
15  * it under the terms of the GNU General Public License as published by
16  * the Free Software Foundation, either version 3 of the License, or
17  * (at your option) any later version.
18  *
19  * This program is distributed in the hope that it will be useful,
20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  * GNU General Public License for more details.
23  *
24  * You should have received a copy of the GNU General Public License
25  * along with this program. If not, see <http://www.gnu.org/licenses/>.
26  */
27 class ApplicationSelector extends BaseFrameworkSystem {
28         /**
29          * An ArrayObject for all found applications
30          */
31         private $foundApps = null;
32
33         /**
34          * An array object for all loaded application templates (selector_app-name.tpl)
35          */
36         private $loadedTemplates = null;
37
38         /**
39          * The application selector's own template engine handler
40          */
41         private $selectorTplEngine = null;
42
43         /**
44          * A list of items we shall ignore while reading from directories
45          */
46         private $dirIgnoreList = array(
47                 ".",
48                 "..",
49                 ".htaccess"
50         );
51
52         /**
53          * The private constructor. No direct instances can be created from this.
54          *
55          * @return      void
56          */
57         protected function __construct() {
58                 // Call parent constructor
59                 parent::__construct(__CLASS__);
60
61                 // Set description
62                 $this->setObjectDescription("Applikationswechsler");
63
64                 // Create unique ID number
65                 $this->createUniqueID();
66
67                 // Remove system array and thousand seperator
68                 $this->removeSystemArray();
69                 $this->removeNumberFormaters();
70
71                 // Initialize the array lists
72                 $this->initializeAppsList();
73                 $this->initializeTemplatesList();
74         }
75
76         /**
77          * Create a prepared instance of ApplicationSelector
78          *
79          * @param               $langInstance           The language sub-system: LanguageSystem
80          * @param               $fileIOInstance The file I/O instance
81          * @return              $selInstance            An instance of ApplicationSelector
82          */
83         public final static function createApplicationSelector (ManageableLanguage $langInstance, FileIoHandler $fileIOInstance) {
84                 // Get a new instance
85                 $selInstance = new ApplicationSelector();
86
87                 // Get all applications
88                 $selInstance->readApplicationDirectory();
89
90                 // Set language and file I/O instances
91                 $selInstance->setLanguageInstance($langInstance);
92                 $selInstance->setFileIoInstance($fileIOInstance);
93
94                 // Return the prepared instance
95                 return $selInstance;
96         }
97
98         /**
99          * Initialize the application list
100          *
101          * @return      void
102          */
103         private function initializeAppsList () {
104                 $this->foundApps = new FrameworkArrayObject();
105         }
106
107         /**
108          * Initialize the loaded templates list
109          *
110          * @return      void
111          */
112         private function initializeTemplatesList () {
113                 $this->loadedTemplates = new FrameworkArrayObject();
114         }
115
116         /**
117          * Load the init.php script of an application and append the application
118          * instance to $foundApps
119          *
120          * @param               $initScript     The FQFN of init.php
121          * @param               $appName                The application's Uni* name
122          * @return      void
123          * @throws      AppVarIsNotSetException If 'app' is not set
124          * @throws      NullPointerException    If 'app' is null
125          * @throws      NoObjectException               If 'app' is not an object
126          * @throws      MissingMethodException  If a required method is missing
127          */
128         private function loadInitScript ($initScript, $appName) {
129                 // Is it a file and readable?
130                 if ((is_file($initScript)) && (is_readable($initScript))) {
131                         // Then include it
132                         include ($initScript);
133
134                         // We now should have $app re-defined!
135                         if (!isset($app)) {
136                                 // This application shall not be loaded
137                                 return;
138                         } elseif (is_null($app)) {
139                                 // The class instance is null
140                                 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
141                         } elseif (!is_object($app)) {
142                                 // Not an object
143                                 throw new NoObjectException($app, self::EXCEPTION_IS_NO_OBJECT);
144                         } elseif (!method_exists($app, $this->getConfigInstance()->readConfig("entry_method"))) {
145                                 // Method not found!
146                                 throw new MissingMethodException(array($app, $this->getConfigInstance()->readConfig("entry_method")), self::EXCEPTION_MISSING_METHOD);
147                         }
148
149                         // Add the current instance to the list
150                         $this->foundApps->append($app);
151
152                 } // END - if ((is_file(...
153         }
154
155         /**
156          * Setter for the selector's template engine instance
157          *
158          * @param               $tplEngine      An instance of TemplateEngine
159          */
160         private final function setSelectorTemplateEngine (CompileableTemplate $tplEngine) {
161                 $this->selectorTplEngine = $tplEngine;
162         }
163
164         /**
165          * Getter for the selector's template engine instance
166          *
167          * @return      $selectTplEngine        The selector's template engine
168          */
169         private final function getSelectorTemplateEngine () {
170                 return $this->selectorTplEngine;
171         }
172
173         /**
174          * Getter for the $loadedTemplates array object
175          *
176          * @return      $loadedTemplates        An array object holding all loaded
177          *                                                      application templates
178          */
179         private final function getLoadedTemplates () {
180                 return $this->loadedTemplates;
181         }
182
183         /**
184          * Method for compatiblity with prepareTemplateEngine()
185          *
186          * @return      $shortName      This selector's short name
187          */
188         public function getAppShortName() {
189                 $shortName = $this->getConfigInstance()->readConfig("selector_path");
190                 return $shortName;
191         }
192
193         /**
194          * Add a directory/file to the ignore list
195          *
196          * @param               $ignoreItem     The file/directory we shall ignore
197          * @return      void
198          */
199         public function addDirIgnoreList ($ignoreItem) {
200                 // Cast and add it
201                 $ignoreItem = (string) $ignoreItem;
202                 $this->dirIgnoreList[] = $ignoreItem;
203         }
204
205         /**
206          * Read the base path for all applications (application/) and create a
207          * list of all found applications
208          *
209          * @return      void
210          */
211         public function readApplicationDirectory () {
212                 // Generate the base path for all applications
213                 $appBasePath = sprintf("%s%s/",
214                         PATH,
215                         $this->getConfigInstance()->readConfig("application_path")
216                 );
217
218                 // Add the selector path to the ignore list
219                 $this->addDirIgnoreList($this->getConfigInstance()->readConfig("selector_path"));
220
221                 // Get a directory pointer for the application path
222                 $dirInstance = FrameworkDirectoryPointer::createFrameworkDirectoryPointer($appBasePath);
223
224                 // Backup and remove the 'app' from global name space
225                 /*$appBackup = $app;
226                 unset($app);*/
227
228                 // Read all directories&files except some parts
229                 while ($appName = $dirInstance->readDirectoryExcept($this->dirIgnoreList)) {
230                         // Generate FQFN for the application name (or better directory name)
231                         $fqfn = sprintf("%s%s", $appBasePath, $appName);
232
233                         // Is this a readable directory? (files will be ignored silently)
234                         if ((is_dir($fqfn)) && (is_readable($fqfn))) {
235                                 // Then get the init.php script for analyzing
236                                 $initScript = sprintf("%s/init%s", $fqfn, $this->getConfigInstance()->readConfig("php_extension"));
237
238                                 // Load the application's init.php script and append the
239                                 // application to the ArrayObject
240                                 $this->loadInitScript($initScript, $appName);
241
242                         } // END - if ((is_dir(...
243
244                 } // END - while
245
246                 // Close directory pointer
247                 $dirInstance->closeDirectory();
248
249                 // Restore old 'app' from backup
250                 //$app = $appBackup;
251         }
252
253         /**
254          * Load all templates for found applications in previous scan
255          *
256          * @return      void
257          */
258         public function loadApplicationTemplates () {
259                 // Iterate through all applications
260                 for ($idx = $this->foundApps->getIterator(); $idx->valid(); $idx->next()) {
261                         // Get current application
262                         $appInstance = $idx->current();
263
264                         // Prepare the template engine for the current template
265                         $tplEngine = $this->prepareTemplateEngine($appInstance);
266
267                         // Try to load the web template
268                         $tplEngine->loadWebTemplate(sprintf("%s_%s",
269                                 $this->getConfigInstance()->readConfig("tpl_selector_prefix"),
270                                 strtolower($appInstance->getAppShortName())
271                         ));
272
273                         // Remember this template and the application for later usage
274                         $this->loadedTemplates->append(array(
275                                 'tpl_engine'   => $tplEngine,
276                                 'app_instance' => $appInstance
277                         ));
278                 }
279
280                 // Re-initialize the application list to avoid double loading
281                 $this->initializeAppsList();
282         }
283
284         /**
285          * Removes $dirIgnoreList from the object to save some memory
286          *
287          * @return      void
288          */
289         public final function removeDirIgnoreList () {
290                 unset($this->dirIgnoreList);
291         }
292
293         /**
294          * Loads the selector's own main template. This step is not linking the
295          * application's templates into the main one.
296          *
297          * @return      void
298          */
299         public function loadSelectorTemplate () {
300                 // Prepare the template engine
301                 $tplEngine = $this->prepareTemplateEngine($this);
302
303                 // Load the selector's template
304                 $tplEngine->loadCodeTemplate($this->getConfigInstance()->readConfig("selector_main_tpl"));
305
306                 // Now store it in the class
307                 $this->setSelectorTemplateEngine($tplEngine);
308         }
309
310         /**
311          * Inserts all loaded application templates into the selector's template
312          *
313          * @return      void
314          * @throws      NullPointerException            If $curr is null
315          * @throws      NoArrayException                        If $curr is not an array
316          * @throws      InvalidArrayCountException      If $curr contains an
317          *                                                                      unexpected count of elements
318          * @throws      MissingArrayElementsException   If $curr is missing expected
319          *                                                                      array elements
320          */
321         public function insertApplicationTemplates () {
322                 // First prepare the instance
323                 $tplEngine = $this->prepareTemplateEngine($this);
324
325                 // Load template which shall later hold all application templates
326                 $tplEngine->loadCodeTemplate($this->getConfigInstance()->readConfig("selector_apps_tpl"));
327
328                 // Add all loaded application templates together
329                 $dummy = "";
330                 for ($idx = $this->getLoadedTemplates()->getIterator(); $idx->valid(); $idx->next()) {
331                         // Get current item from array object
332                         $curr = $idx->current();
333
334                         // Do some sanity checks on the loaded item
335                         if (is_null($curr)) {
336                                 // $curr is null
337                                 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
338                         } elseif (!is_array($curr)) {
339                                 // Not an array
340                                 throw new NoArrayException($curr, self::EXCEPTION_IS_NO_ARRAY);
341                         } elseif (count($curr) != 2) {
342                                 // Not expected count of entries
343                                 throw new InvalidArrayCountException(array($this, "curr", count($curr), 2), self::EXCEPTION_ARRAY_HAS_INVALID_COUNT);
344                         } elseif (!isset($curr['tpl_engine']) || (!isset($curr['app_instance']))) {
345                                 // Expected entries missing
346                                 throw new MissingArrayElementsException(array($this, "curr", array('tpl_engine', 'app_instance')), self::EXCEPTION_ARRAY_ELEMENTS_MISSING);
347                         }
348                         die("<pre>".print_r($curr, true)."</pre>");
349
350                 } // END - for
351         }
352
353         /**
354          * Stub!
355          */
356         public function saveObjectToDatabase () {
357                 $this->getDebugInstance()->output(sprintf("[%s:] Stub <strong>%s</strong> erreicht.",
358                         $this->__toString(),
359                         __FUNCTION__
360                 ));
361         }
362 }
363
364 // [EOF]
365 ?>