cvs: /phpdoc/features connection-handling.sgml cookies.sgml error-handling.sgml file-upload.sgml http-auth.sgml images.sgml
persistent-connections.sgml remote-files.sgml

cslawi Wed Oct 20 18:54:02 1999 EDT Modified files: /phpdoc/features connection-handling.sgml cookies.sgml error-handling.sgml file-upload.sgml http-auth.sgml images.sgml persistent-connections.sgml remote-files.sgml Log: Normalized according to the DocBook 3.1 DTD. This mostly just adds closing tags and attribute quotes, but lets a stock 3.1 install compile the PHP docs. It still compiles with DocBook 3.0, as well. Index: phpdoc/features/connection-handling.sgml diff -u phpdoc/features/connection-handling.sgml:1.1 phpdoc/features/connection-handling.sgml:1.2 --- phpdoc/features/connection-handling.sgml:1.1 Sat Jun 19 21:21:16 1999 +++ phpdoc/features/connection-handling.sgml Wed Oct 20 18:54:01 1999 @@ -9,9 +9,9 @@ Internally in PHP a connection status is maintained. There are 3 possible states: <itemizedlist> - <listitem><simpara>0 - NORMAL - <listitem><simpara>1 - ABORTED - <listitem><simpara>2 - TIMEOUT + <listitem><simpara>0 - NORMAL</simpara></listitem> + <listitem><simpara>1 - ABORTED</simpara></listitem> + <listitem><simpara>2 - TIMEOUT</simpara></listitem> </itemizedlist> </para> @@ -21,7 +21,7 @@ turned on. A remote client disconnect is usually caused by the user hitting his STOP button. If the PHP-imposed time limit (see <function>set_time_limit</function>) is hit, the TIMEOUT state flag - is turned on. + is turned on.</simpara> <simpara> You can decide whether or not you want a client disconnect to cause @@ -42,7 +42,7 @@ terminating normally, so to do something different in case of a client diconnect you can use the <function>connection_aborted</function> function. This function will return true if the connection was - aborted. + aborted.</simpara> <simpara> Your script can also be terminated by the built-in script timer. @@ -55,7 +55,7 @@ be called. Within this shutdown function you can check to see if a timeout caused the shutdown function to be called by calling the <function>connection_timeout</function> function. This function will - return true if a timeout caused the shutdown function to be called. + return true if a timeout caused the shutdown function to be called.</simpara> <simpara> One thing to note is that both the ABORTED and the TIMEOUT states @@ -69,7 +69,7 @@ You can also check both states in a single call by using the <function>connection_status</function>. This function returns a bitfield of the active states. So, if both states are active it - would return 3, for example. + would return 3, for example.</simpara> </chapter> Index: phpdoc/features/cookies.sgml diff -u phpdoc/features/cookies.sgml:1.1 phpdoc/features/cookies.sgml:1.2 --- phpdoc/features/cookies.sgml:1.1 Sat Jun 19 21:21:16 1999 +++ phpdoc/features/cookies.sgml Wed Oct 20 18:54:01 1999 @@ -8,14 +8,14 @@ <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. + <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. + the <function>setcookie</function> function.</para> </chapter> Index: phpdoc/features/error-handling.sgml diff -u phpdoc/features/error-handling.sgml:1.1 phpdoc/features/error-handling.sgml:1.2 --- phpdoc/features/error-handling.sgml:1.1 Sat Jun 19 21:21:16 1999 +++ phpdoc/features/error-handling.sgml Wed Oct 20 18:54:01 1999 @@ -5,12 +5,12 @@ There are 4 types of errors and warnings in PHP. They are: <itemizedlist> - <listitem><simpara>1 - Normal Function Errors - <listitem><simpara>2 - Normal Warnings - <listitem><simpara>4 - Parser Errors + <listitem><simpara>1 - Normal Function Errors</simpara></listitem> + <listitem><simpara>2 - Normal Warnings</simpara></listitem> + <listitem><simpara>4 - Parser Errors</simpara></listitem> <listitem><simpara>8 - Notices (warnings you can ignore but which - may imply a bug in your code) - </itemizedlist> + may imply a bug in your code)</simpara></listitem> + </itemizedlist></para> <simpara> The above 4 numbers are added up to define an error reporting @@ -19,7 +19,7 @@ php3.ini file with the error_reporting directive. It can also be set in your Apache httpd.conf file with the php3_error_reporting directive or lastly it may be set at runtime within a script using - the <function>error_reporting</function> function. + the <function>error_reporting</function> function.</simpara> <simpara> All <link linkend="expressions">PHP expressions</link> can also be called @@ -27,7 +27,7 @@ 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. + $php_errormsg.</simpara> </chapter> Index: phpdoc/features/file-upload.sgml diff -u phpdoc/features/file-upload.sgml:1.2 phpdoc/features/file-upload.sgml:1.3 --- phpdoc/features/file-upload.sgml:1.2 Sat Jul 31 21:23:47 1999 +++ phpdoc/features/file-upload.sgml Wed Oct 20 18:54:01 1999 @@ -16,9 +16,8 @@ <para> Note that PHP also supports PUT-method file uploads as used by - Netscape Composer and W3C's Amaya clients. See the <link - linkend="features.file-upload.put-method">PUT Method Support</link> - for more details. + Netscape Composer and W3C's Amaya clients. See the <link linkend="features.file-upload.put-method">PUT Method Support</link> + for more details.</para> <para> A file upload screen can be built by creating a special form which @@ -38,7 +37,7 @@ The _URL_ should point to a PHP file. The MAX_FILE_SIZE hidden field must precede the file input field and its value is the maximum filesize accepted. The value is in bytes. In this destination file, - the following variables will be defined upon a successful upload: + the following variables will be defined upon a successful upload:</para> <para> <itemizedlist> @@ -71,14 +70,14 @@ Note that the &quot;$userfile&quot; part of the above variables is whatever the name of the INPUT field of TYPE=file is in the upload form. In the above upload form example, we chose to call it - &quot;userfile&quot;. + &quot;userfile&quot;.</para> <simpara> Files will by default be stored in the server's default temporary directory. This can be changed by setting the environment variable <envar>TMPDIR</envar> in the environment in which PHP runs. Setting it using <function>putenv</function> from within a PHP script will - not work. + not work.</simpara> <simpara> The PHP script which receives the uploaded file should implement @@ -88,11 +87,11 @@ big. You could use the $file_type variable to throw away any files that didn't match a certain type criteria. Whatever the logic, you should either delete the file from the temporary - directory or move it elsewhere. + directory or move it elsewhere.</simpara> <simpara> The file will be deleted from the temporary directory at the end - of the request if it has not been moved away or renamed. + of the request if it has not been moved away or renamed.</simpara></sect1> <sect1 id="features.file-upload.common-pitfalls"> <title>Common Pitfalls</title> @@ -100,12 +99,12 @@ The MAX_FILE_SIZE item cannot specify a file size greater than the file size that has been set in the upload_max_filesize in the PHP3.ini file or the corresponding php3_upload_max_filesize Apache .conf directive. - The default is 2 Megabytes. + The default is 2 Megabytes.</simpara> <simpara> Please note that the CERN httpd seems to strip off everything starting at the first whitespace in the content-type mime header it gets from the client. As long as this is the case, CERN httpd - will not support the file upload feature. + will not support the file upload feature.</simpara> </sect1> <sect1 id="feature-fileupload.multiple"> @@ -114,10 +113,10 @@ It is possible to upload multiple files simultaneously and have the information organized automatically in arrays for you. To do so, you need to use the same array submission syntax in the - HTML form as you do with multiple selects and checkboxes: + HTML form as you do with multiple selects and checkboxes:</simpara> <note> <para> - Support for multiple file uploads was added in version 3.0.10. + Support for multiple file uploads was added in version 3.0.10.</para> </note> <para> @@ -131,7 +130,7 @@ &lt;input type=&quot;submit&quot; value=&quot;Send files&quot;&gt; &lt;/form&gt; </programlisting> - </example> + </example></para> <simpara> When the above form is submitted, the arrays <computeroutput>$userfile</computeroutput>, @@ -139,7 +138,7 @@ <computeroutput>$userfile_size</computeroutput> will be formed in the global scope (as well as in $HTTP_POST_VARS). Each of these will be a numerically indexed array of the appropriate values for the - submitted files. + submitted files.</simpara> <simpara> For instance, assume that the filenames @@ -150,7 +149,7 @@ <computeroutput>$userfile_name[1]</computeroutput> would contain the value <computeroutput>xwp.out</computeroutput>. Similarly, <computeroutput>$userfile_size[0]</computeroutput> would contain - <filename>review.html</filename>'s filesize, and so forth. + <filename>review.html</filename>'s filesize, and so forth.</simpara></sect1> <sect1 id="features.file-upload.put-method"> <title>PUT method support</title> @@ -210,7 +209,7 @@ (may vary on non-Apache web servers). This destination filename is the one that the remote client specified. You do not have to listen to this client. You could, for example, copy all uploaded files to - a special uploads directory. + a special uploads directory.</simpara></sect1> </chapter> Index: phpdoc/features/http-auth.sgml diff -u phpdoc/features/http-auth.sgml:1.1 phpdoc/features/http-auth.sgml:1.2 --- phpdoc/features/http-auth.sgml:1.1 Sat Jun 19 21:21:16 1999 +++ phpdoc/features/http-auth.sgml Wed Oct 20 18:54:01 1999 @@ -12,7 +12,7 @@ $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. + function for more information.</simpara> <para> An example script fragment which would force client authentication @@ -20,7 +20,7 @@ <example> <title>HTTP Authentication example</title> - <programlisting role=php> + <programlisting role="php"> &lt;?php if(!isset($PHP_AUTH_USER)) { Header(&quot;WWW-Authenticate: Basic realm=\&quot;My Realm\&quot;&quot;); @@ -33,20 +33,20 @@ } ?> </programlisting> - </example> + </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. + 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. + for now.</para> <simpara> In order to prevent someone from writing a script which reveals @@ -54,22 +54,22 @@ 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. + 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. + 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> + 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> + <programlisting role="php"> &lt;?php function authenticate() { Header( &quot;WWW-authenticate: basic realm='Test Authentication System'&quot;); @@ -100,10 +100,10 @@ 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). + 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. + the CGI version of PHP due to a limitation of IIS.</simpara> </chapter> Index: phpdoc/features/images.sgml diff -u phpdoc/features/images.sgml:1.1 phpdoc/features/images.sgml:1.2 --- phpdoc/features/images.sgml:1.1 Sat Jun 19 21:21:16 1999 +++ phpdoc/features/images.sgml Wed Oct 20 18:54:01 1999 @@ -11,7 +11,7 @@ <para> <example> <title>GIF creation with PHP</title> - <programlisting role=php> + <programlisting role="php"> &lt;?php Header("Content-type: image/gif"); $string=implode($argv," "); Index: phpdoc/features/persistent-connections.sgml diff -u phpdoc/features/persistent-connections.sgml:1.1 phpdoc/features/persistent-connections.sgml:1.2 --- phpdoc/features/persistent-connections.sgml:1.1 Sat Jun 19 21:49:47 1999 +++ phpdoc/features/persistent-connections.sgml Wed Oct 20 18:54:01 1999 @@ -8,7 +8,7 @@ connection (that remained open from earlier) - and if it exists, it uses it. If it does not exist, it creates the link. An 'identical' connection is a connection that was opened to the same host, with - the same username and the same password (where applicable). + the same username and the same password (where applicable).</simpara> <simpara> People who aren't thoroughly familiar with the way web servers work @@ -19,14 +19,14 @@ transaction efficently, and they don't do a whole lot of other things. In fact, to be extremely clear about the subject, persistent connections don't give you <emphasis>any</emphasis> functionality - that wasn't possible with their non-persistent brothers. + that wasn't possible with their non-persistent brothers.</simpara> <simpara> - Why? + Why?</simpara> <simpara> This has to do with the way web servers work. There are three ways - in which your web server can utilize PHP to generate web pages. + in which your web server can utilize PHP to generate web pages.</simpara> <simpara> The first method is to use PHP as a CGI "wrapper". When run this @@ -35,7 +35,7 @@ is destroyed after every request, any resources that it acquires (such as a link to an SQL database server) are closed when it is destroyed. In this case, you do not gain anything from trying to use - persistent connections -- they simply don't persist. + persistent connections -- they simply don't persist.</simpara> <simpara> The second, and most popular, method is to run PHP as a module in @@ -50,7 +50,7 @@ this case it make it so each child process only needs to connect to your SQL server the first time that it serves a page that makes us of such a connection. When another page then requires a connection to the - SQL server, it can reuse the connection that child established earlier. + SQL server, it can reuse the connection that child established earlier.</simpara> <simpara> The last method is to use PHP as a plug-in for a multithreaded web @@ -60,11 +60,11 @@ all allow PHP to be used as a plug-in on multithreaded servers like Netscape FastTrack, Microsoft's Internet Information Server (IIS), and O'Reilly's WebSite Pro. When this happens, the behavior will be - essentially the same as for the multiprocess model described before. + essentially the same as for the multiprocess model described before.</simpara> <simpara> If persistent connections don't have any added functionality, what - are they good for? + are they good for?</simpara> <simpara> The answer here is extremely simple -- efficiency. Persistent @@ -81,7 +81,7 @@ open persistent connection to the server. For example, if you had 20 different child processes that ran a script that made a persistent connection to your SQL server, you'd have 20 different connections - to the SQL server, one from each child. + to the SQL server, one from each child.</simpara> <simpara> An important summary. Persistent connections were designed to have @@ -89,7 +89,7 @@ <emphasis>always</emphasis> be able to replace persistent connections with non-persistent connections, and it won't change the way your script behaves. It <emphasis>may</emphasis> (and probably will) - change the efficiency of the script, but not its behavior! + change the efficiency of the script, but not its behavior!</simpara> </chapter> Index: phpdoc/features/remote-files.sgml diff -u phpdoc/features/remote-files.sgml:1.1 phpdoc/features/remote-files.sgml:1.2 --- phpdoc/features/remote-files.sgml:1.1 Sat Jul 31 19:39:49 1999 +++ phpdoc/features/remote-files.sgml Wed Oct 20 18:54:01 1999 @@ -12,14 +12,14 @@ <note> <para> You can't use remote files in <function>include</function> and - <function>require</function> statements on Windows. - </note> + <function>require</function> statements on Windows.</para> + </note></para> <para> For example, you can use this to open a file on a remote web server, parse the output for the data you want, and then use that data in a database query, or simply to output it in a style matching the rest - of your website. + of your website.</para> <para> <example> @@ -42,7 +42,7 @@ fclose($file); ?&gt; </programlisting> - </example> + </example></para> <para> You can also write to files on an FTP as long you connect as a user @@ -51,7 +51,7 @@ the username (and possibly password) within the URL, such as 'ftp://user:password@ftp.example.com/path/to/file'. (You can use the same sort of syntax to access files via HTTP when they require Basic - authentication.) + authentication.)</para> <para> <example> @@ -75,8 +75,8 @@ You might get the idea from the example above to use this technique to write to a remote log, but as mentioned above, you can only write to a new file using the URL fopen() wrappers. To do distributed logging - like that, you should take a look at <function>syslog</function>. - </note> + like that, you should take a look at <function>syslog</function>.</para> + </note></para> </chapter>