From fd84b1494dade3a8930c315a1d1c4320f7697d53 Mon Sep 17 00:00:00 2001 From: Jose Lorenzo Rodriguez Date: Sat, 12 Mar 2011 01:15:56 -0430 Subject: [PATCH] Documenting remaining methods in App class --- lib/Cake/Core/App.php | 62 +++++++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/lib/Cake/Core/App.php b/lib/Cake/Core/App.php index 3db3db5db..4d651abe2 100644 --- a/lib/Cake/Core/App.php +++ b/lib/Cake/Core/App.php @@ -27,17 +27,17 @@ * This allows you to split your application up across the filesystem. * * ### Packages - * + * * CakePHP is organized around the idea of packages, each class belongs to a package or folder where other * classes reside. You can configure each package location in your application using `App::build('APackage/SubPackage', $paths)` * to inform the framework where should each class be loaded. Almost every class in the CakePHP framework can be swapped * by your own compatible implementation. If you wish to use you own class instead of the classes the framework provides, * just add the class to your libs folder mocking the directory location of where CakePHP expects to find it. - * + * * For instance if you'd like to use your own HttpSocket class, put it under - * + * * app/libs/Network/Http/HttpSocket.php - * + * * ### Inspecting loaded paths * * You can inspect the currently loaded paths using `App::path('Controller')` for example to see loaded @@ -45,7 +45,7 @@ * * It is also possible to inspect paths for plugin classes, for instance, to see a plugin's helpers you would call * `App::path('View/Helper', 'MyPlugin')` - * + * * ### Locating plugins and themes * * Plugins and Themes can be located with App as well. Using App::pluginPath('DebugKit') for example, will @@ -183,7 +183,7 @@ class App { * Usage: * * `App::path('Model'); will return all paths for models` - * + * * `App::path('Model/Datasource', 'MyPlugin'); will return the path for datasources under the 'MyPlugin' plugin` * * @param string $type type of path @@ -217,15 +217,15 @@ class App { * Sets up each package location on the file system. You can configure multiple search paths * for each package, those will be used to look for files one folder at a time in the specified order * All paths should be terminated with a Directory separator - * + * * Usage: - * + * * `App::build(array(Model' => array('/a/full/path/to/models/'))); will setup a new search path for the Model package` - * + * * `App::build(array('Model' => array('/path/to/models/')), true); will setup the path as the only valid path for searching models` * * `App::build(array('View/Helper' => array('/path/to/models/', '/another/path/))); will setup multiple search paths for helpers` - * + * * @param array $paths associative array with package names as keys and a list of directories for new search paths * @param boolean $reset true will set paths, false merges paths [default] false * @return void @@ -311,9 +311,9 @@ class App { /** * Gets the path that a plugin is on. Searches through the defined plugin paths. - * + * * Usage: - * + * * `App::pluginPath('MyPlugin'); will return the full path to 'MyPlugin' plugin'` * * @param string $plugin CamelCased/lower_cased plugin name to find the path of. @@ -333,9 +333,9 @@ class App { * Finds the path that a theme is on. Searches through the defined theme paths. * * Usage: - * + * * `App::themePath('MyTheme'); will return the full path to the 'MyTheme' theme` - * + * * @param string $theme lower_cased theme name to find the path of. * @return string full path to the theme. */ @@ -351,9 +351,9 @@ class App { /** * Returns the full path to a package inside the CakePHP core - * + * * Usage: - * + * * `App::core('Cache/Engine'); will return the full path to the cache engines package` * * @param string $type @@ -372,14 +372,15 @@ class App { * * `App::objects('plugin');` returns `array('DebugKit', 'Blog', 'User');` * + * `App::objects('Controller');` returns `array('PagesController', 'BlogController');` + * * You can also search only within a plugin's objects by using the plugin dot * syntax. * * `App::objects('MyPlugin.Model');` returns `array('MyPluginPost', 'MyPluginComment');` * - * @param string $type Type of object, i.e. 'model', 'controller', 'helper', or 'plugin' - * @param mixed $path Optional Scan only the path given. If null, paths for the chosen - * type will be used. + * @param string $type Type of object, i.e. 'Model', 'Controller', 'View/Helper', 'file', 'class' or 'plugin' + * @param mixed $path Optional Scan only the path given. If null, paths for the chosen type will be used. * @param boolean $cache Set to false to rescan objects of the chosen type. Defaults to true. * @return mixed Either false on incorrect / miss. Or an array of found objects. */ @@ -475,10 +476,31 @@ class App { self::$__objects[$cacheLocation][$type] = $values; } +/** + * Declares a package for a class. This package location will be used + * by the automatic class loader if the class is tried to be used + * + * Usage: + * + * `App::use('MyCustomController', 'Controller');` will setup the class to be found under Controller package + * + * `App::use('MyHelper', 'MyPlugin.View/Helper');` will setup the helper class to be found in plugin's helper package + * + * @param string $className the name of the class to configure package for + * @param string $location the package name + */ public static function uses($className, $location) { self::$__classMap[$className] = $location; } +/** + * Method to handle the automatic class loading. It will look for each class' package + * defined using App::uses() and with this information it will resolve the package name to a full path + * to load the class from. File name for each class should follow the class name. For instance, + * if a class is name `MyCustomClass` the file name should be `MyCustomClass.php` + * + * @param string $className the name of the class to load + */ public static function load($className) { if (isset(self::$__classMap[$className])) { if ($file = self::__mapped($className)) { @@ -693,7 +715,7 @@ class App { foreach ($paths as $path) { if (file_exists($path . $file)) { self::__map($path . $file, $name, $plugin); - return (bool) include($path . $file); + return (bool) include($path . $file); } } }