-
Notifications
You must be signed in to change notification settings - Fork 706
/
tutorial.xml
479 lines (466 loc) · 18.7 KB
/
tutorial.xml
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
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="tutorial" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info><title>A simple tutorial</title></info>
<para>
Here we would like to show the very basics of PHP in a short, simple
tutorial. This text only deals with dynamic web page creation with
PHP, though PHP is not only capable of creating web pages. See
the section titled <link linkend="intro-whatcando">What can PHP
do</link> for more information.
</para>
<para>
PHP-enabled web pages are treated just like regular HTML pages and
you can create and edit them the same way you normally create
regular HTML pages.
</para>
<section xml:id="tutorial.requirements">
<info><title>What do I need?</title></info>
<para>
In this tutorial we assume that your server has activated support
for PHP and that all files ending in <filename>.php</filename>
are handled by PHP. On most servers, this is the default extension
for PHP files, but ask your server administrator to be sure. If
your server supports PHP, then you do not need to do anything. Just
create your <filename>.php</filename> files, put them in your
web directory and the server will automatically parse them for you.
There is no need to compile anything nor do you need to install
any extra tools. Think of these PHP-enabled files as simple HTML
files with a whole new family of magical tags that let you do all
sorts of things.
</para>
<para>
Let us say you want to save precious bandwidth and develop locally.
In this case, you will want to install a web server, such as
<link xlink:href="&url.apache;">Apache</link>, and of course
<link xlink:href="&url.php.downloads;">PHP</link>. You will most likely
want to install a database as well, such as
<link xlink:href="&url.mysql.docs;">MySQL</link>.
</para>
<para>
You can either install these individually or choose a simpler way. Our
manual has <link linkend="install">installation instructions for
PHP</link> (assuming you already have some web server set up). If
you have problems with installing PHP yourself, we would suggest you ask
your questions on our <link xlink:href="&url.php.mailing-lists;">installation
mailing list</link>. If you choose to go on the simpler route, then
<link xlink:href="&url.installkits;">locate a pre-configured package</link>
for your operating system, which automatically installs all of these
with just a few mouse clicks. It is easy to setup a web server with PHP
support on any operating system, including MacOSX, Linux and Windows.
On Linux, you may find <link xlink:href="&url.rpmfind;">rpmfind</link> and
<link xlink:href="&url.rpmfind.pbone;">PBone</link> helpful for
locating RPMs. You may also want to visit <link
xlink:href="&url.apt-get;">apt-get</link> to find packages for Debian.
</para>
</section>
<section xml:id="tutorial.firstpage">
<info><title>Your first PHP-enabled page</title></info>
<para>
Create a file named <filename>hello.php</filename> and put it
in your web server's root directory (<varname>DOCUMENT_ROOT</varname>)
with the following content:
</para>
<para>
<example>
<info><title>Our first PHP script: <filename>hello.php</filename></title></info>
<programlisting role="php">
<![CDATA[
<!DOCTYPE html>
<html>
<head>
<title>PHP Test</title>
</head>
<body>
<?php echo '<p>Hello World</p>'; ?>
</body>
</html>
]]>
</programlisting>
<simpara>
Use your browser to access the file with your web server's URL, ending
with the <literal>/hello.php</literal> file reference. When developing locally this
URL will be something like <literal>http://localhost/hello.php</literal>
or <literal>http://127.0.0.1/hello.php</literal> but this depends on the
web server's configuration. If everything is configured correctly, this
file will be parsed by PHP and the following output will be sent to
your browser:
</simpara>
<screen role="html">
<![CDATA[
<!DOCTYPE html>
<html>
<head>
<title>PHP Test</title>
</head>
<body>
<p>Hello World</p>
</body>
</html>
]]>
</screen>
</example>
</para>
<para>
This program is extremely simple and you really did not need to use
PHP to create a page like this. All it does is display:
<literal>Hello World</literal> using the PHP <function>echo</function>
statement. Note that the file <emphasis>does not need to be executable</emphasis>
or special in any way. The server finds out that this file needs to be interpreted
by PHP because you used the ".php" extension, which the server is configured
to pass on to PHP. Think of this as a normal HTML file which happens to have
a set of special tags available to you that do a lot of interesting things.
</para>
<para>
If you tried this example and it did not output anything, it prompted
for download, or you see the whole file as text, chances are that the
server you are on does not have PHP enabled, or is not configured properly.
Ask your administrator to enable it for you using the
<link linkend="install">Installation</link> chapter
of the manual. If you are developing locally, also read the
installation chapter to make sure everything is configured
properly. Make sure that you access the file via http with the server
providing you the output. If you just call up the file from your file
system, then it will not be parsed by PHP. If the problems persist anyway,
do not hesitate to use one of the many
<link xlink:href="&url.php.support;">PHP support</link> options.
</para>
<para>
The point of the example is to show the special PHP tag format.
In this example we used <literal><?php</literal> to indicate the
start of a PHP tag. Then we put the PHP statement and left PHP mode by
adding the closing tag, <literal>?></literal>. You may jump in
and out of PHP mode in an HTML file like this anywhere you want. For more
details, read the manual section on the <link linkend="language.basic-syntax">
basic PHP syntax</link>.
</para>
<note>
<info><title>A Note on Line Feeds</title></info>
<para>
Line feeds have little meaning in HTML, however it is still a good idea
to make your HTML look nice and clean by putting line feeds in. A
linefeed that follows immediately after a closing
<literal>?></literal> will be removed by PHP. This can be extremely
useful when you are putting in many blocks of PHP or include files
containing PHP that aren't supposed to output anything. At the same time
it can be a bit confusing. You can put a space after the closing
<literal>?></literal> to force a space and a line feed to be output,
or you can put an explicit line feed in the last echo/print from within
your PHP block.
</para>
</note>
<note>
<info><title>A Note on Text Editors</title></info>
<para>
There are many text editors and Integrated Development Environments (IDEs)
that you can use to create, edit and manage PHP files. A partial list of
these tools is maintained at <link xlink:href="&url.phpeditorlist;">PHP Editors
List</link>. If you wish to recommend an editor, please visit the above
page and ask the page maintainer to add the editor to the list. Having
an editor with syntax highlighting can be helpful.
</para>
</note>
<note>
<info><title>A Note on Word Processors</title></info>
<para>
Word processors such as StarOffice Writer, Microsoft Word and Abiword are
not optimal for editing PHP files. If you wish to use one for this
test script, you must ensure that you save the file as <emphasis>plain
text</emphasis> or PHP will not be able to read and execute the script.
</para>
</note>
<para>
Now that you have successfully created a working PHP script, it is
time to create the most famous PHP script! Make a call to the
<function>phpinfo</function> function and you will see a lot of useful
information about your system and setup such as available
<link linkend="language.variables.predefined">predefined variables</link>,
loaded PHP modules, and <link linkend="configuration">configuration</link>
settings. Take some time and review this important information.
</para>
<para>
<example>
<info><title>Get system information from PHP</title></info>
<programlisting role="php">
<![CDATA[
<?php phpinfo(); ?>
]]>
</programlisting>
</example>
</para>
</section>
<section xml:id="tutorial.useful">
<info><title>Something Useful</title></info>
<para>
Let us do something more useful now. We are going to check
what sort of browser the visitor is using.
For that, we check the user agent string the browser
sends as part of the HTTP request. This information is stored in a <link
linkend="language.variables">variable</link>. Variables always start
with a dollar-sign in PHP. The variable we are interested in right now
is <varname>$_SERVER['HTTP_USER_AGENT']</varname>.
</para>
<note>
<para>
<varname>$_SERVER</varname> is a
special reserved PHP variable that contains all web server information.
It is known as a superglobal. See the related manual page on
<link linkend="language.variables.superglobals">superglobals</link>
for more information.
</para>
</note>
<para>
To display this variable, you can simply do:
</para>
<para>
<example>
<info><title>Printing a variable (Array element)</title></info>
<programlisting role="php">
<![CDATA[
<?php
echo $_SERVER['HTTP_USER_AGENT'];
?>
]]>
</programlisting>
<para>
A sample output of this script may be:
</para>
<screen role="html">
<![CDATA[
Mozilla/5.0 (Linux) Firefox/112.0
]]>
</screen>
</example>
</para>
<para>
There are many <link linkend="language.types">types</link> of
variables available in PHP. In the above example we printed an element
from an <link linkend="language.types.array">Array</link> variable.
Arrays can be very useful.
</para>
<para>
<varname>$_SERVER</varname> is just one variable that PHP automatically
makes available to you. A list can be seen in the
<link linkend="reserved.variables">Reserved Variables</link> section
of the manual or you can get a complete list of them by looking at
the output of the <function>phpinfo</function> function used in the
example in the previous section.
</para>
<para>
You can put multiple PHP statements inside a PHP tag and create
little blocks of code that do more than just a single echo.
For example, if you want to check for Firefox you
can do this:
</para>
<para>
<example>
<info><title>Example using <link linkend="language.control-structures">control
structures</link> and <link linkend="language.functions">functions</link></title></info>
<programlisting role="php">
<![CDATA[
<?php
if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
echo 'You are using Firefox.';
}
?>
]]>
</programlisting>
<para>
A sample output of this script may be:
</para>
<screen role="html">
<![CDATA[
You are using Firefox.
]]>
</screen>
</example>
</para>
<para>
Here we introduce a couple of new concepts. We have an
<link linkend="control-structures.if">if</link> statement.
If you are familiar with the basic syntax used by the C
language, this should look logical to you. Otherwise, you
should probably pick up an introductory PHP book and read the first
couple of chapters, or read the <link linkend="langref">Language
Reference</link> part of the manual.
</para>
<para>
The second concept we introduced was the <function>str_contains</function>
function call. <function>str_contains</function> is a function built into
PHP which determines if a given string contains another string. In this case we are
looking for <literal>'Firefox'</literal> (so-called needle) inside
<varname>$_SERVER['HTTP_USER_AGENT']</varname> (so-called haystack). If
the needle is found inside the haystack, the function returns true. Otherwise, it
returns &false;. If it returns &true;, the <link
linkend="control-structures.if">if</link> expression evaluates to &true;
and the code within its {braces} is executed. Otherwise, the code is not
run. Feel free to create similar examples,
with <link linkend="control-structures.if">if</link>,
<link linkend="control-structures.else">else</link>, and other
functions such as <function>strtoupper</function> and
<function>strlen</function>. Each related manual page contains examples
too. If you are unsure how to use functions, you will want to read both
the manual page on <link linkend="about.prototypes">how to read a
function definition</link> and the section about
<link linkend="language.functions">PHP functions</link>.
</para>
<para>
We can take this a step further and show how you can jump in and out
of PHP mode even in the middle of a PHP block:
</para>
<para>
<example>
<info><title>Mixing both HTML and PHP modes</title></info>
<programlisting role="php">
<![CDATA[
<?php
if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
?>
<h3>str_contains() returned true</h3>
<p>You are using Firefox</p>
<?php
} else {
?>
<h3>str_contains() returned false</h3>
<p>You are not using Firefox</p>
<?php
}
?>
]]>
</programlisting>
<para>
A sample output of this script may be:
</para>
<screen role="html">
<![CDATA[
<h3>str_contains() returned true</h3>
<p>You are using Firefox</p>
]]>
</screen>
</example>
</para>
<para>
Instead of using a PHP echo statement to output something, we jumped out
of PHP mode and just sent straight HTML. The important and powerful point
to note here is that the logical flow of the script remains intact. Only
one of the HTML blocks will end up getting sent to the viewer depending on
the result of <function>str_contains</function>. In other words, it depends on
whether the string <literal>Firefox</literal> was found or not.
</para>
</section>
<section xml:id="tutorial.forms">
<info><title>Dealing with Forms</title></info>
<para>
One of the most powerful features of PHP is the way it handles HTML
forms. The basic concept that is important to understand is that any
form element will automatically be available to your PHP
scripts. Please read the manual section on
<link linkend="language.variables.external">Variables from external
sources</link> for more information and examples on using forms
with PHP. Here is an example HTML form:
</para>
<para>
<example>
<info><title>A simple HTML form</title></info>
<programlisting role="html">
<![CDATA[
<form action="action.php" method="post">
<label for="name">Your name:</label>
<input name="name" id="name" type="text">
<label for="age">Your age:</label>
<input name="age" id="age" type="number">
<button type="submit">Submit</button>
</form>
]]>
</programlisting>
</example>
</para>
<para>
There is nothing special about this form. It is a straight HTML form
with no special tags of any kind. When the user fills in this form
and hits the submit button, the <filename>action.php</filename> page
is called. In this file you would write something like this:
</para>
<para>
<example>
<info><title>Printing data from our form</title></info>
<programlisting role="php">
<![CDATA[
Hi <?php echo htmlspecialchars($_POST['name']); ?>.
You are <?php echo (int)$_POST['age']; ?> years old.
]]>
</programlisting>
<para>
A sample output of this script may be:
</para>
<screen role="html">
<![CDATA[
Hi Joe. You are 22 years old.
]]>
</screen>
</example>
</para>
<para>
Apart from the <function>htmlspecialchars</function> and
<literal>(int)</literal> parts, it should be obvious what this does.
<function>htmlspecialchars</function> makes sure any characters that are
special in html are properly encoded so people can't inject HTML tags
or Javascript into your page. For the age field, since we know it is a
number, we can just <link linkend="language.types.typecasting">convert</link>
it to an <type>int</type> which will automatically get rid of any
stray characters. You can also have PHP do this for you automatically by
using the <link linkend="ref.filter">filter</link> extension.
The <varname>$_POST['name']</varname> and <varname>$_POST['age']</varname>
variables are automatically set for you by PHP. Earlier we
used the <varname>$_SERVER</varname> superglobal; above we just
introduced the <varname>$_POST</varname>
superglobal which contains all POST data. Notice how the
<emphasis>method</emphasis> of our form is POST. If we used the
method <emphasis>GET</emphasis> then our form information would live in
the <varname>$_GET</varname> superglobal instead.
You may also use the <varname>$_REQUEST</varname>
superglobal, if you do not care about the source of your request data. It
contains the merged information of GET, POST and COOKIE data.
</para>
<para>
You can also deal with XForms input in PHP, although you will find yourself
comfortable with the well supported HTML forms for quite some time.
While working with XForms is not for beginners, you might be interested
in them. We also have a <link linkend="features.xforms">short introduction
to handling data received from XForms</link> in our features section.
</para>
</section>
<section xml:id="tutorial.whatsnext">
<info><title>What's next?</title></info>
<para>
With your new knowledge you should be able to understand most of
the manual and also the various example scripts available in the
example archives.
</para>
<para>
To view various slide presentations that show more of what PHP can do,
see the PHP Conference Material Site:
<link xlink:href="&url.php.talks;">&url.php.talks;</link>
</para>
</section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->