mirror of
https://github.com/php/doc-en.git
synced 2026-04-30 02:33:15 +02:00
Christoph M. Becker
6b60bf846b
We should not encourage use of Notepad for editing PHP files, and those who use it, should at least know how it works (after all, it's not that complex). Closes GH-1265.
473 lines
19 KiB
XML
473 lines
19 KiB
XML
<?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[
|
|
<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[
|
|
<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">
|
|
Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
|
|
</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 <link linkend="language.types.array">Array</link> element.
|
|
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 Internet Explorer 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 (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
|
|
echo 'You are using Internet Explorer.<br />';
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
A sample output of this script may be:
|
|
</para>
|
|
<screen role="html">
|
|
<![CDATA[
|
|
You are using Internet Explorer.<br />
|
|
]]>
|
|
</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>strpos</function>
|
|
function call. <function>strpos</function> is a function built into
|
|
PHP which searches a string for another string. In this case we are
|
|
looking for <literal>'MSIE'</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 the position
|
|
of the needle relative to the start of the haystack. Otherwise, it
|
|
returns &false;. If it does not return &false;, 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 (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
|
|
?>
|
|
<h3>strpos() must have returned non-false</h3>
|
|
<p>You are using Internet Explorer</p>
|
|
<?php
|
|
} else {
|
|
?>
|
|
<h3>strpos() must have returned false</h3>
|
|
<p>You are not using Internet Explorer</p>
|
|
<?php
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
A sample output of this script may be:
|
|
</para>
|
|
<screen role="html">
|
|
<![CDATA[
|
|
<h3>strpos() must have returned non-false</h3>
|
|
<p>You are using Internet Explorer</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>strpos</function>. In other words, it depends on
|
|
whether the string <literal>MSIE</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">
|
|
<p>Your name: <input type="text" name="name" /></p>
|
|
<p>Your age: <input type="text" name="age" /></p>
|
|
<p><input type="submit" /></p>
|
|
</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
|
|
-->
|