Class App
App is responsible for path management, class location and class loading.
Adding paths
You can add paths to the search indexes App uses to find classes using App::build()
. Adding
additional controller paths for example would alter where CakePHP looks for controllers.
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 your 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/Network/Http/HttpSocket.php
Inspecting loaded paths
You can inspect the currently loaded paths using App::path('Controller')
for example to see loaded
controller paths.
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
give you the full path to the DebugKit plugin. App::themePath('purple'), would give the full path to the
purple
theme.
Inspecting known objects
You can find out which objects App knows about using App::objects('Controller') for example to find which application controllers App knows about.
Link: http://book.cakephp.org/2.0/en/core-utility-libraries/app.html
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/Core/App.php
Constants summary
Properties summary
-
$_cacheChange
protected staticboolean
Indicates whether the class cache should be stored again because of an addition to it -
$_classMap
protected staticarray
Holds the location of each class -
$_map
protected staticarray
Holds key/value pairs of $type => file path. -
$_objectCacheChange
protected staticboolean
Indicates whether the object cache should be stored again because of an addition to it -
$_objects
protected staticarray
Holds and key => value array of object types. -
$_packageFormat
protected staticarray
Holds the templates for each customizable package path in the application -
$_packages
protected staticarray
Holds the possible paths for each package name -
$bootstrapping
public staticboolean
Indicates the the Application is in the bootstrapping process. Used to better cache loaded classes while the cache libraries have not been yet initialized
-
$legacy
public staticarray
Maps an old style CakePHP class type to the corresponding package -
$return
public staticboolean
Whether or not to return the file that is loaded. -
$search
public staticarray
Paths to search for files. -
$types
public staticarray
List of object types and their properties
Method Summary
-
_checkFatalError() protected static
Check if a fatal error happened and trigger the configured handler if configured -
_loadClass() protected static
Helper function to include classes This is a compatibility wrapper around using App::uses() and automatic class loading
-
_loadFile() protected static
Helper function to include single files -
_loadVendor() protected static
Helper function to load files from vendors folders -
_map() protected static
Maps the $name to the $file. -
_mapped() protected static
Returns a file's complete path. -
_packageFormat() protected static
Sets then returns the templates for each customizable package path -
build() public static
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
-
core() public static
Returns the full path to a package inside the CakePHP core -
import() public static
Finds classes based on $name or specific file(s) to search. Calling App::import() will not construct any classes contained in the files. It will only find and require() the file.
-
init() public static
Initializes the cache for App, registers a shutdown function. -
load() public static
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 beMyCustomClass.php
-
location() public static
Returns the package name where a class was defined to be located at -
objects() public static
Returns an array of objects of the given type. -
path() public static
Used to read information stored path -
paths() public static
Get all the currently loaded paths from App. Useful for inspecting or storing all paths App knows about. For a paths to a specific package use App::path()
-
pluginPath() public static deprecated
Gets the path that a plugin is on. Searches through the defined plugin paths. -
shutdown() public static
Object destructor. -
themePath() public static
Finds the path that a theme is on. Searches through the defined theme paths. -
uses() public static
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
Method Detail
_checkFatalError() protected static ¶
_checkFatalError( )
Check if a fatal error happened and trigger the configured handler if configured
_loadClass() protected static ¶
_loadClass( string $name , string $plugin , string $type , string $originalType , boolean $parent )
Helper function to include classes This is a compatibility wrapper around using App::uses() and automatic class loading
Parameters
- string $name
- unique name of the file for identifying it inside the application
- string $plugin
- camel cased plugin name if any
- string $type
- name of the packed where the class is located
- string $originalType
- type name as supplied initially by the user
- boolean $parent
- whether to load the class parent or not
Returns
true indicating the successful load and existence of the class
_loadFile() protected static ¶
_loadFile( string $name , string $plugin , array $search , string $file , boolean $return )
Helper function to include single files
Parameters
- string $name
- unique name of the file for identifying it inside the application
- string $plugin
- camel cased plugin name if any
- array $search
- list of paths to search the file into
- string $file
- filename if known, the $name param will be used otherwise
- boolean $return
- whether this function should return the contents of the file after being parsed by php or just a success notice
Returns
if $return contents of the file after php parses it, boolean indicating success otherwise
_loadVendor() protected static ¶
_loadVendor( string $name , string $plugin , string $file , string $ext )
Helper function to load files from vendors folders
Parameters
- string $name
- unique name of the file for identifying it inside the application
- string $plugin
- camel cased plugin name if any
- string $file
- file name if known
- string $ext
- file extension if known
Returns
true if the file was loaded successfully, false otherwise
_map() protected static ¶
_map( string $file , string $name , string $plugin = null )
Maps the $name to the $file.
Parameters
- string $file
- full path to file
- string $name
- unique name for this map
- string $plugin optional null
- camelized if object is from a plugin, the name of the plugin
_mapped() protected static ¶
_mapped( string $name , string $plugin = null )
Returns a file's complete path.
Parameters
- string $name
- unique name
- string $plugin optional null
- camelized if object is from a plugin, the name of the plugin
Returns
file path if found, false otherwise
_packageFormat() protected static ¶
_packageFormat( )
Sets then returns the templates for each customizable package path
Returns
templates for each customizable package path
build() public static ¶
build( array $paths = array() , boolean|string $mode = App::PREPEND )
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/')), App::RESET); will setup the path as the only valid path for searching models
App::build(array('View/Helper' => array('/path/to/helpers/', '/another/path/'))); will setup multiple search paths for helpers
App::build(array('Service' => array('%s' . 'Service' . DS)), App::REGISTER); will register new package 'Service'
If reset is set to true, all loaded plugins will be forgotten and they will be needed to be loaded again.
Parameters
- array $paths optional array()
- associative array with package names as keys and a list of directories for new search paths
- boolean|string $mode optional App::PREPEND
App::RESET will set paths, App::APPEND with append paths, App::PREPEND will prepend paths (default) App::REGISTER will register new packages and their paths, %s in path will be replaced by APP path
Link
core() public static ¶
core( string $type )
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
Parameters
- string $type
- Package type.
Returns
full path to package
Link
import() public static ¶
import( string|array $type = null , string $name = null , boolean|array $parent = true , array $search = array() , string $file = null , boolean $return = false )
Finds classes based on $name or specific file(s) to search. Calling App::import() will not construct any classes contained in the files. It will only find and require() the file.
Parameters
- string|array $type optional null
The type of Class if passed as a string, or all params can be passed as a single array to $type.
- string $name optional null
- Name of the Class or a unique name for the file
- boolean|array $parent optional true
boolean true if Class Parent should be searched, accepts key => value array('parent' => $parent, 'file' => $file, 'search' => $search, 'ext' => '$ext'); $ext allows setting the extension of the file name based on Inflector::underscore($name) . ".$ext";
- array $search optional array()
- paths to search for files, array('path 1', 'path 2', 'path 3');
- string $file optional null
- full name of the file to search for including extension
- boolean $return optional false
Return the loaded file, the file must have a return statement in it to work: return $variable;
Returns
true if Class is already in memory or if file is found and loaded, false if not
Link
load() public static ¶
load( string $className )
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
Parameters
- string $className
- the name of the class to load
Returns
location() public static ¶
location( string $className )
Returns the package name where a class was defined to be located at
Parameters
- string $className
- name of the class to obtain the package name from
Returns
Package name, or null if not declared
Link
objects() public static ¶
objects( string $type , string|array $path = null , boolean $cache = true )
Returns an array of objects of the given type.
Example usage:
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');
When scanning directories, files and directories beginning with .
will be excluded as these
are commonly used by version control systems.
Parameters
- string $type
- Type of object, i.e. 'Model', 'Controller', 'View/Helper', 'file', 'class' or 'plugin'
- string|array $path optional null
- Optional Scan only the path given. If null, paths for the chosen type will be used.
- boolean $cache optional true
- Set to false to rescan objects of the chosen type. Defaults to true.
Returns
Either false on incorrect / miss. Or an array of found objects.
Link
path() public static ¶
path( string $type , string $plugin = null )
Used to read information stored path
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
Parameters
- string $type
- type of path
- string $plugin optional null
- name of plugin
Returns
Link
paths() public static ¶
paths( )
Get all the currently loaded paths from App. Useful for inspecting or storing all paths App knows about. For a paths to a specific package use App::path()
Returns
An array of packages and their associated paths.
Link
pluginPath() public static deprecated ¶
pluginPath( string $plugin )
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'
Deprecated
Parameters
- string $plugin
- CamelCased/lower_cased plugin name to find the path of.
Returns
full path to the plugin.
Link
shutdown() public static ¶
shutdown( )
Object destructor.
Writes cache file if changes have been made to the $_map. Also, check if a fatal error happened and call the handler.
themePath() public static ¶
themePath( string $theme )
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
Parameters
- string $theme
- theme name to find the path of.
Returns
full path to the theme.
Link
uses() public static ¶
uses( string $className , string $location )
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::uses('MyCustomController', 'Controller');
will setup the class to be found under Controller package
App::uses('MyHelper', 'MyPlugin.View/Helper');
will setup the helper class to be found in plugin's helper package
Parameters
- string $className
- the name of the class to configure package for
- string $location
- the package name
Link
Properties detail
$_cacheChange ¶
Indicates whether the class cache should be stored again because of an addition to it
false
$_objectCacheChange ¶
Indicates whether the object cache should be stored again because of an addition to it
false
$_packageFormat ¶
Holds the templates for each customizable package path in the application
array()
$bootstrapping ¶
Indicates the the Application is in the bootstrapping process. Used to better cache loaded classes while the cache libraries have not been yet initialized
false
$legacy ¶
Maps an old style CakePHP class type to the corresponding package
array( 'models' => 'Model', 'behaviors' => 'Model/Behavior', 'datasources' => 'Model/Datasource', 'controllers' => 'Controller', 'components' => 'Controller/Component', 'views' => 'View', 'helpers' => 'View/Helper', 'shells' => 'Console/Command', 'libs' => 'Lib', 'vendors' => 'Vendor', 'plugins' => 'Plugin', 'locales' => 'Locale' )
$types ¶
List of object types and their properties
array( 'class' => array('extends' => null, 'core' => true), 'file' => array('extends' => null, 'core' => true), 'model' => array('extends' => 'AppModel', 'core' => false), 'behavior' => array('suffix' => 'Behavior', 'extends' => 'Model/ModelBehavior', 'core' => true), 'controller' => array('suffix' => 'Controller', 'extends' => 'AppController', 'core' => true), 'component' => array('suffix' => 'Component', 'extends' => null, 'core' => true), 'lib' => array('extends' => null, 'core' => true), 'view' => array('suffix' => 'View', 'extends' => null, 'core' => true), 'helper' => array('suffix' => 'Helper', 'extends' => 'AppHelper', 'core' => true), 'vendor' => array('extends' => null, 'core' => true), 'shell' => array('suffix' => 'Shell', 'extends' => 'AppShell', 'core' => true), 'plugin' => array('extends' => null, 'core' => true) )