Blame view

site/jpgraph/docs/chunkhtml/ch03s03.html 36.8 KB
d72ac078   Guillaume   Ajout graphe V1.1
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
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
  <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing the library</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch03.html" title="Chapter 3. The Long Version: Installing the Library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Installing the library</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 3. The Long Version: Installing the Library</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Installing the library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec1.installing-library"></a>Installing the library</h2></div></div></div>
              
              <p>When you have verified the necessary preconditions as described in the previous
                  paragraphs it is time to install the library. The "installing" part is nothing more
                  than copying the files in the distribution to a place in the directory structure
                  where you script can find the library files. On a Unix system it is common to
                  install PHP libraries under "<code class="filename">/usr/share/php/</code>". On a windows
                  system there is really no standard path for installing PHP libraries so you have to
                  decide your self. </p>
              <p>The important thing here is that the path to the library is included in the PHP
                  search path, i.e. it is in one of the paths that PHP searches when it tries to
                  resolve a "<code class="code">require_once</code>" or "<code class="code">include</code>" statements.
                  Furthermore, the included examples and demo applications (included in the pro
                  version) assumes that the library is installed under the directory
                      "<code class="filename">jpgraph/</code>".</p>
              <p>As an example the following commands will install a specific version of the
                  library on a Unix server. If we assume that you have downloaded the library to the
                      "<code class="filename">/tmp/</code>" directory and are already standing in this
                  directory the following commands will setup the library to be used</p>
              <p>
                  </p><pre class="screen">root:/tmp&gt; tar xzf jpgraph-2.5.tar.gz
  root:/tmp&gt; cp -r jpgraph-2.5 /usr/shar/php/
  root:/tmp&gt; ln -s /usr/shar/php/jpgraph-2.5 /usr/shar/php/jpgraph</pre><p>
              </p>
              <p>The last line makes a symbolic link from "jpgraph" to the actual version of the
                  library. This way you can try out different versions of the library without having
                  to make any changes in your scripts. You just point out a different version of the
                  library in the symbolic link.</p>
              <div class="sect2" title="Configuring JpGraph/PHP on a development server"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.config-dev-server"></a>Configuring JpGraph/PHP on a development server</h3></div></div></div>
                  
                  <div class="sect3" title="Setting up your php.ini file"><div class="titlepage"><div><div><h4 class="title"><a name="sec3.setting-up-php-ini"></a>Setting up your php.ini file</h4></div></div></div>
                      
                      <p>
                          </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
                              <p>To find the location of your <code class="filename">php.ini</code> file
                                  create and run a script with the single line <code class="code">&lt;?php
                                      phpinfo(); ?&gt;</code> . The look at the output for a line saying
                                  "php.ini file used" and you will see which
                                      <code class="filename">php.ini</code> file is used.</p>
                          </div><p>
                      </p>
                      <p><span class="bold"><strong>Setting the memory limits</strong></span></p>
                      <p>In many default configuration the allowed memory for PHP is not enough for
                          complex graph script since they (as many other image manipulation programs)
                          can require a lot of memory. On a development server there should be at
                          least 32MB memory allowed for the HTTP/PHP process. To verify this do the
                          following</p>
                      <p>
                          </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
                                  <p>Open <code class="filename">php.ini</code> for editing.</p>
                              </li><li class="listitem">
                                  <p>Locate the line saying</p>
                                  <p><code class="code">memory_limit = xx</code></p>
                                  <p>where "xx" is some number. Now make sure that you have at
                                      least 32MB allowed by making sure the line reads</p>
                                  <p><code class="code">memory_limit = 32M</code></p>
                                  <p>Note that fore very large images this might not be enough.
                                      Consider the following example.</p>
                                  <p>Assume you need to create an 1200x1024 image in true color.
                                      Just the plain image in itself will require 1200x1020x4 bytes,
                                      which is roughly 4.7MB RAM during internal processing the
                                      library can need up to three times that amount of memory so this
                                      means that just for the image the library needs around of ~15MB
                                      of RAM. If we then take the memory needed to load PHP as well as
                                      the entire JpGraph library and dynamically execute and parse the
                                      library it can easily consume another ~15MB RAM. If the image is
                                      very complex and requires a huge number of objects to be created
                                      (a typical example is a large Gantt chart) it might be necessary
                                      to double the allowed memory to 64MB RAM. </p>
                              </li></ol></div><p>
                      </p>
                      <p></p>
                      <p><span class="bold"><strong>Setting maximum allowed run time</strong></span></p>
                      <p>By default many installations have very short maximum run time for the PHP
                          scripts. Common figures are 10s. For normal interactive use involving plain
                          text processing this is usually adequate. However, producing large and
                          complex images might take considerable time (as do all images processing).
                          For this reason the maximum time limit for PHP should be increased to a
                          minimum of 20s (depending on the complexity of your images as well as any
                          associated data processing it might be necessary to allow up to
                          30-40s).</p>
                      <p>The allowed running time is controlled by the <code class="filename">php.ini</code>
                          setting</p>
                      <p><code class="code">max_execution_time = xx</code></p>
                      <p>where "xx" is some number. Recommended setting is therefore </p>
                      <p><code class="code">max_execution_time = 30</code></p>
                      <p></p>
                      <p><span class="bold"><strong>Disabling output buffer</strong></span></p>
                      <p>The next part of the <code class="filename">php.ini</code> file that might need
                          changing is the output buffer. In short this should be disabled and we will
                          shortly explain why. To check this do the following</p>
                      <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
                                  <p>Open <code class="filename">php.ini</code> for editing</p>
                              </li><li class="listitem">
                                  <p>Locate the line saying </p>
                                  <p><code class="code">output_buffering = xx</code></p>
                                  <p>where "xx" is some number. Make sure that this line is
                                      commented out, i.e. it reads</p>
                                  <p><code class="code">; output_buffering = xx</code></p>
                              </li></ol></div><p>This reason we want this to be commented out is that during
                          development we want to be able to see the potential error messages produced
                          by the library and having the output buffering enabled will actually prevent
                          this. Fully understanding why this is the case is good first step into the
                          added complexity of producing images with PHP compared with just outputting
                          text. Understanding this requires us to understand a few basic principles
                          about the HTTP protocol. Especially how MIME encodings of data works.</p>
                      <p>The following explanation is slightly simplified since a full description
                          of the HTTP protocol would bring us a bit to far in this manual</p>
                      <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
                                  <p>A client (e.g. browser) requests data from the server by
                                      issuing a GET (or possible a POST) command to the server. This
                                      is what happens when you enter a URI i the address bar in the
                                      browser.</p>
                              </li><li class="listitem">
                                  <p>The server replies with a data stream (or an error if the
                                      requested data wasn't available). This data stream is prepended
                                      with header (MIME header) that tells the client (e.g. the
                                      browser) how to interpret the data that follows. The most common
                                      type (and the default type if no header is sent by a faulty
                                      server) is "text/html" . This tells the client to interpret the
                                      data as plain text with embedded HTML encoding. </p>
                                  <p>When the data is to be interpreted as an image the header will
                                      instead be one of the image headers, for example
                                          <code class="code">"image/png"</code> or <code class="code">"image/jpeg"</code>. When
                                      the client receives this header it will Interpret all the
                                      following data as an image encoded in the indicated format. </p>
                                  <p>The important thing to keep in mind here is that each server
                                      reply can have one and only one MIME type. This is the key to
                                      further understanding the specific issues with dynamic image
                                      generation. This explains why if a PHP script running on the
                                      server sends a header first indicating that the following data
                                      it sends should be interpreted by the client as an image it
                                      cannot send both image data and some text.</p>
                              </li></ol></div><p>We are now in a position to explain how output buffering would
                          make debugging more difficult.</p>
                      <p>Normally all output from a PHP script is sequentially, i.e. the header
                          must first be sent and then the data. If no header is sent or plain text is
                          sent without a header the client will interpret this as
                              <code class="code">"text/html"</code>. One purpose with "output_buffer" it to
                          circumvent this to allow a certain amount of output to be put in a buffer
                          for a while and later when some processing has determined what header should
                          be sent the data is prepended with the correct header and the rest of the
                          data is then sent. </p>
                      <p>What could now happen is the following (not unlikely scenario): </p>
                      <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
                                  <p>The scripts starts executing and the image starts to be
                                      build.</p>
                              </li><li class="listitem">
                                  <p>Your script has some minor issues which produces some warnings
                                      from PHP. These warning does not get sent directly back to the
                                      client (the browser) to allow you to act on these warnings
                                      instead they will be put into the output buffer. When later the
                                      scripts starts outputting the proper image header and the image
                                      data it gets added to the output buffer where your previous
                                      textual PHP warning already are stored. </p>
                              </li><li class="listitem">
                                  <p>Your client now receives the header that indicates that the
                                      following data should be interpreted as an image but since that
                                      image data is mixed with the textual warning messages it will
                                      fail to decode the data (since it is not proper image data) and
                                      will typical just show the image as a square with a red-cross
                                      (FireFox) or some message along the lines of "<span class="italic">Cannot decode image</span>". This is all
                                      depending on how a certain client handles a corrupt
                                      image.</p>
                              </li></ol></div><p>The above scenario makes it impossible to debug your script
                          since it will give no clue to what caused or where in your script these
                          warnings were generated. The way to counteract this scenario is to disable
                          output buffering. In this way the warning will be sent back to the client as
                          soon as they are generated by PHP and will allow you to act on them. </p>
                      <p></p>
                      <p><span class="bold"><strong>Enabling adequate error checking</strong></span></p>
                      <p>The final part of the <code class="filename">php.ini</code> file that should be
                          adjusted (and this is not only for the JpGraph library) is the error level.
                          To ensure maximum interoperability of the developed scripts they should all
                          run completely silent no matter what error levels are set on the server.
                          This means that development of all scripts should always be done with
                          maximum error checking enabled. The JpGraph library can safely run
                          completely silent even when all error checking is enabled.</p>
                      <p>The error checking should therefore be specified as</p>
                      <p><code class="code">error_reporting = E_ALL | E_STRICT</code></p>
                      <p>to enable the highest degree of PHP error checking</p>
                      <p></p>
                      <p>
                          </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
                              <p>In addition to the above setting it is a good idea to also to
                                  makes sure that the following options are set</p>
                              <p><code class="code">zend.ze1_compatibility_mode = Off</code></p>
                              <p>Zend engine 1 compatibility might cause problems with the
                                  library</p>
                              <p><code class="code">implicit_flush = On</code></p>
                              <p>This can reduce the performance and shouldn't be used on a
                                  production server but will make all outputs sent back to the client
                                  as soon as possible and will aid in debugging.</p>
                              <p><code class="code">allow_call_time_pass_reference = Off</code></p>
                              <p>This is just a general good idea since call time pass references
                                  is deprecated in PHP 5.0 and higher</p>
                              <p><code class="code">display_errors = On</code></p>
                              <p>This makes sure all error are displayed</p>
                              <p><code class="code">display_startup_errors = On</code></p>
                              <p>This makes sure that any initial errors thrown by PHP will be
                                  reported</p>
                          </div><p>
                      </p>
                      <p><span class="bold"><strong>Setting default timezone</strong></span></p>
                      <p>Starting with PHP 5.2 a warning will now be generated unless a default
                          time zone is explicitly specified in <code class="filename">php.ini</code>. To set
                          this find the line <code class="code">date.timezone</code> in the
                          <code class="code">[Date]</code>section and set this to valid zone. For example to
                          specify GMT+1 one could specify</p>
                      <p><code class="code">date.timezone = Europe/Paris</code></p>
                      <p>Note: There should be no citation signs around the time zone.</p>
                      <p>
                          </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
                              <p>In order to use the LED module (See <a class="xref" href="ch17.html#sec.led-graph-type" title="LED bill boards">LED bill boards</a>) the PHP installation must
                                  have multi-byte strings enabled so that the function
                                      <span class="command"><strong>mb_strlen()</strong></span> is available. This is normally
                                  enabled at compile time for PHP by specifying the options
                                      <code class="code">--enable-mbstring --enable-mbregex</code> when configuring
                                  the compile options.</p>
                          </div><p>
                      </p>
                      <p>
                          </p><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
                              <p>In order to use the PDF417 barcode module (See <a class="xref" href="ch25.html" title="Chapter 25. PDF417 (2D-Barcode)">Chapter 25. <i>PDF417 (2D-Barcode)</i></a>) it is necessary for the PHP
                                  installation to support the function <span class="command"><strong>bcmod()</strong></span>.
                                  This is enabled when compiling PHP by making sure that the option
                                      <code class="code">--enable-bcmath</code> is given when configuring PHP at
                                  compile time.</p>
                          </div><p>
                      </p>
                  </div>
                  <div class="sect3" title="Setting up your jpg-config.inc.php"><div class="titlepage"><div><div><h4 class="title"><a name="id2491276"></a>Setting up your jpg-config.inc.php</h4></div></div></div>
                      
                      <p>Apart from the standard configuration described in <a class="xref" href="ch03s04.html" title="Installing and configuring Font support">Installing and configuring Font support</a> and <a class="xref" href="ch03s05.html" title="Adapting and customizing the installation">Adapting and customizing the installation</a> there is only one important
                          configuration that is specific for a development server and that is the
                          localization setting for error messages. </p>
                      <p>As of version 3.0.0 there are three localization options</p>
                      <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
                                  <p>English error messages ("en")</p>
                              </li><li class="listitem">
                                  <p>German error messages ("de")</p>
                              </li><li class="listitem">
                                  <p>Production error messages ("prod"). This is not really a
                                      localization but a different set of error messages which does
                                      not give detailed error messages but a generic message suitable
                                      for a production server where the end user is not helped by
                                      detailed graph script errors. Instead a generic message is shown
                                      together with an error code that corresponds to the detailed
                                      error. ("prod")</p>
                              </li></ol></div><p>In order to specify the error message localization the
                          following define in <code class="filename">jpg-config.inc.php</code> must be set the </p>
                      <p><code class="code">define('DEFAULT_ERR_LOCALE','en');</code></p>
                      <p>The possible options are</p>
                      <p>
                          </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
                                  <p>"en", English locale</p>
                              </li><li class="listitem">
                                  <p>"de", German locale</p>
                              </li><li class="listitem">
                                  <p>"prod", The production version of the error messages.</p>
                              </li></ol></div><p>
                      </p>
                      <p>
                          </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
                              <p>In addition to specifying the locale in the
                                      <code class="filename">jpg-config.inc.php</code> file it can also be
                                  specified dynamically in each script by calling</p>
                              <p>
                                  </p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
  </pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">JpGraphError::SetErrLocale($aLocale);</span></pre></td></tr></table></div><p>
                              </p>
                          </div><p>
                      </p>
                  </div>
              </div>
              <div class="sect2" title="Configuring JpGraph/PHP on a production server"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.config-prod-server"></a>Configuring JpGraph/PHP on a production server</h3></div></div></div>
                  
                  <div class="sect3" title="Setting up your php.ini file"><div class="titlepage"><div><div><h4 class="title"><a name="id2491419"></a>Setting up your php.ini file</h4></div></div></div>
                      
                      <p>Apart from what is applicable to a development server as described in <a class="xref" href="ch03s03.html#sec2.config-dev-server" title="Configuring JpGraph/PHP on a development server">Configuring JpGraph/PHP on a development server</a> the following changes should be
                          considered in a production environment.</p>
                      <p>
                          <span class="bold"><strong>Setting the memory limits</strong></span>
                      </p>
                      <p>The one thing to keep in mind here is that each active connection will
                          spawn a unique PHP instance (HTTP process). This means that the memory limit
                          set per PHP process can cause a very high memory demand on a busy server
                          with many simultaneous connections. For this reason it is important that
                          during system test (before going into production) the actual needed memory
                          limit is determined. </p>
                      <p>For a busy server it is not uncommon to dimension it so it can handle 100
                          simultaneous connections. If the limit of r each PHP process is set to 32MB
                          this means that the server needs at least ~3.2GB memory just to handle the
                          PHP processes (if they are all using there maximum allowed memory).</p>
                      <p>
                          <span class="bold"><strong>Setting maximum allowed run time</strong></span>
                      </p>
                      <p>The same principle applies to a the allowed run time. For a production
                          server with high load and many simultaneous users it might be necessary to
                          increase the maximum allowed execution time just to be sure no process is
                          terminated due to it reaching its maximum allowed run time. When that
                          happens the PHP process will be killed an no output sent back to the client
                          (e.g. the browser).</p>
                      <p>
                          <span class="bold"><strong>Disabling output buffer</strong></span>
                      </p>
                      <p>The output buffer should be disabled on the production server as well
                          since enabling this will slow down the PHP and put a higher demand on the
                          memory requirements.</p>
                      <p>
                          <span class="bold"><strong>Enabling adequate error checking</strong></span>
                      </p>
                      <p>On a production server it is not a good idea to display all PHP error
                          messages to the end user so the display of error messages should be disabled
                          and the error messages should only be logged to a file.</p>
                      <div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
                          <p> On a production server it is also a good to idea to have the
                              following settings: </p>
                          <p>
                              <code class="code">display_errors = Off</code>
                          </p>
                          <p>This makes sure that now PHP errors are displayed</p>
                          <p>
                              <code class="code">display_startup_errors = Off</code>
                          </p>
                          <p>This makes sure that any initial errors thrown by PHP is not displayed
                              to the end user</p>
                          <p><code class="code">log_errors = On</code></p>
                          <p><code class="code">error_log = &lt;name-of-log-file&gt;</code></p>
                          <p>This makes sure all server PHP errors are logged to a specified
                              file</p>
                      </div>
                  </div>
                  <div class="sect3" title="Setting up your jpg-config.inc.php"><div class="titlepage"><div><div><h4 class="title"><a name="id2491421"></a>Setting up your <code class="filename">jpg-config.inc.php</code></h4></div></div></div>
                      
                      <p>On a production server it is best not to show detailed error messages to
                          an end user. Instead it is better to have a generic error message that
                          indicates a server problem and give an error code which can be decoded by
                          looking it up in the table in <a class="xref" href="aph.html" title="Appendix H. Error messages">Appendix H. <i>Error messages</i></a> Using a generic error message is achieved by
                          setting the following define:</p>
                      <p><code class="code">define('DEFAULT_ERR_LOCALE','prod');</code></p>
                  </div>
              </div>
              <div class="sect2" title="Adjusting PHP include path"><div class="titlepage"><div><div><h3 class="title"><a name="sec2.adjusting-php-include-path"></a>Adjusting PHP include path</h3></div></div></div>
                  
                  <p>As was mentioned before the library should be installed somewhere in the PHP
                      include path. There are two ways of configuring the include path:</p>
                  <p>
                      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
                              <p>setting the include path in <code class="filename">php.ini</code></p>
                              <p><code class="code">include_path = &lt;file-path&gt;</code></p>
                          </li><li class="listitem">
                              <p>adjusting the include path directly in the code by using the PHP
                                  command <code class="code">php_ini_set()</code> at the top of the script</p>
                          </li></ol></div><p>
                  </p>
                  <p>The library examples assume that the library is available under a directory
                      called "<code class="filename">jpgraph/</code>" . This will allow the scripts to include
                      the library files by, for example, writing "<code class="code">include</code>" or
                          "<code class="code">require_once</code>" statements such as </p>
                  <p><code class="code">require_once( 'jpgraph/jpgraph.php')</code></p>
              </div>
              <div class="sect2" title="Using Apache2 alias configuration during development"><div class="titlepage"><div><div><h3 class="title"><a name="id2491659"></a>Using Apache2 alias configuration during development</h3></div></div></div>
                  
                  <p>
                      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
                          <p>This section only discusses alias setting using the Apache HTTP server
                              so this section can be skipped at first time reading the manual without
                              loss of continuation.</p>
                      </div><p>
                      </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
                          <p>More detailed information on the alias directive is also available in
                              the official Apache documentation at <code class="uri"><a class="uri" href="http://httpd.apache.org/docs/2.2/mod/mod_alias.html#alias" target="_top">http://httpd.apache.org/docs/2.2/mod/mod_alias.html</a></code></p>
                      </div><p>
                  </p>
                  <p>When accessing examples and test code through a regular bowser during
                      development the scripts must be available in document root (or somewhere beneath
                      that root) the root is traditionally named <code class="code">/htdocs</code>. Having a
                      development code/repository directly under this root directory is not a good
                      idea. For example, write access to a document root (even on a development
                      server) should be restricted, in addition the paths given to a test team should
                      be the same whatever version is currently under test so storing different
                      versions with different names under the root is also a poor setup.</p>
                  <p>A much better and easy, approach is to use the powerful concept of alias in
                      Apache. This is a way of mapping a URL to a specific directory on the server.
                      For example if <code class="uri"><a class="uri" href="http://www.eclipse.org/projects/project-plan.php?projectid=tools.pdt" target="_top">Eclipse-PDT</a></code>
                      is used as an IDE to develop PHP it is mandatory to have a workspace setup where
                      all the working files resides. Assuming that a local developer has his workspace
                      directly in his home directory, say <code class="filename">~joe/workspace</code>, we
                      could configure an alias so that the workspace is accessible by the alias
                          "<code class="filename">http://localhost/ws/</code>" by adding the following
                      configuration in the Apache setup file(s)</p>
                  <div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
  2
  3
  4
  5
  </pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">Alias /ws /home/joe/worksapce
  &lt;Directory /home/joe/workspace&gt;
    Order allow,deny
    Allow from all
  &lt;/Directory&gt;</span></pre></td></tr></table></div>
                  <p>In this particular setup we use very liberal settings, allowing basically
                      everyone with server access to access the directory. Using this approach makes
                      it very easy to use the same test setup but allow testing of different
                      branches/versions of the code.</p>
                  <p>Depending on the system these configurations can reside in different places.
                      However, a very common structure is to keep all these small configuration files
                      under <code class="filename">/etc/apache/conf.d/</code> The main Apache configuration
                      then reads all the files (regardless of there name) that are stored under this
                      directory. </p>
                  <p>As a final example we show a further slightly more complex example (which
                      actually shows how most of our developers have there systems setup for PHP5
                      development). This example adds options to do directory listing and allows the
                      server to follow symbolic links. More information on available argument for the
                      directive option is available in the official Apache documentation <code class="uri"><a class="uri" href="http://httpd.apache.org/docs/2.2/mod/core.html#options" target="_top">http://httpd.apache.org/docs/2.2/mod/core.html#options</a></code></p>
                  <p>
                      </p><div class="example"><a name="id2491770"></a><p class="title"><b>Example 3.5. Alias configuration for a development server running Apache with
                              Eclipse-PDT</b></p><div class="example-contents">
                          
                          <div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  </pre></td><td class="hl-main" valign="top"><pre><span class="hl-code"># Configuration for Eclipse workspace
  #
  &lt;IfModule mod_php5.c&gt;
        Alias /ws/ /home/joe/workspace/
        &lt;Directory /home/joe/workspace/&gt;
               Options         +Indexes +Multiviews +FollowSymLinks
               order allow,deny
               allow from all
        &lt;/Directory&gt;
  &lt;/IfModule&gt;</span></pre></td></tr></table></div>
                      </div></div><p><br class="example-break">
                  </p>
              </div>
          </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>