reverted last changes

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@38989 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hartmut Holzgraefe 2001-01-09 12:38:23 +00:00
parent 21a62e5546
commit 50c57eca13
4 changed files with 526 additions and 0 deletions

37
features/cookies.xml Normal file
View file

@ -0,0 +1,37 @@
<chapter id="features.cookies">
<title>Cookies</title>
<para>
PHP transparently supports HTTP cookies. Cookies are a mechanism
for storing data in the remote browser and thus tracking
or identifying return users. You can set cookies using the
<function>setcookie</function> function. Cookies are part of the
HTTP header, so <function>setcookie</function> must be called before
any output is sent to the browser. This is the same limitation that
<function>header</function> has.</para>
<para>
Any cookies sent to you from the client will automatically be
turned into a PHP variable just like GET and POST method data. If
you wish to assign multiple values to a single cookie, just add
<emphasis>[]</emphasis> to the cookie name. For more details see
the <function>setcookie</function> function.</para>
</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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

305
features/error-handling.xml Normal file
View file

@ -0,0 +1,305 @@
<chapter id="features.error-handling">
<title>Error Handling</title>
<para>
There are several types of errors and warnings in PHP. They are:
<table>
<title>PHP error types</title>
<tgroup cols="4">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Description</entry>
<entry>Note</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>E_ERROR</entry>
<entry>fatal run-time errors</entry>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>E_WARNING</entry>
<entry>run-time warnings (non fatal errors)</entry>
<entry></entry>
</row>
<row>
<entry>4</entry>
<entry>E_PARSE</entry>
<entry>compile-time parse errors</entry>
<entry></entry>
</row>
<row>
<entry>8</entry>
<entry>E_NOTICE </entry>
<entry>
run-time notices (less serious than warnings)
</entry>
<entry></entry>
</row>
<row>
<entry>16</entry>
<entry>E_CORE_ERROR</entry>
<entry>fatal errors that occur during PHP's initial startup</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>32</entry>
<entry>E_CORE_WARNING</entry>
<entry>
warnings (non fatal errors) that occur during PHP's initial
startup
</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>64</entry>
<entry>E_COMPILE_ERROR</entry>
<entry>fatal compile-time errors</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>128</entry>
<entry>E_COMPILE_WARNING</entry>
<entry>compile-time warnings (non fatal errors)</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>256</entry>
<entry>E_USER_ERROR</entry>
<entry>user-generated error message</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>512</entry>
<entry>E_USER_WARNING</entry>
<entry>user-generated warning message</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>1024</entry>
<entry>E_USER_NOTICE </entry>
<entry>user-generated notice message</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry></entry>
<entry>E_ALL</entry>
<entry>all of the above, as supported</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The above values (either numerical or symbolic) are used to build
up a bitmask that specifies which errors to report. You can use the
<link linkend="language.operators.bitwise">bitwise operators</link>
to combine these values or mask out certain types of errors. Note
that only '|', '~', '!', and '&amp;' will be understood within
<filename>php.ini</filename>, however, and that no bitwise
operators will be understood within <filename>php3.ini</filename>.
</para>
<para>
In PHP 4, the default <link
linkend="ini.error-reporting">error_reporting</link> setting is
<literal>E_ALL &amp; ~E_NOTICE</literal>, meaning to display all errors
and warnings which are not E_NOTICE-level. In PHP 3, the default
setting is <literal>(E_ERROR | E_WARNING | E_PARSE)</literal>,
meaning the same thing. Note, however, that since constants are not
supported in PHP 3's <filename>php3.ini</filename>, the <link
linkend="ini.error-reporting">error_reporting</link> setting there
must be numeric; hence, it is <literal>7</literal>.
</para>
<para>
The initial setting can be changed in the ini file with the <link
linkend="ini.error-reporting">error_reporting</link> directive, in
your Apache <filename>httpd.conf</filename> file with the
php_error_reporting (php3_error_reporting for PHP 3) directive, and
lastly it may be set at runtime within a script by using the
<function>error_reporting</function> function.
</para>
<warning>
<para>
When upgrading code or servers from PHP 3 to PHP 4 you should
check these settings and calls to
<function>error_reporting</function> or you might disable
reporting the new error types, especially E_COMPILE_ERROR. This
may lead to empty documents without any feedback of what happened
or where to look for the problem.
</para>
</warning>
<para>
All <link linkend="language.expressions">PHP expressions</link> can
also be called with the "@" prefix, which turns off error reporting
for that particular expression. If an error occurred during such
an expression and the <link
linkend="ini.track-errors">track_errors</link> feature is enabled,
you can find the error message in the global variable
$php_errormsg.
</para>
<warning>
<para>
Currently the <link linkend="language.operators.errorcontrol">@
error-control operator</link> prefix will even disable error
reporting for critical errors that will terminate script
execution. Among other things, this means that if you use <link
linkend="language.operators.errorcontrol">@</link> to suppress
errors from a certain function and either it isn't available or
has been mistyped, the script will die right there with no
indication as to why.
</para>
</warning>
<para>
Below we can see an example of using the error handling capabilities in
PHP. We define a error handling function which logs the information into
a file (using an XML format), and e-mails the developer in case a critical
error in the logic happens.
<example>
<title>Using error handling in a script</title>
<programlisting role="php">
&lt;?php
// we will do our own error handling
error_reporting(0);
// user defined error handling function
function userErrorHandler ($errno, $errmsg, $filename, $linenum, $vars) {
// timestamp for the error entry
$dt = date(&quot;Y-m-d H:i:s (T)&quot;);
// define an assoc array of error string
// in reality the only entries we should
// consider are 2,8,256,512 and 1024
$errortype = array (
1 =&gt; &quot;Error&quot;,
2 =&gt; &quot;Warning&quot;,
4 =&gt; &quot;Parsing Error&quot;,
8 =&gt; &quot;Notice&quot;,
16 =&gt; &quot;Core Error&quot;,
32 =&gt; &quot;Core Warning&quot;,
64 =&gt; &quot;Compile Error&quot;,
128 =&gt; &quot;Compile Warning&quot;,
256 =&gt; &quot;User Error&quot;,
512 =&gt; &quot;User Warning&quot;,
1024=&gt; &quot;User Notice&quot;
);
// set of errors for which a var trace will be saved
$user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
$err = &quot;&lt;errorentry&gt;\n&quot;;
$err .= &quot;\t&lt;datetime&gt;&quot;.$dt.&quot;&lt;/datetime&gt;\n&quot;;
$err .= &quot;\t&lt;errornum&gt;&quot;.$errno.&quot;&lt;/errnumber&gt;\n&quot;;
$err .= &quot;\t&lt;errortype&gt;&quot;.$errortype[$errno].&quot;&lt;/errortype&gt;\n&quot;;
$err .= &quot;\t&lt;errormsg&gt;&quot;.$errmsg.&quot;&lt;/errormsg&gt;\n&quot;;
$err .= &quot;\t&lt;scriptname&gt;&quot;.$filename.&quot;&lt;/scriptname&gt;\n&quot;;
$err .= &quot;\t&lt;scriptlinenum&gt;&quot;.$linenum.&quot;&lt;/scriptlinenum&gt;\n&quot;;
if (in_array($errno, $user_errors))
$err .= &quot;\t&lt;vartrace&gt;&quot;.wddx_serialize_value($vars,&quot;Variables&quot;).&quot;&lt;/vartrace&gt;\n&quot;;
$err .= &quot;&lt;/errorentry&gt;\n\n&quot;;
// for testing
// echo $err;
// save to the error log, and e-mail me if there is a critical user error
error_log($err, 3, &quot;/usr/local/php4/error.log&quot;);
if ($errno == E_USER_ERROR)
mail(&quot;phpdev@mydomain.com&quot;,&quot;Critical User Error&quot;,$err);
}
function distance ($vect1, $vect2) {
if (!is_array($vect1) || !is_array($vect2)) {
trigger_error(&quot;Incorrect parameters, arrays expected&quot;, E_USER_ERROR);
return NULL;
}
if (count($vect1) != count($vect2)) {
trigger_error(&quot;Vectors need to be of the same size&quot;, E_USER_ERROR);
return NULL;
}
for ($i=0; $i&lt;count($vect1); $i++) {
$c1 = $vect1[$i]; $c2 = $vect2[$i];
$d = 0.0;
if (!is_numeric($c1)) {
trigger_error(&quot;Coordinate $i in vector 1 is not a number, using zero&quot;,
E_USER_WARNING);
$c1 = 0.0;
}
if (!is_numeric($c2)) {
trigger_error(&quot;Coordinate $i in vector 2 is not a number, using zero&quot;,
E_USER_WARNING);
$c2 = 0.0;
}
$d += $c2*$c2 - $c1*$c1;
}
return sqrt($d);
}
$old_error_handler = set_error_handler(&quot;userErrorHandler&quot;);
// undefined constant, generates a warning
$t = I_AM_NOT_DEFINED;
// define some &quot;vectors&quot;
$a = array(2,3,&quot;foo&quot;);
$b = array(5.5, 4.3, -1.6);
$c = array (1,-3);
// generate a user error
$t1 = distance($c,$b).&quot;\n&quot;;
// generate another user error
$t2 = distance($b,&quot;i am not an array&quot;).&quot;\n&quot;;
// generate a warning
$t3 = distance($a,$b).&quot;\n&quot;;
?&gt;
</programlisting>
</example>
This is just a simple example showing how to use the
<link linkend="ref.errorfunc">Error Handling and Logging
functions</link>.
</para>
<para>
See also <function>error_reporting</function>,
<function>error_log</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>,
<function>trigger_error</function>,
<function>user_error</function>
</para>
</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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

