Creating Libraries
+ +When we use the term "Libraries" we are normally referring to the classes that are located in the libraries +directory and described in the Class Reference of this user guide. In this case, however, we will instead describe how you can create +your own libraries within your application/libraries directory in order to maintain separation between your local resources +and the global framework resources.
+ +As an added bonus, CodeIgniter permits your libraries to extend native classes if you simply need to add some functionality +to an existing library. Or you can even replace native libraries just by placing identically named versions in your application/libraries folder.
+ +In summary:
+ +-
+
- You can create entirely new libraries. +
- You can extend native libraries. +
- You can replace native libraries. +
The page below explains these three concepts in detail.
+ +Note: The Database classes can not be extended or replaced with your own classes. All other classes are able to be replaced/extended.
+ + +Storage
+ +Your library classes should be placed within your application/libraries folder, as this is where CodeIgniter will look for them when +they are initialized.
+ + +Naming Conventions
+ +-
+
- File names must be capitalized. For example: Myclass.php +
- Class declarations must be capitalized. For example: class Myclass +
- Class names and file names must match. +
The Class File
+ +Classes should have this basic prototype (Note: We are using the name Someclass purely as an example):
+ +<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
+
+class Someclass {
+
+ public function some_function()
+ {
+ }
+}
+/* End of file Someclass.php */
+
+
+Using Your Class
+ +From within any of your Controller functions you can initialize your class using the standard:
+ +$this->load->library('someclass');
+
+Where someclass is the file name, without the ".php" file extension. You can submit the file name capitalized or lower case. +CodeIgniter doesn't care.
+ +Once loaded you can access your class using the lower case version:
+ +$this->someclass->some_function(); // Object instances will always be lower case
+
+
+
+
+Passing Parameters When Initializing Your Class
+ +In the library loading function you can dynamically pass data as an array via the second parameter and it will be passed to your class +constructor:
+ +
+$params = array('type' => 'large', 'color' => 'red');
+
+$this->load->library('Someclass', $params);
+
+If you use this feature you must set up your class constructor to expect data:
+ +<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
+
+class Someclass {
+
+ public function __construct($params)
+ {
+ // Do something with $params
+ }
+}
+?>
+
+You can also pass parameters stored in a config file. Simply create a config file named identically to the class file name +and store it in your application/config/ folder. Note that if you dynamically pass parameters as described above, +the config file option will not be available.
+ + + + + + + +Utilizing CodeIgniter Resources within Your Library
+ + +To access CodeIgniter's native resources within your library use the get_instance() function. +This function returns the CodeIgniter super object.
+ +Normally from within your controller functions you will call any of the available CodeIgniter functions using the $this construct:
+ +
+$this->load->helper('url');
+$this->load->library('session');
+$this->config->item('base_url');
+etc.
+
+
+$this, however, only works directly within your controllers, your models, or your views. +If you would like to use CodeIgniter's classes from within your own custom classes you can do so as follows:
+ + +First, assign the CodeIgniter object to a variable:
+ +$CI =& get_instance();
+
+Once you've assigned the object to a variable, you'll use that variable instead of $this:
+ +
+$CI =& get_instance();
+
+$CI->load->helper('url');
+$CI->load->library('session');
+$CI->config->item('base_url');
+etc.
+
+
+Note: You'll notice that the above get_instance() function is being passed by reference:
+
+$CI =& get_instance();
+
+
+This is very important. Assigning by reference allows you to use the original CodeIgniter object rather than creating a copy of it.
Replacing Native Libraries with Your Versions
+ +Simply by naming your class files identically to a native library will cause CodeIgniter to use it instead of the native one. To use this +feature you must name the file and the class declaration exactly the same as the native library. For example, to replace the native Email library +you'll create a file named application/libraries/Email.php, and declare your class with:
+ +
+class CI_Email {
+
+}
+
+Note that most native classes are prefixed with CI_.
+ +To load your library you'll see the standard loading function:
+ +$this->load->library('email');
+
+Note: At this time the Database classes can not be replaced with your own versions.
+ + +Extending Native Libraries
+ +If all you need to do is add some functionality to an existing library - perhaps add a function or two - then +it's overkill to replace the entire library with your version. In this case it's better to simply extend the class. +Extending a class is nearly identical to replacing a class with a couple exceptions:
+ +-
+
- The class declaration must extend the parent class. +
- Your new class name and filename must be prefixed with MY_ (this item is configurable. See below.). +
For example, to extend the native Email class you'll create a file named application/libraries/MY_Email.php, and declare your class with:
+ +
+class MY_Email extends CI_Email {
+
+}
+
+Note: If you need to use a constructor in your class make sure you extend the parent constructor:
+ + +
+class MY_Email extends CI_Email {
+
+ public function __construct()
+ {
+ parent::__construct();
+ }
+}
+
+
+Loading Your Sub-class
+ +To load your sub-class you'll use the standard syntax normally used. DO NOT include your prefix. For example, +to load the example above, which extends the Email class, you will use:
+ +$this->load->library('email');
+
+Once loaded you will use the class variable as you normally would for the class you are extending. In the case of +the email class all calls will use:
+ + +$this->email->some_function();
+
+
+Setting Your Own Prefix
+ +To set your own sub-class prefix, open your application/config/config.php file and look for this item:
+ +$config['subclass_prefix'] = 'MY_';
+
+Please note that all native CodeIgniter libraries are prefixed with CI_ so DO NOT use that as your prefix.
+ + + +