philip Tue Jul 16 17:09:37 2002 EDT
Modified files:
/phpdoc/en/chapters tutorial.xml
Log:
Made many changes. Added a lot of Autoglobal information, made
all informal examples formal, reworded various parts, and added
a lot of links.
Index: phpdoc/en/chapters/tutorial.xml
diff -u phpdoc/en/chapters/tutorial.xml:1.2 phpdoc/en/chapters/tutorial.xml:1.3
--- phpdoc/en/chapters/tutorial.xml:1.2 Tue Jul 16 09:11:09 2002
+++ phpdoc/en/chapters/tutorial.xml Tue Jul 16 17:09:37 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<chapter id="tutorial">
<title>A simple tutorial</title>
@@ -41,7 +41,7 @@
</para>
<para>
<example>
- <title>hello.php</title>
+ <title>Our first PHP script: <filename>hello.php</filename></title>
<programlisting role="php">
<![CDATA[
<html>
@@ -65,13 +65,19 @@
<para>
This program is extremely simple and you really didn't need to use
PHP to create a page like this. All it does is display:
- <literal>Hello World</literal> using the <function>echo</function>
+ <literal>Hello World</literal> using the PHP <function>echo</function>
statement.
</para>
<para>
- If you tried this example and it didn't output anything or you see
- the whole file as text, chances are that the server you are on does
- not have PHP enabled. Ask your administrator to enable it for you.
+ If you tried this example and it didn't output anything, or 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. Ask your administrator
+ to enable it for you using the
+ <link linkend="installation">Installation</link> chapter
+ of the manual. If you want to develop PHP scripts locally, see
+ the <ulink url="&url.php.downloads;">downloads</ulink> section.
+ You can develop locally on any Operating system, be sure to
+ install an appropriate web server too.
</para>
<para>
The point of the example is to show the special PHP tag format.
@@ -88,31 +94,61 @@
Let's do something a bit more useful now. We are going to check
what sort of browser the person viewing the page is using.
In order to do that we check the user agent string that the browser
- sends as part of its request. This information is stored in a <link
+ sends as part of its 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 is
- <varname>$_SERVER["HTTP_USER_AGENT"]</varname>. To display this
- variable we can simply do:
+ with a dollar-sign in PHP. The variable we are interested in right now
+ is <varname>$_SERVER["HTTP_USER_AGENT"]</varname>.
</para>
- <informalexample>
+ <note>
+ <title>PHP Autoglobals Note</title>
+ <para>
+ <link linkend="reserved.variables.server">$_SERVER</link> is a
+ special reserved PHP variable that contains all web server information.
+ It's known as an Autoglobal. See the related manual page on
+ <link linkend="language.variables.superglobals">Autoglobals</link>
+ (also known as Superglobals) for more information. These special
+ variables were introduced in PHP 4.1.0. Before this time, we used
+ the older <varname>$HTTP_*_VARS</varname> arrays instead,
+ such as <varname>$HTTP_SERVER_VARS</varname>. Although deprecated,
+ these older variables still exist.
+ </para>
+ </note>
+ <para>
+ To display this variable, we can simply do:
+ </para>
+ <para>
+ <example>
+ <title>Printing a variable (Array element)</title>
<programlisting role="php">
<![CDATA[
<?php echo $_SERVER["HTTP_USER_AGENT"]; ?>
]]>
</programlisting>
- </informalexample>
+ </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>
- There are many other variables that are automatically set by
- for your by PHP. You can get a complete list of them by creating
+ <varname>$_SERVER</varname> is just one variable that's automatically
+ made available to you by PHP. 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 creating
a file that looks like this:
</para>
- <informalexample>
- <programlisting role="php">
+ <para>
+ <example>
+ <title>Show all predefined variables with <function>phpinfo</function></title>
+ <programlisting role="php">
<![CDATA[
<?php phpinfo(); ?>
]]>
- </programlisting>
- </informalexample>
+ </programlisting>
+ </example>
+ </para>
<para>
If you load up this file in your browser you will see a page
full of information about PHP along with a list of all the
@@ -124,8 +160,11 @@
For example, if we wanted to check for Internet Explorer we
could do something like this:
</para>
- <informalexample>
- <programlisting role="php">
+ <para>
+ <example>
+ <title>Example using <link linkend="control-structures">control
+ structures</link> and <link linkend="functions">functions</link></title>
+ <programlisting role="php">
<![CDATA[
<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
@@ -133,8 +172,9 @@
}
?>
]]>
- </programlisting>
- </informalexample>
+ </programlisting>
+ </example>
+ </para>
<para>
Here we introduce a couple of new concepts. We have an
<link linkend="control-structures.if">if</link> statement.
@@ -151,36 +191,50 @@
function call. <function>strstr</function> is a function built into
PHP which searches a string for another string. In this case we are
looking for <literal>"MSIE"</literal> inside
- <varname>$_SERVER["HTTP_USER_AGENT"]</varname>. If the string is found
+ <varname>$_SERVER["HTTP_USER_AGENT"]</varname>. If the string is found,
the function returns &true; and if it isn't, it returns &false;. If
- it returns &true; the following statement is executed.
+ it returns &true;, the <link linkend="control-structures.if">if</link>
+ statement evaluates to &true; and the code within its {braces} is
+ executed. Otherwise, it's not. 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.
</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>
- <informalexample>
- <programlisting role="php">
+ <para>
+ <example>
+ <title>Mixing both HTML and PHP modes</title>
+ <programlisting role="php">
<![CDATA[
<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
?>
+<h3>strstr must have returned true</h3>
<center><b>You are using Internet Explorer</b></center>
<?php
} else {
?>
+<h3>strstr must have returned false</h3>
<center><b>You are not using Internet Explorer</b></center>
<?php
}
?>
]]>
- </programlisting>
- </informalexample>
+ </programlisting>
+ </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 remain intact. Only one of the HTML blocks
- will end up getting sent to the viewer.
+ 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 if
+ <function>strstr</function> returned &true; or &false; In other words,
+ if the string <literal>MSIE</literal> was found or not.
</para>
</sect1>
@@ -189,13 +243,16 @@
<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 in a form will automatically result in a variable
- with the same name as the element being created on the target page.
- This probably sounds confusing, so here is a simple example.
- Assume you have a page with a form like this on it:
+ form element in a form will automatically be available to your PHP
+ scripts. Please read the manual section on
+ <link linkend="language.variables.external">Variables from outside
+ of PHP</link> for more information and examples on using forms
+ with PHP. Here's an example HTML form:
</para>
- <informalexample>
- <programlisting role="html">
+ <para>
+ <example>
+ <title>A simple HTML form</title>
+ <programlisting role="html">
<![CDATA[
<form action="action.php" method="POST">
Your name: <input type="text" name="name" />
@@ -203,37 +260,40 @@
<input type="submit">
</form>
]]>
- </programlisting>
- </informalexample>
+ </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 have something like this:
</para>
- <informalexample>
- <programlisting role="php">
+ <para>
+ <example>
+ <title>Printing data from our form</title>
+ <programlisting role="php">
<![CDATA[
Hi <?php echo $_POST["name"]; ?>.
You are <?php echo $_POST["age"]; ?> years old.
]]>
- </programlisting>
- </informalexample>
+ </programlisting>
+ </example>
+ </para>
<para>
It should be obvious what this does. There is nothing more to it.
The <varname>$_POST["name"]</varname> and <varname>$_POST["age"]</varname>
- variables are automatically set for you by PHP.
- </para>
- <para>
- <note>
- <para>
- On versions previous to PHP 4.1.0, one needed to use the
- <varname>$HTTP_POST_VARS</varname> array instead of the
- <varname>$_POST</varname> superglobal array. See the section
- on <link linkend="language.variables.predefined">predefined
- variables</link> for more information.
- </para>
- </note>
+ variables are automatically set for you by PHP. Earlier we
+ used the <varname>$_SERVER</varname> autoglobal, now above we just
+ introduced the <link linkend="reserved.variables.post">$_POST</link>
+ autoglobal 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 <link linkend="reserved.variables.get">$_GET</link> autoglobal instead.
+ You may also use the <link linkend="reserved.variables.request">$_REQUEST</link>
+ autoglobal if you don't care the source of your request data. It
+ contains a mix of GET, POST, COOKIE and FILE data. See also the
+ <function>import_request_variables</function> function.
</para>
</sect1>
@@ -254,25 +314,33 @@
<simpara>
The deprecation of the old <varname>$HTTP_*_VARS</varname> arrays
(which need to be indicated as global when used inside a function or
- method), for the superglobal arrays <varname>$_GET</varname>,
- <varname>$_POST</varname>, <varname>$_COOKIE</varname>,
- <varname>$_SERVER</varname>, <varname>$_ENV</varname>,
- <varname>$_REQUEST</varname>, and <varname>$_SESSION</varname>,
- which are always accessible even from inside a function
- scope. (PHP >= 4.1.0)
+ method). The following
+ <link linkend="language.variables.superglobals">autoglobal arrays</link>
+ were introduced in PHP 4.1.0. They are:
+ <varname>$_GET</varname>, <varname>$_POST</varname>,
+ <varname>$_COOKIE</varname>, <varname>$_SERVER</varname>,
+ <varname>$_ENV</varname>, <varname>$_REQUEST</varname>, and
+ <varname>$_SESSION</varname>. The older <varname>$HTTP_*_VARS</varname>
+ arrays, such as $HTTP_POST_VARS, still exist and have since PHP 3.
</simpara>
</listitem>
<listitem>
<simpara>
External variables are no longer registered in the global scope by
- default (in other words, <literal>register_globals=off</literal>
- by defaults in php.ini), which means that the preferred method of
- accessing those values is via the superglobal arrays mentioned
- above. (PHP >= 4.2.0)
+ default. In other words, as of PHP
+ <ulink url="&url.php.release4.2.0;">4.2.0</ulink> the PHP directive
+ <link linkend="ini.register-globals">register_globals</link> is
+ <emphasis>off</emphasis> by default in &php.ini;. The preferred
+ method of accessing these values is via the autoglobal arrays mentioned
+ above. Older scripts, books, and tutorials may rely on this
+ directive being on. If on, for example, one could use
+ <varname>$id</varname> from the URL
+ <literal>http://www.example.com/foo.php?id=42</literal>. Whether on
+ or off, <varname>$_GET['id']</varname> is available.
</simpara>
</listitem>
</itemizedlist>
- For more details on these changes see the section on
+ For more details on these changes, see the section on
<link linkend="language.variables.predefined">predefined variables</link>
and links therein.
</para>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