125
features/http-auth.xml Normal file
View file

@ -0,0 +1,125 @@
<chapter id="features.http-auth">
<title>HTTP authentication with PHP</title>
<simpara>
The HTTP Authentication hooks in PHP are only available when it is
running as an Apache module and is hence not available in the CGI version.
In an Apache module PHP script, it is possible to use the
<function>Header</function> function to send an "Authentication Required"
message to the client browser causing it to pop up a Username/Password
input window. Once the user has filled in a username and a password,
the URL containing the PHP script will be called again with the variables,
$PHP_AUTH_USER, $PHP_AUTH_PW and $PHP_AUTH_TYPE set to the user
name, password and authentication type respectively. Only "Basic"
authentication is supported at this point. See the <function>Header</function>
function for more information.</simpara>
<para>
An example script fragment which would force client authentication
on a page would be the following:
<example>
<title>HTTP Authentication example</title>
<programlisting role="php">
&lt;?php
if(!isset($PHP_AUTH_USER)) {
Header(&quot;WWW-Authenticate: Basic realm=\&quot;My Realm\&quot;&quot;);
Header(&quot;HTTP/1.0 401 Unauthorized&quot;);
echo &quot;Text to send if user hits Cancel button\n&quot;;
exit;
} else {
echo &quot;Hello $PHP_AUTH_USER.&lt;P&gt;&quot;;
echo &quot;You entered $PHP_AUTH_PW as your password.&lt;P&gt;&quot;;
}
?>
</programlisting>
</example></para>
<para>
Instead of simply printing out the $PHP_AUTH_USER and
$PHP_AUTH_PW, you would probably want to check the username and
password for validity. Perhaps by sending a query to a database,
or by looking up the user in a dbm file.</para>
<para>
Watch out for buggy Internet Explorer browsers out there. They
seem very picky about the order of the headers. Sending the
<emphasis>WWW-Authenticate</emphasis> header before the
<errorcode>HTTP/1.0 401</errorcode> header seems to do the trick
for now.</para>
<simpara>
In order to prevent someone from writing a script which reveals
the password for a page that was authenticated through a
traditional external mechanism, the PHP_AUTH variables will not be
set if external authentication is enabled for that particular
page. In this case, the $REMOTE_USER variable can be used to
identify the externally-authenticated user.</simpara>
<simpara>
Note, however, that the above does not prevent someone who
controls a non-authenticated URL from stealing passwords from
authenticated URLs on the same server.</simpara>
<simpara>
Both Netscape and Internet Explorer will clear the local browser
window's authentication cache for the realm upon receiving a
server response of 401. This can effectively "log out" a user,
forcing them to re-enter their username and password. Some people
use this to "time out" logins, or provide a "log-out" button.</simpara>
<simpara></simpara>
<example>
<title>HTTP Authentication example forcing a new name/password</title>
<programlisting role="php">
&lt;?php
function authenticate() {
Header( &quot;WWW-authenticate: basic realm=\&quot;Test Authentication System\&quot;&quot;);
Header( &quot;HTTP/1.0 401 Unauthorized&quot;);
echo &quot;You must enter a valid login ID and password to access this resource\n&quot;;
exit;
}
if(!isset($PHP_AUTH_USER) || ($SeenBefore == 1 &amp;&amp; !strcmp($OldAuth, $PHP_AUTH_USER)) ) {
authenticate();
}
else {
echo &quot;Welcome: $PHP_AUTH_USER&lt;BR&gt;&quot;;
echo &quot;Old: $OldAuth&quot;;
echo &quot;&lt;FORM ACTION=\&quot;$PHP_SELF\&quot; METHOD=POST&gt;\n&quot;;
echo &quot;&lt;INPUT TYPE=HIDDEN NAME=\&quot;SeenBefore\&quot; VALUE=\&quot;1\&quot;&gt;\n&quot;;
echo &quot;&lt;INPUT TYPE=HIDDEN NAME=\&quot;OldAuth\&quot; VALUE=\&quot;$PHP_AUTH_USER\&quot;&gt;\n&quot;;
echo &quot;&lt;INPUT TYPE=Submit VALUE=\&quot;Re Authenticate\&quot;&gt;\n&quot;;
echo &quot;&lt;/FORM&gt;\n&quot;;
}
?>
</programlisting>
</example>
<simpara>
This behavior is not required by the HTTP Basic authentication
standard, so you should never depend on this. Testing with Lynx
has shown that Lynx does not clear the authentication credentials
with a 401 server response, so pressing back and then forward
again will open the resource (as long as the credential
requirements haven't changed).</simpara>
<simpara>
Also note that this does not work using Microsoft's IIS server and
the CGI version of PHP due to a limitation of IIS.</simpara>
</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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

59
features/images.xml Normal file
View file

@ -0,0 +1,59 @@
<chapter id="features.images">
<title>Creating and manipulating images</title>
<simpara>
PHP is not limited to creating just HTML output. It can also be
used to create and manipulate image files in a variety of different
image formats, including gif, png, jpg, wbmp, and xpm. Even more
convenient, php can output image streams directly to a browser. You
will need to compile PHP with the GD library of image functions for
this to work. GD and PHP may also require other libraries, depending
on which image formats you want to work with. GD stopped supporting
Gif images in version 1.6.
</simpara>
<para>
<example>
<title>PNG creation with PHP</title>
<programlisting role="php">
&lt;?php
Header("Content-type: image/png");
$string=implode($argv," ");
$im = imageCreateFromPng("images/button1.png");
$orange = ImageColorAllocate($im, 220, 210, 60);
$px = (imagesx($im)-7.5*strlen($string))/2;
ImageString($im,3,$px,9,$string,$orange);
ImagePng($im);
ImageDestroy($im);
?>
</programlisting>
</example>
This example would be called from a page with a tag like: &lt;img
src=&quot;button.php?text&quot;&gt; The above button.php script
then takes this &quot;text&quot; string an overlays it on top of a
base image which in this case is &quot;images/button1.png&quot;
and outputs the resulting image. This is a very convenient way to
avoid having to draw new button images every time you want to
change the text of a button. With this method they are
dynamically generated.
</para>
</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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->