Copyright year updated, converted double->single quotes
[core.git] / inc / loader / class_ClassLoader.php
1 <?php
2 /**
3  * This class loads class include files with a specific prefix and suffix
4  *
5  * @author              Roland Haeder <webmaster@shipsimu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2013 Core Developer Team
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.shipsimu.org
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 3 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program. If not, see <http://www.gnu.org/licenses/>.
23  *
24  * ----------------------------------
25  * 1.4
26  *  - Some comments improved, other minor improvements
27  * 1.3
28  *  - Constructor is now empty and factory method 'createClassLoader' is created
29  *  - renamed loadClasses to scanClassPath
30  *  - Added initLoader()
31  * 1.2
32  *  - ClassLoader rewritten to PHP SPL's own RecursiveIteratorIterator class
33  * 1.1
34  *  - loadClasses rewritten to fix some notices
35  * 1.0
36  *  - Initial release
37  * ----------------------------------
38  */
39 class ClassLoader {
40         /**
41          * Instance of this class
42          */
43         private static $selfInstance = NULL;
44
45         /**
46          * Array with all classes
47          */
48         private $classes = array();
49
50         /**
51          * List of loaded classes
52          */
53         private $loadedClasses = array();
54
55         /**
56          * Suffix with extension for all class files
57          */
58         private $prefix = 'class_';
59
60         /**
61          * Suffix with extension for all class files
62          */
63         private $suffix = '.php';
64
65         /**
66          * A list for directory names (no leading/trailing slashes!) which not be scanned by the path scanner
67          * @see scanLocalPath
68          */
69         private $ignoreList = array();
70
71         /**
72          * Debug this class loader? (TRUE = yes, FALSE = no)
73          */
74         private $debug = FALSE;
75
76         /**
77          * Whether the file list is cached
78          */
79         private $listCached = FALSE;
80
81         /**
82          * Wethe class content has been cached
83          */
84         private $classesCached = FALSE;
85
86         /**
87          * Filename for the list cache
88          */
89         private $listCacheFQFN = '';
90
91         /**
92          * Cache for class content
93          */
94         private $classCacheFQFN = '';
95
96         /**
97          * Counter for loaded include files
98          */
99         private $total = 0;
100
101         /**
102          * The protected constructor. Please use the factory method below, or use
103          * getSelfInstance() for singleton
104          *
105          * @return      void
106          */
107         protected function __construct () {
108                 // Is currently empty
109         }
110
111         /**
112          * The destructor makes it sure all caches got flushed
113          *
114          * @return      void
115          */
116         public function __destruct () {
117                 // Skip here if dev-mode
118                 if (defined('DEVELOPER')) {
119                         return;
120                 } // END - if
121
122                 // Skip here if already cached
123                 if ($this->listCached === FALSE) {
124                         // Writes the cache file of our list away
125                         $cacheContent = serialize($this->classes);
126                         file_put_contents($this->listCacheFQFN, $cacheContent);
127                 } // END - if
128
129                 // Skip here if already cached
130                 if ($this->classesCached === FALSE) {
131                         // Generate a full-cache of all classes
132                         $cacheContent = '';
133                         foreach ($this->loadedClasses as $fqfn) {
134                                 // Load the file
135                                 $cacheContent .= file_get_contents($fqfn);
136                         } // END - foreach
137
138                         // And write it away
139                         file_put_contents($this->classCacheFQFN, $cacheContent);
140                 } // END - if
141         }
142
143         /**
144          * Creates an instance of this class loader for given configuration instance
145          *
146          * @param       $configInstance         Configuration class instance
147          * @return      void
148          */
149         public static final function createClassLoader (FrameworkConfiguration $configInstance) {
150                 // Get a new instance
151                 $loaderInstance = new ClassLoader();
152
153                 // Init the instance
154                 $loaderInstance->initLoader($configInstance);
155
156                 // Return the prepared instance
157                 return $loaderInstance;
158         }
159
160         /**
161          * Initializes our loader class
162          *
163          * @param       $configInstance Configuration class instance
164          * @return      void
165          */
166         protected function initLoader (FrameworkConfiguration $configInstance) {
167                 // Set configuration instance
168                 $this->configInstance = $configInstance;
169
170                 // Construct the FQFN for the cache
171                 if (!defined('DEVELOPER')) {
172                         $this->listCacheFQFN  = $this->configInstance->getConfigEntry('local_db_path') . 'list-' . $this->configInstance->getConfigEntry('app_name') . '.cache';
173                         $this->classCacheFQFN = $this->configInstance->getConfigEntry('local_db_path') . 'class-' . $this->configInstance->getConfigEntry('app_name') . '.cache';
174                 } // END - if
175
176                 // Set suffix and prefix from configuration
177                 $this->suffix = $configInstance->getConfigEntry('class_suffix');
178                 $this->prefix = $configInstance->getConfigEntry('class_prefix');
179
180                 // Set own instance
181                 self::$selfInstance = $this;
182
183                 // Skip here if no dev-mode
184                 if (defined('DEVELOPER')) {
185                         return;
186                 } // END - if
187
188                 // IS the cache there?
189                 if (file_exists($this->listCacheFQFN)) {
190                         // Get content
191                         $cacheContent = file_get_contents($this->listCacheFQFN);
192
193                         // And convert it
194                         $this->classes = unserialize($cacheContent);
195
196                         // List has been restored from cache!
197                         $this->listCached = TRUE;
198                 } // END - if
199
200                 // Does the class cache exist?
201                 if (file_exists($this->classCacheFQFN)) {
202                         // Then include it
203                         require($this->classCacheFQFN);
204
205                         // Mark the class cache as loaded
206                         $this->classesCached = TRUE;
207                 } // END - if
208         }
209
210         /**
211          * Autoload-function
212          *
213          * @param       $className      Name of the class to load
214          * @return      void
215          */
216         public static function autoLoad ($className) {
217                 // Try to include this class
218                 self::getSelfInstance()->includeClass($className);
219         }
220
221         /**
222          * Singleton getter for an instance of this class
223          *
224          * @return      $selfInstance   A singleton instance of this class
225          */
226         public static final function getSelfInstance () {
227                 // Is the instance there?
228                 if (is_null(self::$selfInstance)) {
229                         // Get a new one
230                         self::$selfInstance = ClassLoader::createClassLoader(FrameworkConfiguration::getSelfInstance());
231                 } // END - if
232
233                 // Return the instance
234                 return self::$selfInstance;
235         }
236
237         /**
238          * Scans recursively a local path for class files which must have a prefix and a suffix as given by $this->suffix and $this->prefix
239          *
240          * @param       $basePath               The relative base path to 'base_path' constant for all classes
241          * @param       $ignoreList             An optional list (array forced) of directory and file names which shall be ignored
242          * @return      void
243          */
244         public function scanClassPath ($basePath, array $ignoreList = array() ) {
245                 // Is a list has been restored from cache, don't read it again
246                 if ($this->listCached === TRUE) {
247                         // Abort here
248                         return;
249                 } // END - if
250
251                 /*
252                  * Directories which this class loader ignores by default while
253                  * scanning the whole directory structure starting from given base
254                  * path.
255                  */
256                 array_push($ignoreList, '.');
257                 array_push($ignoreList, '..');
258                 array_push($ignoreList, '.htaccess');
259                 array_push($ignoreList, '.svn');
260
261                 // Keep it in class for later usage
262                 $this->ignoreList = $ignoreList;
263
264                 /*
265                  * Set base directory which holds all our classes, we should use an
266                  * absolute path here so is_dir(), is_file() and so on will always
267                  * find the correct files and dirs.
268                  */
269                 $basePath2 = realpath($basePath);
270
271                 // If the basePath is FALSE it is invalid
272                 if ($basePath2 === FALSE) {
273                         /* @todo: Do not die here. */
274                         exit(__METHOD__ . ':Cannot read ' . $basePath . ' !');
275                 } else {
276                         // Set base path
277                         $basePath = $basePath2;
278                 }
279
280                 // Get a new iterator
281                 //* DEBUG: */ echo "<strong>Base path: {$basePath}</strong><br />\n";
282                 $iterator = new RecursiveDirectoryIterator($basePath);
283                 $recursive = new RecursiveIteratorIterator($iterator);
284                 foreach ($recursive as $entry) {
285                         // Get filename from iterator
286                         $fileName = $entry->getFileName();
287
288                         // Get the FQFN and add it to our class list
289                         $fqfn = $entry->getRealPath();
290
291                         // Is this file wanted?
292                         //* DEBUG: */ echo "FOUND:{$fileName}<br />\n";
293                         if ((!in_array($fileName, $this->ignoreList)) && (filesize($fqfn) > 100) && (substr($fileName, 0, strlen($this->prefix)) == $this->prefix) && (substr($fileName, -strlen($this->suffix), strlen($this->suffix)) == $this->suffix)) {
294                                 //* DEBUG: */ echo "ADD: {$fileName}<br />\n";
295                                 // Add it to the list
296                                 $this->classes[$fileName] = $fqfn;
297                         } // END - if
298                 } // END - foreach
299         }
300
301         /**
302          * Load extra config files
303          *
304          * @return      void
305          */
306         public function loadExtraConfigs () {
307                 // Backup old prefix
308                 $oldPrefix = $this->prefix;
309
310                 // Set new prefix (temporary!)
311                 $this->prefix = 'config-';
312
313                 // Set base directory
314                 $basePath = $this->configInstance->getConfigEntry('base_path') . 'inc/config/';
315
316                 // Load all classes from the config directory
317                 $this->scanClassPath($basePath);
318
319                 // Include these extra configs now
320                 $this->includeExtraConfigs();
321
322                 // Set back the old prefix
323                 $this->prefix = $oldPrefix;
324         }
325
326         /**
327          * Tries to find the given class in our list. This method ignores silently
328          * missing classes or interfaces. So if you use class_exists() this method
329          * does not interrupt your program.
330          *
331          * @param       $className      The class we shall load
332          * @return      void
333          */
334         public function includeClass ($className) {
335                 // Create a name with prefix and suffix
336                 $fileName = $this->prefix . $className . $this->suffix;
337
338                 // Now look it up in our index
339                 if ((isset($this->classes[$fileName])) && (!in_array($this->classes[$fileName], $this->loadedClasses))) {
340                         // File is found and not loaded so load it only once
341                         //* DEBUG: */ echo "LOAD: ".$fileName." - Start<br />\n";
342                         require($this->classes[$fileName]);
343                         //* DEBUG: */ echo "LOAD: ".$fileName." - End<br />\n";
344
345                         // Count this include
346                         $this->total++;
347
348                         // Mark this class as loaded
349                         array_push($this->loadedClasses, $this->classes[$fileName]);
350
351                         // Remove it from classes list
352                         unset($this->classes[$fileName]);
353
354                         // Developer mode excludes caching (better debugging)
355                         if (!defined('DEVELOPER')) {
356                                 // Reset cache
357                                 $this->classesCached = FALSE;
358                         } // END - if
359                 } // END - if
360         }
361
362         /**
363          * Includes all extra config files
364          *
365          * @return      void
366          */
367         private function includeExtraConfigs () {
368                 // Run through all class names (should not be much)
369                 foreach ($this->classes as $fileName => $fqfn) {
370                         // Is this a config?
371                         if (substr($fileName, 0, strlen($this->prefix)) == $this->prefix) {
372                                 // Then include it
373                                 require($fqfn);
374
375                                 // Remove it from the list
376                                 unset($this->classes[$fileName]);
377                         } // END - if
378                 } // END - foreach
379         }
380
381         /**
382          * Getter for total include counter
383          *
384          * @return      $total  Total loaded include files
385          */
386         public final function getTotal () {
387                 return $this->total;
388         }
389
390         /**
391          * Getter for a printable list of included classes/interfaces/exceptions
392          *
393          * @param       $includeList    A printable include list
394          */
395         public function getPrintableIncludeList () {
396                 // Prepare the list
397                 $includeList = '';
398                 foreach ($this->loadedClasses as $classFile) {
399                         $includeList .= basename($classFile) . '<br />' . PHP_EOL;
400                 } // END - foreach
401
402                 // And return it
403                 return $includeList;
404         }
405 }
406
407 // [EOF]
408 ?>