diff options
Diffstat (limited to 'user_guide_src/source/libraries/loader.rst')
| -rw-r--r-- | user_guide_src/source/libraries/loader.rst | 567 |
1 files changed, 315 insertions, 252 deletions
diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 91db5afbd..15d9d80fc 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -11,368 +11,431 @@ can be libraries (classes) :doc:`View files <../general/views>`, .. note:: This class is initialized automatically by the system so there is no need to do it manually. -The following methods are available in this class: +.. contents:: + :local: -$this->load->library('class_name', $config, 'object name') -========================================================== +.. raw:: html -This method is used to load core classes. Where class_name is the -name of the class you want to load. + <div class="custom-index container"></div> -.. note:: We use the terms "class" and "library" interchangeably. +Application "Packages" +====================== -For example, if you would like to send email with CodeIgniter, the first -step is to load the email class within your controller:: +An application package allows for the easy distribution of complete sets +of resources in a single directory, complete with its own libraries, +models, helpers, config, and language files. It is recommended that +these packages be placed in the application/third_party directory. Below +is a sample map of an package directory. - $this->load->library('email'); +The following is an example of a directory for an application package +named "Foo Bar". -Once loaded, the library will be ready for use, using -$this->email->*some_method*(). +:: -Library files can be stored in subdirectories within the main -"libraries" directory, or within your personal application/libraries -directory. To load a file located in a subdirectory, simply include the -path, relative to the "libraries" directory. For example, if you have -file located at:: + /application/third_party/foo_bar - libraries/flavors/Chocolate.php + config/ + helpers/ + language/ + libraries/ + models/ -You will load it using:: +Whatever the purpose of the "Foo Bar" application package, it has its +own config files, helpers, language files, libraries, and models. To use +these resources in your controllers, you first need to tell the Loader +that you are going to be loading resources from a package, by adding the +package path via the ``add_package_path()`` method. - $this->load->library('flavors/chocolate'); +Package view files +------------------ -You may nest the file in as many subdirectories as you want. +By Default, package view files paths are set when ``add_package_path()`` +is called. View paths are looped through, and once a match is +encountered that view is loaded. -Additionally, multiple libraries can be loaded at the same time by -passing an array of libraries to the load method. +In this instance, it is possible for view naming collisions within +packages to occur, and possibly the incorrect package being loaded. To +ensure against this, set an optional second parameter of FALSE when +calling ``add_package_path()``. :: - $this->load->library(array('email', 'table')); + $this->load->add_package_path(APPPATH.'my_app', FALSE); + $this->load->view('my_app_index'); // Loads + $this->load->view('welcome_message'); // Will not load the default welcome_message b/c the second param to add_package_path is FALSE -Setting options ---------------- + // Reset things + $this->load->remove_package_path(APPPATH.'my_app'); -The second (optional) parameter allows you to optionally pass -configuration setting. You will typically pass these as an array:: + // Again without the second parameter: + $this->load->add_package_path(APPPATH.'my_app'); + $this->load->view('my_app_index'); // Loads + $this->load->view('welcome_message'); // Loads - $config = array ( - 'mailtype' => 'html', - 'charset' => 'utf-8, - 'priority' => '1' - ); +*************** +Class Reference +*************** - $this->load->library('email', $config); +.. class:: CI_Loader -Config options can usually also be set via a config file. Each library -is explained in detail in its own page, so please read the information -regarding each one you would like to use. + .. method:: library($library[, $params = NULL[, $object_name = NULL]]) -Please take note, when multiple libraries are supplied in an array for -the first parameter, each will receive the same parameter information. + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: object -Assigning a Library to a different object name ----------------------------------------------- + This method is used to load core classes. -If the third (optional) parameter is blank, the library will usually be -assigned to an object with the same name as the library. For example, if -the library is named Calendar, it will be assigned to a variable named -$this->calendar. + .. note:: We use the terms "class" and "library" interchangeably. -If you prefer to set your own class names you can pass its value to the -third parameter:: + For example, if you would like to send email with CodeIgniter, the first + step is to load the email class within your controller:: - $this->load->library('calendar', '', 'my_calendar'); + $this->load->library('email'); - // Calendar class is now accessed using: - $this->my_calendar + Once loaded, the library will be ready for use, using ``$this->email``. -Please take note, when multiple libraries are supplied in an array for -the first parameter, this parameter is discarded. + Library files can be stored in subdirectories within the main + "libraries" directory, or within your personal *application/libraries* + directory. To load a file located in a subdirectory, simply include the + path, relative to the "libraries" directory. For example, if you have + file located at:: -$this->load->driver('parent_name', $config, 'object name') -========================================================== + libraries/flavors/Chocolate.php -This method is used to load driver libraries. Where parent_name is the -name of the parent class you want to load. + You will load it using:: -As an example, if you would like to use sessions with CodeIgniter, the first -step is to load the session driver within your controller:: + $this->load->library('flavors/chocolate'); - $this->load->driver('session'); + You may nest the file in as many subdirectories as you want. -Once loaded, the library will be ready for use, using -$this->session->*some_method*(). + Additionally, multiple libraries can be loaded at the same time by + passing an array of libraries to the load method. + :: -Driver files must be stored in a subdirectory within the main -"libraries" directory, or within your personal application/libraries -directory. The subdirectory must match the parent class name. Read the -:doc:`Drivers <../general/drivers>` description for details. + $this->load->library(array('email', 'table')); -Additionally, multiple driver libraries can be loaded at the same time by -passing an array of drivers to the load method. + **Setting options** -:: + The second (optional) parameter allows you to optionally pass + configuration setting. You will typically pass these as an array:: - $this->load->driver(array('session', 'cache')); + $config = array ( + 'mailtype' => 'html', + 'charset' => 'utf-8, + 'priority' => '1' + ); -Setting options ---------------- + $this->load->library('email', $config); -The second (optional) parameter allows you to optionally pass -configuration settings. You will typically pass these as an array:: + Config options can usually also be set via a config file. Each library + is explained in detail in its own page, so please read the information + regarding each one you would like to use. - $config = array( - 'sess_driver' => 'cookie', - 'sess_encrypt_cookie' => true, - 'encryption_key' => 'mysecretkey' - ); + Please take note, when multiple libraries are supplied in an array for + the first parameter, each will receive the same parameter information. - $this->load->driver('session', $config); + **Assigning a Library to a different object name** -Config options can usually also be set via a config file. Each library -is explained in detail in its own page, so please read the information -regarding each one you would like to use. + If the third (optional) parameter is blank, the library will usually be + assigned to an object with the same name as the library. For example, if + the library is named Calendar, it will be assigned to a variable named + ``$this->calendar``. -Assigning a Driver to a different object name ---------------------------------------------- + If you prefer to set your own class names you can pass its value to the + third parameter:: -If the third (optional) parameter is blank, the library will be assigned -to an object with the same name as the parent class. For example, if -the library is named Session, it will be assigned to a variable named -``$this->session``. + $this->load->library('calendar', NULL, 'my_calendar'); -If you prefer to set your own class names you can pass its value to the -third parameter:: + // Calendar class is now accessed using: + $this->my_calendar - $this->load->library('session', '', 'my_session'); + Please take note, when multiple libraries are supplied in an array for + the first parameter, this parameter is discarded. - // Session class is now accessed using: - $this->my_session + .. method:: driver($library[, $params = NULL[, $object_name]]) -.. note:: Driver libraries may also be loaded with the ``library()`` method, - but it is faster to use ``driver()``. + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: object -$this->load->view('file_name', $data, TRUE/FALSE) -================================================= + This method is used to load driver libraries, acts very much like the + ``library()`` method. -This method is used to load your View files. If you haven't read the -:doc:`Views <../general/views>` section of the user guide it is -recommended that you do since it shows you how this method is -typically used. + As an example, if you would like to use sessions with CodeIgniter, the first + step is to load the session driver within your controller:: -The first parameter is required. It is the name of the view file you -would like to load. + $this->load->driver('session'); -.. note:: The .php file extension does not need to be specified unless - you use something other than .php. + Once loaded, the library will be ready for use, using ``$this->session``. -The second **optional** parameter can take an associative array or an -object as input, which it runs through the PHP -`extract() <http://www.php.net/extract>`_ function to convert to variables -that can be used in your view files. Again, read the -:doc:`Views <../general/views>` page to learn how this might be useful. + Driver files must be stored in a subdirectory within the main + "libraries" directory, or within your personal *application/libraries* + directory. The subdirectory must match the parent class name. Read the + :doc:`Drivers <../general/drivers>` description for details. -The third **optional** parameter lets you change the behavior of the -method so that it returns data as a string rather than sending it to -your browser. This can be useful if you want to process the data in some -way. If you set the parameter to true (boolean) it will return data. The -default behavior is false, which sends it to your browser. Remember to -assign it to a variable if you want the data returned:: + Additionally, multiple driver libraries can be loaded at the same time by + passing an array of drivers to the load method. + :: - $string = $this->load->view('myfile', '', true); + $this->load->driver(array('session', 'cache')); -$this->load->model('model_name'); -================================== + **Setting options** -:: + The second (optional) parameter allows you to optionally pass + configuration settings. You will typically pass these as an array:: - $this->load->model('model_name'); + $config = array( + 'sess_driver' => 'cookie', + 'sess_encrypt_cookie' => true, + 'encryption_key' => 'mysecretkey' + ); + $this->load->driver('session', $config); -If your model is located in a subdirectory, include the relative path -from your models directory. For example, if you have a model located at -application/models/blog/Queries.php you'll load it using:: + Config options can usually also be set via a config file. Each library + is explained in detail in its own page, so please read the information + regarding each one you would like to use. - $this->load->model('blog/queries'); + **Assigning a Driver to a different object name** -If you would like your model assigned to a different object name you can -specify it via the second parameter of the loading method:: + If the third (optional) parameter is blank, the library will be assigned + to an object with the same name as the parent class. For example, if + the library is named Session, it will be assigned to a variable named + ``$this->session``. - $this->load->model('model_name', 'fubar'); - $this->fubar->method(); + If you prefer to set your own class names you can pass its value to the + third parameter:: -$this->load->database('options', TRUE/FALSE) -============================================ + $this->load->library('session', '', 'my_session'); -This method lets you load the database class. The two parameters are -**optional**. Please see the :doc:`database <../database/index>` -section for more info. + // Session class is now accessed using: + $this->my_session -$this->load->vars($array) -========================= + .. method:: view($view[, $vars = array()[, return = FALSE]]) -This method takes an associative array as input and generates -variables using the PHP `extract <http://www.php.net/extract>`_ -method. This method produces the same result as using the second -parameter of the ``$this->load->view()`` method above. The reason you -might want to use this method independently is if you would like to -set some global variables in the constructor of your controller and have -them become available in any view file loaded from any method. You can -have multiple calls to this method. The data get cached and merged -into one array for conversion to variables. + :param string $view: View name + :param array $vars: An associative array of variables + :param bool $return: Whether to return the loaded view + :returns: mixed -$this->load->get_var($key) -========================== + This method is used to load your View files. If you haven't read the + :doc:`Views <../general/views>` section of the user guide it is + recommended that you do since it shows you how this method is + typically used. -This method checks the associative array of variables available to -your views. This is useful if for any reason a var is set in a library -or another controller method using ``$this->load->vars()``. + The first parameter is required. It is the name of the view file you + would like to load. -$this->load->get_vars() -======================= + .. note:: The .php file extension does not need to be specified unless + you use something other than .php. -This method retrieves all variables available to your views. + The second **optional** parameter can take an associative array or an + object as input, which it runs through the PHP + `extract() <http://www.php.net/extract>`_ function to convert to variables + that can be used in your view files. Again, read the + :doc:`Views <../general/views>` page to learn how this might be useful. -$this->load->clear_vars() -========================= + The third **optional** parameter lets you change the behavior of the + method so that it returns data as a string rather than sending it to + your browser. This can be useful if you want to process the data in some + way. If you set the parameter to TRUE (boolean) it will return data. The + default behavior is FALSE, which sends it to your browser. Remember to + assign it to a variable if you want the data returned:: -Clears cached view variables. + $string = $this->load->view('myfile', '', TRUE); -$this->load->helper('file_name') -================================ + .. method:: vars($vars[, $val = '']) -This method loads helper files, where file_name is the name of the -file, without the _helper.php extension. + :param mixed $vars: An array of variables or a single variable name + :param mixed $val: Optional variable value + :returns: object -$this->load->file('filepath/filename', TRUE/FALSE) -================================================== + This method takes an associative array as input and generates + variables using the PHP `extract() <http://www.php.net/extract>`_ + function. This method produces the same result as using the second + parameter of the ``$this->load->view()`` method above. The reason you + might want to use this method independently is if you would like to + set some global variables in the constructor of your controller and have + them become available in any view file loaded from any method. You can + have multiple calls to this method. The data get cached and merged + into one array for conversion to variables. -This is a generic file loading method. Supply the filepath and name in -the first parameter and it will open and read the file. By default the -data is sent to your browser, just like a View file, but if you set the -second parameter to true (boolean) it will instead return the data as a -string. + .. method:: get_var($key) -$this->load->language('file_name') -================================== + :param string $key: Variable name key + :returns: mixed -This method is an alias of the :doc:`language loading -method <language>`: ``$this->lang->load()`` + This method checks the associative array of variables available to + your views. This is useful if for any reason a var is set in a library + or another controller method using ``$this->load->vars()``. -$this->load->config('file_name') -================================ + .. method:: get_vars() -This method is an alias of the :doc:`config file loading -method <config>`: ``$this->config->load()`` + :returns: array -$this->load->is_loaded('library_name') -====================================== + This method retrieves all variables available to your views. -The ``is_loaded()`` method allows you to check if a class has already -been loaded or not. + .. method:: clear_vars() -.. note:: The word "class" here refers to libraries and drivers. + :returns: object -If the requested class has been loaded, the method returns its assigned -name in the CI Super-object and FALSE if it's not:: + Clears cached view variables. - $this->load->library('form_validation'); - $this->load->is_loaded('Form_validation'); // returns 'form_validation' + .. method:: model($model[, $name = ''[, $db_conn = FALSE]]) - $this->load->is_loaded('Nonexistent_library'); // returns FALSE + :param mixed $model: Model name or an array containing multiple models + :param string $name: Optional object name to assign the model to + :param string $db_conn: Optional database configuration group to load + :returns: object -.. important:: If you have more than one instance of a class (assigned to - different properties), then the first one will be returned. + :: -:: + $this->load->model('model_name'); - $this->load->library('form_validation', $config, 'fv'); - $this->load->library('form_validation'); - $this->load->is_loaded('Form_validation'); // returns 'fv' + If your model is located in a subdirectory, include the relative path + from your models directory. For example, if you have a model located at + *application/models/blog/Queries.php* you'll load it using:: -Application "Packages" -====================== + $this->load->model('blog/queries'); -An application package allows for the easy distribution of complete sets -of resources in a single directory, complete with its own libraries, -models, helpers, config, and language files. It is recommended that -these packages be placed in the application/third_party directory. Below -is a sample map of an package directory + If you would like your model assigned to a different object name you can + specify it via the second parameter of the loading method:: -Sample Package "Foo Bar" Directory Map -====================================== + $this->load->model('model_name', 'fubar'); + $this->fubar->method(); -The following is an example of a directory for an application package -named "Foo Bar". + .. method:: database([$params = ''[, $return = FALSE[, $query_builder = NULL]]]) -:: + :param mixed $params: Database group name or configuration options + :param bool $return: Whether to return the loaded database object + :param bool $query_builder: Whether to load the Query Builder + :returns: mixed - /application/third_party/foo_bar + This method lets you load the database class. The two parameters are + **optional**. Please see the :doc:`database <../database/index>` + section for more info. - config/ - helpers/ - language/ - libraries/ - models/ + .. method:: dbforge([$db = NULL[, $return = FALSE]]) -Whatever the purpose of the "Foo Bar" application package, it has its -own config files, helpers, language files, libraries, and models. To use -these resources in your controllers, you first need to tell the Loader -that you are going to be loading resources from a package, by adding the -package path. + :param object $db: Database object + :param bool $return: Whether to return the Database Forge instance + :returns: mixed -$this->load->add_package_path() ---------------------------------- + Loads the :doc:`Database Forge <../database/forge>` class, please refer + to that manual for more info. -Adding a package path instructs the Loader class to prepend a given path -for subsequent requests for resources. As an example, the "Foo Bar" -application package above has a library named Foo_bar.php. In our -controller, we'd do the following:: + .. method:: dbutil([$db = NULL[, $return = FALSE]]) - $this->load->add_package_path(APPPATH.'third_party/foo_bar/'); - $this->load->library('foo_bar'); + :param object $db: Database object + :param bool $return: Whether to return the Database Utilities instance + :returns: mixed -$this->load->remove_package_path() ------------------------------------- + Loads the :doc:`Database Utilities <../database/utilities>` class, please + refer to that manual for more info. -When your controller is finished using resources from an application -package, and particularly if you have other application packages you -want to work with, you may wish to remove the package path so the Loader -no longer looks in that directory for resources. To remove the last path -added, simply call the method with no parameters. + .. method:: helper($helpers) -$this->load->remove_package_path() ------------------------------------- + :param mixed $helpers: Helper name as a string or an array containing multiple helpers + :returns: object -Or to remove a specific package path, specify the same path previously -given to add_package_path() for a package.:: + This method loads helper files, where file_name is the name of the + file, without the _helper.php extension. - $this->load->remove_package_path(APPPATH.'third_party/foo_bar/'); + .. method:: file($path[, $return = FALSE]) -Package view files ------------------- + :param string $path: File path + :param bool $return: Whether to return the loaded file + :returns: mixed -By Default, package view files paths are set when add_package_path() -is called. View paths are looped through, and once a match is -encountered that view is loaded. + This is a generic file loading method. Supply the filepath and name in + the first parameter and it will open and read the file. By default the + data is sent to your browser, just like a View file, but if you set the + second parameter to boolean TRUE it will instead return the data as a + string. -In this instance, it is possible for view naming collisions within -packages to occur, and possibly the incorrect package being loaded. To -ensure against this, set an optional second parameter of FALSE when -calling add_package_path(). + .. method:: language($files[, $lang = '']) -:: + :param mixed $files: Language file name or an array of multiple language files + :param string $lang: Language name + :returns: object - $this->load->add_package_path(APPPATH.'my_app', FALSE); - $this->load->view('my_app_index'); // Loads - $this->load->view('welcome_message'); // Will not load the default welcome_message b/c the second param to add_package_path is FALSE + This method is an alias of the :doc:`language loading + method <language>`: ``$this->lang->load()``. - // Reset things - $this->load->remove_package_path(APPPATH.'my_app'); + .. method:: config($file[, $use_sections = FALSE[, $fail_gracefully = FALSE]]) - // Again without the second parameter: - $this->load->add_package_path(APPPATH.'my_app'); - $this->load->view('my_app_index'); // Loads - $this->load->view('welcome_message'); // Loads
\ No newline at end of file + :param string $file: Configuration file name + :param bool $use_sections: Whether configuration values should be loaded into their own section + :param bool $fail_gracefully: Whether to just return FALSE in case of failure + :returns: bool + + This method is an alias of the :doc:`config file loading + method <config>`: ``$this->config->load()`` + + .. method:: is_loaded($class) + + :param string $class: Class name + :returns: mixed + + Allows you to check if a class has already been loaded or not. + + .. note:: The word "class" here refers to libraries and drivers. + + If the requested class has been loaded, the method returns its assigned + name in the CI Super-object and FALSE if it's not:: + + $this->load->library('form_validation'); + $this->load->is_loaded('Form_validation'); // returns 'form_validation' + + $this->load->is_loaded('Nonexistent_library'); // returns FALSE + + .. important:: If you have more than one instance of a class (assigned to + different properties), then the first one will be returned. + + :: + + $this->load->library('form_validation', $config, 'fv'); + $this->load->library('form_validation'); + + $this->load->is_loaded('Form_validation'); // returns 'fv' + + .. method:: add_package_path($path[, $view_cascade = TRUE]) + + :param string $path: Path to add + :param bool $view_cascade: Whether to use cascading views + :returns: object + + Adding a package path instructs the Loader class to prepend a given path + for subsequent requests for resources. As an example, the "Foo Bar" + application package above has a library named Foo_bar.php. In our + controller, we'd do the following:: + + $this->load->add_package_path(APPPATH.'third_party/foo_bar/') + ->library('foo_bar'); + + .. method:: remove_package_path([$path = '']) + + :param string $path: Path to remove + :returns: object + + When your controller is finished using resources from an application + package, and particularly if you have other application packages you + want to work with, you may wish to remove the package path so the Loader + no longer looks in that directory for resources. To remove the last path + added, simply call the method with no parameters. + + Or to remove a specific package path, specify the same path previously + given to ``add_package_path()`` for a package.:: + + $this->load->remove_package_path(APPPATH.'third_party/foo_bar/'); + + .. method:: get_package_paths([$include_base = TRUE]) + + :param bool $include_base: Whether to include BASEPATH + :returns: array + + Returns all currently available package paths.
\ No newline at end of file |