forked from fuel/docs
-
Notifications
You must be signed in to change notification settings - Fork 118
/
config.html
416 lines (380 loc) · 14.5 KB
/
config.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="./../assets/css/combined.css">
<link rel="shortcut icon" href="./../favicon.ico" />
<script src="http://www.google.com/jsapi" type="text/javascript"></script>
<script type="text/javascript">
var path = './../';
var class_prefix = "Config::";
</script>
<script src="./../assets/js/combined.js"></script>
<title>Config - Classes - FuelPHP Documentation</title>
</head>
<body>
<div id="container">
<header id="header">
<div class="table">
<h1>
<a href="http://fuelphp.com"><img height="37px" width="147px" src="./../assets/img/fuel.png" /></a>
<strong>Documentation</strong>
</h1>
<form id="google_search">
<p>
<span id="search_clear"> </span>
<input type="submit" name="search_submit" id="search_submit" value="search" />
<input type="text" value="" id="search_input" name="search_input" />
</p>
</form>
</div>
<nav>
<div class="clear"></div>
</nav>
<a href="#" id="toc_handle">table of contents</a>
<div class="clear"></div>
</header>
<div id="cse">
<div id="cse_point"></div>
<div id="cse_content"></div>
</div>
<div id="main">
<h2>Config Class</h2>
<p>The Config class handles nearly all configuration options in Fuel. You use this class whenever you need to load in a config file, get a value or set a value.</p>
<h3 id="config_groups">Config File Types</h3>
You can use different file layouts to store your configuration. The layout type is determined by the file extension:
<ul>
<li>
PHP. The default type. A PHP file should return an array structure.
<pre class="php"><code> return array('key' => 'value');</code></pre>
</li>
<li>
INI. See <a href="http://en.wikipedia.org/wiki/INI_file">this page</a> for a definition of the ini-file layout.
<pre class="ini"><code> [group]
key=value</code></pre>
</li>
<li>
YAML. See <a href="http://en.wikipedia.org/wiki/YAML">this page</a> for a definition of the yaml-file layout.
<pre class="yaml"><code> group:
key: value</code></pre>
</li>
<li>
JSON. See <a href="http://en.wikipedia.org/wiki/JSON">this page</a> for a definition of the json-file layout.
<pre class="javascript"><code> {
"group" :
{
"key": "value"
}
}</code></pre>
</li>
<li>
MEMCACHED. Stores or retrieves the config from a Memcached or Memcachedb store.
<br /><br />
It will use the <strong>config.memcached</strong> section of the <code>app/config/config.php</code> configuration
file to configure the memcached class used to connect to the store.
<br /><br />
</li>
<li>
DB. Use the following table structure:
<pre class="php"><code> CREATE TABLE IF NOT EXISTS `config` (
`identifier` char(100) NOT NULL,
`config` longtext NOT NULL,
`hash` char(13) NOT NULL,
PRIMARY KEY (`identifier`)
)</code></pre>
By default it will use the table name 'config', in the default database. You can override this by defining your
database and table name in <code>app/config/config.php</code>, using the <strong>config.database</strong>
and <strong>config.table_name</strong> key.
</li>
</ul>
<p>If you don't specify a file type, Config::load() will default to the 'php' type.</p>
<p class="note">
If you have more complex configuration values, you can opt to define them as a closure. By default, the closure is returned when you <kbd>get()</kbd> the config
key, and evaluated at runtime, either by you calling it as a function, or wrapping it into <kbd>Fuel::value()</kbd> to get the closures result.
If you don't want this behavior, but cache and re-use the result (for example because your closure always returns the same result), you have to wrap the
closure into <kbd>Fuel::value()</kbd> in your config file where you define the closure.
<br /><br />
The same is true if you want to pass a closure to the <kbd>set()</kbd> method. If you want to store the closures result and not the closure itself, you have
to wrap the closure into <kbd>Fuel::value()</kbd> when passing it to the <kbd>set()</kbd> method.
<br /><br />
Note that you can only define closures in config files of type "php".
</p>
<h3 id="config_groups">Config Groups</h3>
<p>A config group is simply a way to scope config options. This avoids naming collisions. All config files (db.php, routes.php, etc.) are loaded into groups of the same name, with the exception of the main <kbd>config.php</kbd> file.</p>
<h3 id="config_methods">Methods</h3>
<article>
<h4 class="method" id="method_get">get($item, $default = null)</h4>
<p>The <strong>get</strong> method returns the desired config item. If the item does not exist then <kbd>$default</kbd> is returned. If the item you are retrieving is a group, then the entire group is returned.</p>
<table class="method">
<tbody>
<tr>
<th class="legend">Static</th>
<td>Yes</td>
</tr>
<tr>
<th>Parameters</th>
<td>
<table class="parameters">
<tr>
<th>Param</th>
<th>Default</th>
<th class="description">Description</th>
</tr>
<tr>
<th><kbd>$item</kbd></th>
<td><i>required</i></td>
<td>The name of the item to retrieve. Groups and multi-dimensional arrays can be accessed by separating the levels by a dot (<kbd>.</kbd>)</td>
</tr>
<tr>
<th><kbd>$default</kbd></th>
<td><kbd>null</kbd></td>
<td>(Optional) The default value to return if <kbd>$item</kbd> is not found.</td>
</tr>
</table>
</td>
</tr>
<tr>
<th>Returns</th>
<td>Either <kbd>$item</kbd>, or <kbd>$default</kbd> if <kbd>$item</kbd> does not exist. If <kbd>$item</kbd> is a group than an <kbd>array</kbd> containing the entire group.</td>
</tr>
<tr>
<th>Example</th>
<td>
<pre class="php"><code>// Outputs the current language set in config.php
echo Config::get('language');
// By default a non-existent item will return null
if (Config::get('items_to_display') === null)
{
throw new Exception('You must set the number of items to display in config.php');
}
// You can set a default for non-existent items as well
$items_to_display = Config::get('items_to_display', 10);
// This will load in the entire db group, which is the contents of config/db.php
$db_configs = Config::get('db');
// This will get which db connection is set to 'active' in the db config
$active_db = Config::get('db.active');
// You can go multiple levels deep as well.
// This will fetch the hostname of the 'dev' db group
$dev_host = Config::get('db.dev.connection.hostname');</code></pre>
</td>
</tr>
</tbody>
</table>
</article>
<article>
<h4 class="method" id="method_set">set($item, $value)</h4>
<p>The <strong>set</strong> method Sets a given <kbd>$item</kbd> to <kbd>$value</kbd>. <kbd>$item</kbd> can be dot (<kbd>.</kbd>) separated, just like <kbd>get()</kbd>.</p>
<table class="method">
<tbody>
<tr>
<th class="legend">Static</th>
<td>Yes</td>
</tr>
<tr>
<th>Parameters</th>
<td>
<table class="parameters">
<tr>
<th>Param</th>
<th>Default</th>
<th class="description">Description</th>
</tr>
<tr>
<th><kbd>$item</kbd></th>
<td><i>required</i></td>
<td>The name of the item to set. Groups and multi-dimensional arrays can be set by separating the levels by a dot (<kbd>.</kbd>). If <kbd>$item</kbd> does not exist it will be created.</td>
</tr>
<tr>
<th><kbd>$value</kbd></th>
<td><i>required</i></td>
<td>The value to set <kbd>$item</kbd> to.</td>
</tr>
</table>
</td>
</tr>
<tr>
<th>Returns</th>
<td>This method always returns <kbd>true</kbd>.</td>
</tr>
<tr>
<th>Example</th>
<td>
<pre class="php"><code>// Sets the current language
Config::set('language', 'en');
// Sets the active db connection
Config::set('db.active', 'test');
// This sets a custom value that you can use later
Config::set('items_to_display', 5);
// You can also use dots to create custom groups and items
Config::set('blog.items_to_display', 5);</code></pre>
</td>
</tr>
</tbody>
</table>
</article>
<article>
<h4 class="method" id="method_delete">delete($item)</h4>
<p>The <strong>delete</strong> method removes a given <kbd>$item</kbd>. <kbd>$item</kbd> can be dot (<kbd>.</kbd>) separated, just like <kbd>set()</kbd> and <kbd>get()</kbd> .</p>
<table class="method">
<tbody>
<tr>
<th class="legend">Static</th>
<td>Yes</td>
</tr>
<tr>
<th>Parameters</th>
<td>
<table class="parameters">
<tr>
<th>Param</th>
<th>Default</th>
<th class="description">Description</th>
</tr>
<tr>
<th><kbd>$item</kbd></th>
<td><i>required</i></td>
<td>The name of the item to delete.</td>
</tr>
</table>
</td>
</tr>
<tr>
<th>Returns</th>
<td>void</td>
</tr>
<tr>
<th>Example</th>
<td>
<pre class="php"><code>// Remove a configuration item using dot notation
Config::delete('blog.items_to_display');</code></pre>
</td>
</tr>
</tbody>
</table>
</article>
<article>
<h4 class="method" id="method_load">load($file, $group = null, $reload = false, $overwrite = false)</h4>
<p>The <strong>load</strong> method reads in a config file into the system. It searches through the config directories for the requested file. You can optionally group the config files to avoid naming collisions.</p>
<table class="method">
<tbody>
<tr>
<th class="legend">Static</th>
<td>Yes</td>
</tr>
<tr>
<th>Parameters</th>
<td>
<table class="parameters">
<tr>
<th>Param</th>
<th>Default</th>
<th class="description">Description</th>
</tr>
<tr>
<th><kbd>$file</kbd></th>
<td><i>required</i></td>
<td>The path to the config file, relative to the config directory. Do not include the file extension (".php" is assumed). You can prefix this with a module name to force loading a config file from a loaded module.</td>
</tr>
<tr>
<th><kbd>$group</kbd></th>
<td><kbd>null</kbd></td>
<td>(Optional) A group name to use. If set to <kbd>true</kbd> then a group of the same name as <kbd>$file</kbd> will be created. If this is not set or is <kbd>null</kbd> then the loaded config will be merged with the root config.</td>
</tr>
<tr>
<th><kbd>$reload</kbd></th>
<td><kbd>false</kbd></td>
<td>(Optional) If set to <kbd>true</kbd> a reload of the requested configuration is forced, erasing cached configuration items related to the config file to be loaded.</td>
</tr>
<tr>
<th><kbd>$overwrite</kbd></th>
<td><kbd>false</kbd></td>
<td>(Optional) If set to <kbd>true</kbd> the loaded configuration items will be merged with the items already loaded in a non-recursive manner, with will overwrite array values in a multidimensional array, rather then merging them.</td>
</tr>
</table>
</td>
</tr>
<tr>
<th>Returns</th>
<td>An <kbd>array</kbd> containing the configuration that has been loaded. If the config file has already been loaded then it will return <kbd>false</kbd></td>
</tr>
<tr>
<th>Example</th>
<td>
<pre class="php"><code>// This merges the "custom" config file in with the root config.
Config::load('custom');
// This loads the "custom" config file in a group named "custom".
Config::load('custom', true);
// This loads the "custom.ini" config file in a group named "custom".
Config::load('custom.ini', true);
// This loads the "custom" config file in a group named "foo".
Config::load('custom', 'foo');
// This loads the "custom" config from a module called foo in a group named "bar"
Config::load('foo::custom', 'bar');</code></pre>
</td>
</tr>
</tbody>
</table>
</article>
<article>
<h4 class="method" id="method_save">save($file, $config)</h4>
<p>The <strong>save</strong> method saves a config file into the system. It searches through the config directories for the requested file. If no existing file is found, the config file is created in the APPPATH config directory.</p>
<table class="method">
<tbody>
<tr>
<th class="legend">Static</th>
<td>Yes</td>
</tr>
<tr>
<th>Parameters</th>
<td>
<table class="parameters">
<tr>
<th>Param</th>
<th>Default</th>
<th class="description">Description</th>
</tr>
<tr>
<th><kbd>$file</kbd></th>
<td><i>required</i></td>
<td>The path to the config file, relative to the config directory. Do not include the file extension (".php" is assumed). You can prefix this with a namespace to load a config file from a loaded package or module.</td>
</tr>
<tr>
<th><kbd>$config</kbd></th>
<td><i>required</i></td>
<td>If this is a string, it specifies a group name to save. If it is an array, it is assumed to contain the configuration to be saved.</td>
</tr>
</table>
</td>
</tr>
<tr>
<th>Returns</th>
<td><kbd>true</kbd> if the config was saved, <kbd>false</kbd> if an error occurred</td>
</tr>
<tr>
<th>Example</th>
<td>
<pre class="php"><code>// This loads the "custom" config file in a group named "foo".
Config::load('custom', 'foo');
// update some config item
Config::set('foo.key', $value);
// save the updated config group 'foo' (note: it will save everything in that group!)
Config::save('custom', 'foo');
// save the updated config group 'bar' to config file 'custom' in the module 'foo'
Config::save('foo::custom', 'bar');
// save the updated config group 'bar' to memcached using the identifier 'custom'
Config::save('custom.memcached', 'bar');</code></pre>
</td>
</tr>
</tbody>
</table>
</article>
</div>
<footer>
<p>
© FuelPHP Development Team 2010-2016 - <a href="http://fuelphp.com">FuelPHP</a> is released under the MIT license.
</p>
</footer>
</div>
</body>
</html>