user_guide/libraries/config.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   3 <head>
   4
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <title>Config Class : CodeIgniter User Guide</title>
   7
   8 <style type='text/css' media='all'>@import url('../userguide.css');</style>
   9 <link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
  10
  11 <script type="text/javascript" src="../nav/nav.js"></script>
  12 <script type="text/javascript" src="../nav/prototype.lite.js"></script>
  13 <script type="text/javascript" src="../nav/moo.fx.js"></script>
  14 <script type="text/javascript" src="../nav/user_guide_menu.js"></script>
  15
  16 <meta http-equiv='expires' content='-1' />
  17 <meta http-equiv= 'pragma' content='no-cache' />
  18 <meta name='robots' content='all' />
  19 <meta name='author' content='ExpressionEngine Dev Team' />
  20 <meta name='description' content='CodeIgniter User Guide' />
  21
  22 </head>
  23 <body>
  24
  25 <!-- START NAVIGATION -->
  26 <div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
  27 <div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
  28 <div id="masthead">
  29 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
  30 <tr>
  31 <td><h1>CodeIgniter User Guide Version 2.0.2</h1></td>
  32 <td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
  33 </tr>
  34 </table>
  35 </div>
  36 <!-- END NAVIGATION -->
  37
  38
  39 <!-- START BREADCRUMB -->
  40 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
  41 <tr>
  42 <td id="breadcrumb">
  43 <a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
  44 <a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
  45 Config Class
  46 </td>
  47 <td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
  48 </tr>
  49 </table>
  50 <!-- END BREADCRUMB -->
  51
  52 <br clear="all" />
  53
  54
  55 <!-- START CONTENT -->
  56 <div id="content">
  57
  58
  59 <h1>Config Class</h1>
  60
  61 <p>The Config class provides a means to retrieve configuration preferences.  These preferences can
  62 come from the default config file (<samp>application/config/config.php</samp>) or from your own custom config files.</p>
  63
  64 <p class="important"><strong>Note:</strong> This class is initialized automatically by the system so there is no need to do it manually.</p>
  65
  66
  67 <h2>Anatomy of a Config File</h2>
  68
  69 <p>By default, CodeIgniter has one primary config file, located at <samp>application/config/config.php</samp>.  If you open the file using
  70 your text editor you'll see that config items are stored in an array called <var>$config</var>.</p>
  71
  72 <p>You can add your own config items to
  73 this file, or if you prefer to keep your configuration items separate (assuming you even need config items),
  74 simply create your own file and save it in <dfn>config</dfn> folder.</p>
  75
  76 <p><strong>Note:</strong> If you do create your own config files use the same format as the primary one, storing your items in
  77 an array called  <var>$config</var>. CodeIgniter will intelligently manage these files so there will be no conflict even though
  78 the array has the same name (assuming an array index is not named the same as another).</p>
  79
  80 <h2>Loading a Config File</h2>
  81
  82 <p><strong>Note:</strong> CodeIgniter automatically loads the primary config file (<samp>application/config/config.php</samp>),
  83 so you will only need to load a config file if you have created your own.</p>
  84
  85 <p>There are two ways to load a config file:</p>
  86
  87 <ol><li><strong>Manual Loading</strong>
  88
  89 <p>To load one of your custom config files you will use the following function within the <a href="../general/controllers.html">controller</a> that needs it:</p>
  90
  91 <code>$this->config->load('<var>filename</var>');</code>
  92
  93 <p>Where <var>filename</var> is the name of your config file, without the .php file extension.</p>
  94
  95 <p>If you need to load multiple config files normally they will be merged into one master config array.  Name collisions can occur, however, if
  96 you have identically named array indexes in different config files.  To avoid collisions you can set the second parameter to <kbd>TRUE</kbd>
  97 and each config file will be stored in an array index corresponding to the name of the config file. Example:</p>
  98
  99 <code>
 100 // Stored in an array with this prototype:  $this->config['blog_settings'] = $config<br />
 101 $this->config->load('<var>blog_settings</var>', <kbd>TRUE</kbd>);</code>
 102
 103 <p>Please see the section entitled <dfn>Fetching Config Items</dfn> below to learn how to retrieve config items set this way.</p>
 104
 105 <p>The third parameter allows you to suppress errors in the event that a config file does not exist:</p>
 106
 107 <code>$this->config->load('<var>blog_settings</var>', <dfn>FALSE</dfn>, <kbd>TRUE</kbd>);</code>
 108
 109 </li>
 110 <li><strong>Auto-loading</strong>
 111
 112 <p>If you find that you need a particular config file globally, you can have it loaded automatically by the system.  To do this,
 113 open the <strong>autoload.php</strong> file, located at <samp>application/config/autoload.php</samp>, and add your config file as
 114 indicated in the file.</p>
 115 </li>
 116 </ol>
 117
 118
 119 <h2>Fetching Config Items</h2>
 120
 121 <p>To retrieve an item from your config file, use the following function:</p>
 122
 123 <code>$this->config->item('<var>item name</var>');</code>
 124
 125 <p>Where <var>item name</var> is the $config array index you want to retrieve. For example, to fetch your language choice you'll do this:</p>
 126
 127 <code>$lang = $this->config->item('language');</code>
 128
 129 <p>The function returns FALSE (boolean) if the item you are trying to fetch does not exist.</p>
 130
 131 <p>If you are using the second parameter of the <kbd>$this->config->load</kbd> function in order to assign your config items to a specific index
 132 you can retrieve it by specifying the index name in the second parameter of the <kbd>$this->config->item()</kbd> function.  Example:</p>
 133
 134 <code>
 135 // Loads a config file named blog_settings.php and assigns it to an index named "blog_settings"<br />
 136 $this->config->load('<var>blog_settings</var>', <kbd>TRUE</kbd>);<br /><br />
 137
 138 // Retrieve a config item named site_name contained within the blog_settings array<br />
 139 $site_name = $this->config->item('<dfn>site_name</dfn>', '<var>blog_settings</var>');<br /><br />
 140
 141 // An alternate way to specify the same item:<br />
 142 $blog_config = $this->config->item('<var>blog_settings</var>');<br />
 143 $site_name = $blog_config['site_name'];</code>
 144
 145 <h2>Setting a Config Item</h2>
 146
 147 <p>If you would like to dynamically set a config item or change an existing one, you can do so using:</p>
 148
 149 <code>$this->config->set_item('<var>item_name</var>', '<var>item_value</var>');</code>
 150
 151 <p>Where <var>item_name</var> is the $config array index you want to change, and <var>item_value</var> is its value.</p>
 152
 153 <a name="environments"></a>
 154 <h2>Environments</h2>
 155
 156 <p>
 157     You may load different configuration files depending on the current environment.
 158     The <kbd>ENVIRONMENT</kbd> constant is defined in index.php, and is described
 159     in detail in the <a href="../general/environments.html">Handling Environments</a>
 160     section.
 161 </p>
 162
 163 <p>
 164     To create an environment-specific configuration file,
 165     create or copy a configuration file in application/config/{ENVIRONMENT}/{FILENAME}.php
 166 </p>
 167
 168 <p>For example, to create a production-only config.php, you would:</p>
 169
 170 <ol>
 171     <li>Create the directory application/config/production/</li>
 172     <li>Copy your existing config.php into the above directory</li>
 173     <li>Edit application/config/production/config.php so it contains your production settings</li>
 174 </ol>
 175
 176 <p>
 177     When you set the <kbd>ENVIRONMENT</kbd> constant to 'production', the settings
 178     for your new production-only config.php will be loaded.
 179 </p>
 180
 181 <p>You can place the following configuration files in environment-specific folders:</p>
 182
 183 <ul>
 184 <li>Default CodeIgniter configuration files</li>
 185 <li>Your own custom configuration files</li>
 186 </ul>
 187
 188 <p><strong>Note:</strong> CodeIgniter always tries to load the configuration files for the current environment first. If the file does not exist, the global config file (i.e., the one in <samp>application/config/</samp>) is loaded. This means you are not obligated to place <strong>all</strong> of your configuration files in an environment folder &minus; only the files that change per environment.</p>
 189
 190 <h2>Helper Functions</h2>
 191
 192 <p>The config class has the following helper functions:</p>
 193
 194 <h2>$this->config->site_url();</h2>
 195 <p>This function retrieves the URL to your site, along with the "index" value you've specified in the config file.</p>
 196
 197 <h2>$this->config->system_url();</h2>
 198 <p>This function retrieves the URL to your <dfn>system folder</dfn>.</p>
 199
 200
 201 </div>
 202 <!-- END CONTENT -->
 203
 204
 205 <div id="footer">
 206 <p>
 207 Previous Topic:&nbsp;&nbsp;<a href="calendar.html">Calendaring Class</a>
 208 &nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 209 <a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 210 <a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 211 Next Topic:&nbsp;&nbsp;<a href="../database/index.html">Database Class</a>
 212 </p>
 213 <p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
 214 </div>
 215
 216 </body>
 217 </html>