goba Sun May 23 16:51:39 2004 EDT
Added files:
/phpdoc/en/features xforms.xml
Modified files:
/phpdoc/entities global.ent
/phpdoc/en/chapters tutorial.xml
Log:
reworded a lot of parts to make the tutorial more suitable for beginners
- point people to the mailing list where we write about installation
- explain phpinfo() where it is first mentioned
- explain problem with opening a PHP file from the file system
- remove the xforms part and add it in features, since it does not
belong in a *simple* tutorial
- added some missing tags where needed, more interlinks to other parts
of the manual
http://cvs.php.net/diff.php/phpdoc/entities/global.ent?r1=1.181&r2=1.182&ty=u
Index: phpdoc/entities/global.ent
diff -u phpdoc/entities/global.ent:1.181 phpdoc/entities/global.ent:1.182
--- phpdoc/entities/global.ent:1.181 Sat May 22 13:02:26 2004
+++ phpdoc/entities/global.ent Sun May 23 16:51:39 2004
@@ -1,6 +1,6 @@
<!-- -*- SGML -*-
- $Id: global.ent,v 1.181 2004/05/22 17:02:26 abies Exp $
+ $Id: global.ent,v 1.182 2004/05/23 20:51:39 goba Exp $
Contains global "macros" for all the XML documents.
@@ -229,6 +229,7 @@
<!ENTITY url.php.license "http://www.php.net/license/";>
<!ENTITY url.php.links "http://www.php.net/links.php";>
<!ENTITY url.php.manual "http://www.php.net/manual/";>
+<!ENTITY url.php.mailing-lists "http://www.php.net/mailing-lists.php";>
<!ENTITY url.php.museum "http://museum.php.net/";>
<!ENTITY url.php.news "news://news.php.net/";>
<!ENTITY url.php.newsweb "http://news.php.net/";>
http://cvs.php.net/diff.php/phpdoc/en/chapters/tutorial.xml?r1=1.32&r2=1.33&ty=u
Index: phpdoc/en/chapters/tutorial.xml
diff -u phpdoc/en/chapters/tutorial.xml:1.32 phpdoc/en/chapters/tutorial.xml:1.33
--- phpdoc/en/chapters/tutorial.xml:1.32 Wed Mar 24 11:39:43 2004
+++ phpdoc/en/chapters/tutorial.xml Sun May 23 16:51:39 2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.32 $ -->
+<!-- $Revision: 1.33 $ -->
<chapter id="tutorial">
<title>A simple tutorial</title>
@@ -38,15 +38,22 @@
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 linkend="install.apache">Apache</link>, and of course
- <ulink url="&url.php.downloads;">PHP</ulink>. You will most likely
+ <ulink url="&url.php.downloads;">PHP</ulink>. You will most likely
want to install a database as well, such as
- <ulink url="&url.mysql.docs;">MySQL</ulink>. You can either install
- these individually or choose a simpler way. <ulink
- url="&url.installkits;">Locate a pre-configured package</ulink>
- 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 Linux and Windows. On Linux,
- you may find <ulink url="&url.rpmfind;">rpmfind</ulink> and
+ <ulink url="&url.mysql.docs;">MySQL</ulink>.
+ </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 webserver set up). In case you have
+ problems with installing PHP yourself, we would suggest you ask your
+ questions on our <ulink url="&url.php.mailing-lists;">installation
+ mailing list</ulink>. If you choose to go on the simpler route, then
+ <ulink url="&url.installkits;">locate a pre-configured package</ulink>
+ 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 <ulink url="&url.rpmfind;">rpmfind</ulink> and
<ulink url="&url.rpmfind.pbone;">PBone</ulink> helpful for
locating RPMs. You may also want to visit <ulink
url="&url.apt-get;">apt-get</ulink> to find packages for Debian.
@@ -77,15 +84,12 @@
</programlisting>
<simpara>
Use your browser to access the file with your web server's URL, ending
- with the "/hello.php" file reference. When developing locally this
+ with the "/hello.php" 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. Although this is outside the scope of this
- tutorial, see also the <varname>DocumentRoot</varname> and
- <varname>ServerName</varname> directives in your web server's
- configuration file (for Apache, this is &httpd.conf;).
- If everything is configured correctly, this file will be parsed by PHP
- and the following output will be sent to your browser:
+ 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[
@@ -102,37 +106,39 @@
</example>
</para>
<para>
- Note that this is not like a CGI script. The file does not need to be
- executable or special in any way. Think of it 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>
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.
+ 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. Ask your administrator
- to enable it for you using 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="installation">Installation</link> chapter
of the manual. If you are developing locally, also read the
installation chapter to make sure everything is configured
- properly. If the problems persist, do not hesitate to use one of
- the many <ulink url="&url.php.support;">PHP support</ulink> options.
+ 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
+ <ulink url="&url.php.support;">PHP support</ulink> 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 all you want. For more
- details, read the manual section on <link linkend="language.basic-syntax">
+ 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>
<title>A Note on Text Editors</title>
<para>
@@ -150,8 +156,8 @@
<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 PLAIN TEXT or PHP
- will not be able to read and execute the script.
+ 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>
@@ -167,18 +173,28 @@
'Text Documents' drop-down menu in the 'Save' dialog box and change the setting
to "All Files". You can then enter your filename without quotes.
</para>
- </note>
+ </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>
+ 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>
+ <para>
+ <example>
+ <title>Get system information from PHP</title>
+ <programlisting role="php">
+<![CDATA[
+<?php phpinfo(); ?>
+]]>
+ </programlisting>
+ </example>
+ </para>
</sect1>
<sect1 id="tutorial.useful">
@@ -221,7 +237,7 @@
A sample output of this script may be:
</para>
<screen role="html">
-Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)
+Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
</screen>
</example>
</para>
@@ -235,23 +251,9 @@
<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 creating
- a file that looks like this:
- </para>
- <para>
- <example>
- <title>Show all predefined variables with <function>phpinfo</function></title>
- <programlisting role="php">
-<![CDATA[
-<?php phpinfo(); ?>
-]]>
- </programlisting>
- </example>
- </para>
- <para>
- When 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
- variables available to you.
+ 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
@@ -266,8 +268,8 @@
<programlisting role="php">
<![CDATA[
<?php
-if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== false) {
- echo 'You are using Internet Explorer<br />';
+if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
+ echo 'You are using Internet Explorer.<br />';
}
?>
]]>
@@ -277,7 +279,7 @@
</para>
<screen role="html">
<![CDATA[
-You are using Internet Explorer<br />
+You are using Internet Explorer.<br />
]]>
</screen>
</example>
@@ -287,7 +289,7 @@
<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 any introductory PHP book and read the first
+ 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. You can find a list of PHP books
at <ulink url="&url.php.books;">&url.php.books;</ulink>.
@@ -323,15 +325,15 @@
<programlisting role="php">
<![CDATA[
<?php
-if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== false) {
+if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
?>
-<h3>strpos must have returned non-false</h3>
-<center><b>You are using Internet Explorer</b></center>
+<h3>strpos() must have returned non-false</h3>
+<p>You are using Internet Explorer</p>
<?php
} else {
?>
-<h3>strpos must have returned false</h3>
-<center><b>You are not using Internet Explorer</b></center>
+<h3>strpos() must have returned false</h3>
+<p>You are not using Internet Explorer</p>
<?php
}
?>
@@ -342,8 +344,8 @@
</para>
<screen role="html">
<![CDATA[
-<h3>strpos must have returned non-false</h3>
-<center><b>You are using Internet Explorer</b></center>
+<h3>strpos() must have returned non-false</h3>
+<p>You are using Internet Explorer</p>
]]>
</screen>
</example>
@@ -363,7 +365,7 @@
<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 be available to your PHP
+ form element 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
@@ -375,9 +377,9 @@
<programlisting role="html">
<![CDATA[
<form action="action.php" method="post">
- Your name: <input type="text" name="name" />
- Your age: <input type="text" name="age" />
- <input type="submit" />
+ <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>
@@ -423,103 +425,20 @@
contains the merged information of GET, POST and COOKIE data. Also see the
<function>import_request_variables</function> function.
</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>
</sect1>
- <sect1 id="tutorial.xforms">
- <title>Dealing with XForms</title>
- <para>
- <ulink url="&url.xforms;">XForms</ulink> defines a variation on traditional
- webforms which allows them to be used on a wider variety of platforms and
- browsers or even non-traditional media such as PDF documents.
- </para>
- <para>
- The first key difference in xforms is how the form is sent to the client.
- <ulink url="&url.xforms.htmlauthors;">XForms for HTML Authors</ulink>
- contains a detailed description of how to create XForms, for the purpose
- of this tutorial we'll only be looking at a simple example.
- </para>
- <example>
- <title>A simple XForms search form</title>
- <programlisting role="html">
-<![CDATA[
-<h:html xmlns:h="http://www.w3.org/1999/xhtml";
- xmlns="http://www.w3.org/2002/xforms";>
-<h:head>
- <h:title>Search</h:title>
- <model>
- <submission action="http://example.com/search";
- method="post" id="s"/>
- </model>
-</h:head>
-<h:body>
- <h:p>
- <input ref="q"><label>Find</label></input>
- <submit submission="s"><label>Go</label></submit>
- </h:p>
-</h:body>
-</h:html>
-]]>
- </programlisting>
- </example>
- <para>
- The above form displays a text input box (named <parameter>q</parameter>),
- and a submit button. When the submit button is clicked, the form will be
- sent to the page referred to by action.
- </para>
- <para>
- Here's where it starts to look different from your web application's point
- of view. In a normal HTML form, the data would be sent as
- application/x-www-form-urlencoded, in the XForms world however, this information
- is sent as XML formatted data.
- </para>
- <para>
- If you're choosing to work with XForms then you probably want that data as
- XML, in that case, look in $HTTP_RAW_POST_DATA where you'll find the XML
- document generated by the browser which you can pass into your favorite
- XSLT engine or document parser.
- </para>
- <para>
- If you're not interrested in formatting and just want your data to be loaded
- into the traditional $_POST variable, you can instruct the client browser
- to send it as application/x-www-form-urlencoded by changing the
- <parameter>method</parameter> attribute to <emphasis>urlencoded-post</emphasis>.
- </para>
- <example>
- <title>Using an XForm to populate $_POST</title>
- <programlisting role="html">
-<![CDATA[
-<h:html xmlns:h="http://www.w3.org/1999/xhtml";
- xmlns="http://www.w3.org/2002/xforms";>
-<h:head>
- <h:title>Search</h:title>
- <model>
- <submission action="http://example.com/search";
- method="urlencoded-post" id="s"/>
- </model>
-</h:head>
-<h:body>
- <h:p>
- <input ref="q"><label>Find</label></input>
- <submit submission="s"><label>Go</label></submit>
- </h:p>
-</h:body>
-</h:html>
-]]>
- </programlisting>
- </example>
- <note>
- <simpara>
- As of this writing, many browsers do not support XForms.
- Check your browser version if the above examples fail.
- </simpara>
- </note>
- </sect1>
-
<sect1 id="tutorial.oldcode">
<title>Using old code with new versions of PHP</title>
<para>
Now that PHP has grown to be a popular scripting language, there are
- a lot of public repositories/libraries containing code you can reuse.
+ a lot of public repositories and libraries containing code you can reuse.
The PHP developers have largely tried to preserve backwards compatibility,
so a script written for an older version will run (ideally) without changes
in a newer version of PHP. In practice, some changes will usually be needed.
@@ -540,7 +459,6 @@
<varname>$_REQUEST</varname>, and <varname>$_SESSION</varname>. The
older <varname>$HTTP_*_VARS</varname> arrays, such as
<varname>$HTTP_POST_VARS</varname>, still exist as they have since PHP 3.
-
&avail.register-long-arrays;
</simpara>
</listitem>
http://cvs.php.net/co.php/phpdoc/en/features/xforms.xml?r=1.1&p=1
Index: phpdoc/en/features/xforms.xml
+++ phpdoc/en/features/xforms.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<chapter id="features.xforms">
<title>Dealing with XForms</title>
<para>
<ulink url="&url.xforms;">XForms</ulink> defines a variation on traditional
webforms which allows them to be used on a wider variety of platforms and
browsers or even non-traditional media such as PDF documents.
</para>
<para>
The first key difference in XForms is how the form is sent to the client.
<ulink url="&url.xforms.htmlauthors;">XForms for HTML Authors</ulink>
contains a detailed description of how to create XForms, for the purpose
of this tutorial we'll only be looking at a simple example.
</para>
<example>
<title>A simple XForms search form</title>
<programlisting role="html">
<![CDATA[
<h:html xmlns:h="http://www.w3.org/1999/xhtml";
xmlns="http://www.w3.org/2002/xforms";>
<h:head>
<h:title>Search</h:title>
<model>
<submission action="http://example.com/search";
method="post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Find</label></input>
<submit submission="s"><label>Go</label></submit>
</h:p>
</h:body>
</h:html>
]]>
</programlisting>
</example>
<para>
The above form displays a text input box (named <parameter>q</parameter>),
and a submit button. When the submit button is clicked, the form will be
sent to the page referred to by <literal>action</literal>.
</para>
<para>
Here's where it starts to look different from your web application's point
of view. In a normal HTML form, the data would be sent as
<literal>application/x-www-form-urlencoded</literal>, in the XForms world
however, this information is sent as XML formatted data.
</para>
<para>
If you're choosing to work with XForms then you probably want that data as
XML, in that case, look in <variable>$HTTP_RAW_POST_DATA</variable> where
you'll find the XML document generated by the browser which you can pass
into your favorite XSLT engine or document parser.
</para>
<para>
If you're not interrested in formatting and just want your data to be loaded
into the traditional <variable>$_POST</variable> variable, you can instruct
the client browser to send it as <literal>application/x-www-form-urlencoded</literal>
by changing the <parameter>method</parameter> attribute to
<emphasis>urlencoded-post</emphasis>.
</para>
<example>
<title>Using an XForm to populate <variable>$_POST</variable></title>
<programlisting role="html">
<![CDATA[
<h:html xmlns:h="http://www.w3.org/1999/xhtml";
xmlns="http://www.w3.org/2002/xforms";>
<h:head>
<h:title>Search</h:title>
<model>
<submission action="http://example.com/search";
method="urlencoded-post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Find</label></input>
<submit submission="s"><label>Go</label></submit>
</h:p>
</h:body>
</h:html>
]]>
</programlisting>
</example>
<note>
<simpara>
As of this writing, many browsers do not support XForms.
Check your browser version if the above examples fails.
</simpara>
</note>
</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:"../../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
-->
