Documentation/libraries/config.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 12px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin: 0 0 5px 0;
  24                 }
  25
  26                 h2 {
  27                         font-size: 13px;
  28                         font-weight: bold;
  29                         margin: 5px 0 5px 0;
  30                 }
  31
  32                 ol, ul {
  33                         margin: 10px 0 10px 0;
  34                         list-style-position: inside;
  35                 }
  36
  37                 p {
  38                         margin: 5px 0 5px 0;
  39                 }
  40
  41                 .content {
  42                         border: 1px dotted #444;
  43                         margin: 10px;
  44                         padding: 10px;
  45                         text-align: justify;
  46                         width: 700px;
  47                 }
  48
  49                 .example {
  50                         border: 1px solid #ccc;
  51                         background: #eee;
  52                         margin: 10px;
  53                         padding: 10px;
  54                 }
  55         </style>
  56 </head>
  57
  58 <body>
  59         <div class="content">
  60                 <h1>Config Library</h1>
  61
  62                 <p>The config library provides an interface for retrieving configuration options.  These options can be from
  63                 the CarbonPHP configuration file <b>application/config/config.php</b> or from a custom configuration file.
  64                 <i>Note</i>: the config library is automatically loaded by CarbonPHP so there is no need for you to load
  65                 it.</p>
  66         </div>
  67
  68         <div class="content">
  69                 <h1>Configuration File Anatomy</h1>
  70
  71                 <p>CarbonPHP by default only uses one configuration file <b>application/config/config.php</b>.  When you view
  72                 this file in a text editor you will see all the options are stored in a PHP array called <b>$config</b>.</p>
  73
  74                 <p>CarbonPHP allows you to add your own configuration options to this file, or if you wish to keep your
  75                 configuration options separately you can simply create a file in the <b>application/config/</b> directory.</p>
  76
  77                 <p><i>Note</i>: if you choose to create your own configuration files you should follow the same format as the
  78                 CarbonPHP configuration file.  Configuration options should be stored in an array called <b>$config</b>.
  79                 CarbonPHP will be able to manage these files so that there will be no conflict.</p>
  80         </div>
  81
  82         <div class="content">
  83                 <h1>Loading a Configuration File</h1>
  84
  85                 <p>CarbonPHP automatically loads the CarbonPHP configuration file <b>application/config/config.php</b>.
  86                 You will only have to load your own configurations files if you have created them.</p>
  87
  88                 <p>There are two methods of loading your own configuration files.</p>
  89
  90                 <ol>
  91                         <li>
  92                                 <b>Manual Loading</b>
  93
  94                                 <p>To load one of your own configuration files, you will use the following method within a controller
  95                                 to load it</p>
  96
  97                                 <div class="example">
  98                                         $this->config->load('<b>filename</b>');
  99                                 </div>
 100
 101                                 <p>Where <b>filename</b> is the name of your configuration file without the file extension.</p>
 102
 103                                 <p>If you need to load multiple configuration files, they are normally merged into one array.  This
 104                                 means that array index name collisions can occur.  However if you have identical array index names in
 105                                 different configuration files you can set the second parameter to <b>true</b> and each configuration
 106                                 file will be stored in an array index corrosponding to the name of the configuration file.</p>
 107
 108                                 <div class="example">
 109                                         // Stored in an array with the prototype: $this->config['blog_settings'] = $config;<br />
 110                                         $this->config->load('<b>blog_settings</b>', <b>true</b>);
 111                                 </div>
 112
 113                                 <p>The loading method has a third parameter that will allow you to supress errors if a configuration
 114                                 file is not found.</p>
 115
 116                                 <div class="example">
 117                                         $this->config->load('<b>blog_settings</b>', <b>false</b>, <b>true</b>);
 118                                 </div>
 119                         </li>
 120
 121                         <li>
 122                                 <b>Automatically Loading</b>
 123
 124                                 <p>If you find that you're loading your configuration a lot for different controllers, you may wish
 125                                 to have that configuration file loaded automatically.  To do this you need to edit the
 126                                 <b>application/config/autoload.php</b> file, and add your configuration file as the comments say.</p>
 127                         </li>
 128                 </ol>
 129         </div>
 130
 131         <div class="content">
 132                 <h1>Retrieving Configuration Options</h1>
 133
 134                 <p>To retrieve a configuration option from your configuration file, you can do the following.</p>
 135
 136                 <div class="example">
 137                         $this->config->get_config_value('<b>item_name</b>');
 138                 </div>
 139
 140                 <p>Where <b>item_name</b> is the name of the $config array index you wish to retrieve.  For example if you
 141                 wish to retrieve the logging threshold you have set, you do the following.</p>
 142
 143                 <div class="example">
 144                         $threshold = $this->config->get_config_value('<b>logging_threshold</b>');
 145                 </div>
 146
 147                 <p>The method will return <b>false</b> if the configuration option you're trying to get does not exist.</p>
 148
 149                 <p>If you chose the use the second parameter of the <b>load()</b> method in order to assign your configuration
 150                 items to a specific array index you can retrieve it by specifying the index name in the second parameter of
 151                 the <b>get_config_value()</b> method.</p>
 152
 153                 <div class="example">
 154                         $this->config->load('<b>blog_settings</b>, <b>true</b>);<br />
 155                         <br />
 156                         $site_name = $this->config->get_config_value('<b>site_name</b>', '<b>blog_settings</b>');<br />
 157                         <br />
 158                         // You can also do the following...<br />
 159                         $blog_config = $this->config->get_config_value('<b>blog_settings</b>');<br />
 160                         $site_name = $blog_config['site_name'];
 161                 </div>
 162         </div>
 163
 164         <div class="content">
 165                 <h1>Setting Configuration Options</h1>
 166
 167                 <p>If you wish to dynamically change the value of a configuration option you can do the following.</p>
 168
 169                 <div class="example">
 170                         $this->config->set_config_value('<b>item_name</b>', '<b>new_item_value</b>');
 171                 </div>
 172
 173                 <p>Where <b>item_name</b> is the name of the index of the <b>$config</b> array you wish to change, and
 174                 <b>new_item_value</b> is the new value of the item.  <i>Note</i>: any dynamic changes made to configuration
 175                 files are not saved after CarbonPHP finishes executing.</p>
 176         </div>
 177
 178         <div class="content">
 179                 <h1>Helper Methods</h1>
 180
 181                 <p>The configuration class provides the following helper methods.</p>
 182
 183                 <h1>$this->config->get_site_url()</h1>
 184
 185                 <p>This method retrieves the URL to your site, along with the 'index' value you've specified in the configuration
 186                 file.</p>
 187
 188                 <h1>$this->config->get_system_url()</h1>
 189
 190                 <p>This method retrieves the URL to your <b>carbon</b> folder.</p>
 191
 192                 <h1>$this->config->get_application_url()</h1>
 193
 194                 <p>This method retrieves the URL to your <b>application</b> folder.</p>
 195         </div>
 196 </body>
 197
 198 </html>