mirror of
https://github.com/php/doc-en.git
synced 2026-03-24 07:42:10 +01:00
876557ae38
* doc: Simplifiying the "A simple tutorial" page by removing the Apache and MySQL pre-requisites and using php's builtin server * Apply suggestions from code review Co-authored-by: Tim Düsterhus <timwolla@googlemail.com> * Update chapters/tutorial.xml Co-authored-by: Tim Düsterhus <timwolla@googlemail.com> * Adding closing tag to examples * Removing trailing whitespace --------- Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>
455 lines
16 KiB
XML
455 lines
16 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.firstpage">
|
|
<info><title>Your first PHP-enabled page</title></info>
|
|
<simpara>
|
|
This tutorial assumes PHP is already installed.
|
|
Installation instructions can be found on the
|
|
<link xlink:href="&url.php.downloads;">download page</link>.
|
|
</simpara>
|
|
<para>
|
|
Create a file named <filename>hello.php</filename>
|
|
with the following content:
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<info><title>Our first PHP script: <filename>hello.php</filename></title></info>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
echo "Hello World!";
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<simpara>
|
|
Using your terminal, navigate to the directory containing this file and
|
|
start a development server with the following command:
|
|
</simpara>
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
php -S localhost:8000
|
|
]]>
|
|
</programlisting>
|
|
<simpara>
|
|
Use your browser to access the file with your web server's URL, ending
|
|
with the <literal>/hello.php</literal> file reference.
|
|
According to the previous command executed, the URL will be
|
|
<literal>http://localhost:8000/hello.php</literal>.
|
|
If everything is configured correctly, this file will be parsed by PHP
|
|
and you will see the "Hello World!" output displayed in your browser.
|
|
</simpara>
|
|
<simpara>
|
|
PHP can be embedded within a normal HTML web page. That means inside your HTML document
|
|
you can write the PHP statements, as demonstrated in the following example:
|
|
</simpara>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>PHP Test</title>
|
|
</head>
|
|
<body>
|
|
<?php echo '<p>Hello World</p>'; ?>
|
|
</body>
|
|
</html>
|
|
]]>
|
|
</programlisting>
|
|
<simpara>
|
|
This will result in the following output:
|
|
</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>
|
|
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>
|
|
</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
|
|
-->
|