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
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.config.writer.introduction">
<title>Zend_Config_Writer</title>
<para>
<classname>Zend_Config_Writer</classname> gives you the ability to write config
files out of <classname>Zend_Config</classname> objects. It works with an
adapter-less system and thus is very easy to use. By default
<classname>Zend_Config_Writer</classname> ships with four adapters, which are all
file-based. You instantiate a writer with specific options, which
can be <emphasis>filename</emphasis> and <emphasis>config</emphasis>. Then
you call the <methodname>write()</methodname> method of the writer and the config
file is created. You can also give <varname>$filename</varname> and
<varname>$config</varname> directly to the <methodname>write()</methodname> method.
Currently the following writers are shipped with
<classname>Zend_Config_Writer</classname>:
</para>
<itemizedlist>
<listitem>
<para>
<classname>Zend_Config_Writer_Array</classname>
</para>
</listitem>
<listitem>
<para>
<classname>Zend_Config_Writer_Ini</classname>
</para>
</listitem>
<listitem>
<para>
<classname>Zend_Config_Writer_Json</classname>
</para>
</listitem>
<listitem>
<para>
<classname>Zend_Config_Writer_Xml</classname>
</para>
</listitem>
<listitem>
<para>
<classname>Zend_Config_Writer_Yaml</classname>
</para>
</listitem>
</itemizedlist>
<para>
When modifying or creating a <classname>Zend_Config</classname> object, there are
some things to know. To create or modify a value, you simply say set
the parameter of the <classname>Zend_Config</classname> object via the parameter
accessor (<emphasis>-></emphasis>). To create a section in the root or to
create a branch, you just create a new array
("<command>$config->branch = array();</command>"). To define which section
extends another one, you call the <methodname>setExtend()</methodname> method
on the root <classname>Zend_Config</classname> object.
</para>
<example id="zend.config.writer.example.using">
<title>Using Zend_Config_Writer</title>
<para>
This example illustrates the basic use of
<classname>Zend_Config_Writer_Xml</classname> to create a new config file:
</para>
<programlisting language="php"><![CDATA[
// Create the config object
$config = new Zend_Config(array(), true);
$config->production = array();
$config->staging = array();
$config->setExtend('staging', 'production');
$config->production->db = array();
$config->production->db->hostname = 'localhost';
$config->production->db->username = 'production';
$config->staging->db = array();
$config->staging->db->username = 'staging';
// Write the config file in one of the following ways:
// a)
$writer = new Zend_Config_Writer_Xml(array('config' => $config,
'filename' => 'config.xml'));
$writer->write();
// b)
$writer = new Zend_Config_Writer_Xml();
$writer->setConfig($config)
->setFilename('config.xml')
->write();
// c)
$writer = new Zend_Config_Writer_Xml();
$writer->write('config.xml', $config);
]]></programlisting>
<para>
This will create an <acronym>XML</acronym> config file with the sections production
and staging, where staging extends production.
</para>
</example>
<example id="zend.config.writer.modifying">
<title>Modifying an Existing Config</title>
<para>
This example demonstrates how to edit an existing config file.
</para>
<programlisting language="php"><![CDATA[
// Load all sections from an existing config file, while skipping the extends.
$config = new Zend_Config_Ini('config.ini',
null,
array('skipExtends' => true,
'allowModifications' => true));
// Modify a value
$config->production->hostname = 'foobar';
// Write the config file
$writer = new Zend_Config_Writer_Ini(array('config' => $config,
'filename' => 'config.ini'));
$writer->write();
]]></programlisting>
</example>
<note>
<title>Loading a Config File</title>
<para>
When loading an existing config file for modifications it is very
important to load all sections and to skip the extends, so that
no values are merged. This is done by giving the
<emphasis>skipExtends</emphasis> as option to the constructor.
</para>
</note>
<para>
For all the File-Based writers (<acronym>INI</acronym>, <acronym>JSON</acronym>,
<acronym>XML</acronym>, <acronym>YAML</acronym>, and <acronym>PHP</acronym> Array)
internally the <methodname>render()</methodname> is used to build the configuration string.
This method can be used independently to access the string-representation of the
configuration data.
</para>
<sect2 id="zend.config.writer.introduction.ini-notes">
<title>Notes specific to the INI writer</title>
<itemizedlist>
<listitem>
<para>
The <acronym>INI</acronym> writer has two modes for rendering with regard to
sections. By default the top-level configuration is always written into section
names. By calling <command>$writer->setRenderWithoutSections();</command> all
options are written into the global namespace of the <acronym>INI</acronym> file
and no sections are applied.
</para>
</listitem>
<listitem>
<para>
<classname>Zend_Config_Writer_Ini</classname> has an additional option parameter
<emphasis>nestSeparator</emphasis>, which defines with which character the
single nodes are separated. The default is a single dot, which is accepted by
<classname>Zend_Config_Ini</classname> by default.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="zend.config.writer.introduction.yaml-notes">
<title>Notes specific to the YAML writer</title>
<para>
The <acronym>YAML</acronym> writer lets you optionally specify an alternate
<acronym>YAML</acronym> encoder to use. By default, one is shipped with the framework
that is suitable for most configuration tasks. If you find it insufficient, or wish to
use more advanced YAML, you may provide an alternate encoder callback.
</para>
<para>
The method for doing so is to use the
<methodname>Zend_Config_Writer_Yaml::setYamlEncoder()</methodname> method, passing it a
valid callback.
</para>
<programlisting language="php"><![CDATA[
// Use the Symfony Yaml Component:
$writer = new Zend_Config_Writer_Yaml($filename);
$writer->setYamlEncoder(array('sfYaml', 'dump'));
]]></programlisting>
<para>
The above uses the Symfony Components' <classname>sfYaml</classname> component in order
to encode the configuration to <acronym>YAML</acronym>.
</para>
</sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
|
