PHPBuilder.com, the best resource for PHP tutorials, templates, PHP manuals, content management systems, scripts, classes and more.

[PHP-DOC] cvs: phpdoc / lang-nl.ent manual.xml.in /nl bookinfo.xml chapters.ent preface.xml /nl/appendices debugger.xml escaping.xml history.xml http-stuff.xml migration.xml phpdevel.xml regexp.xml /nl/chapters config.xml copyright.xml install.xml intro.xml security.xml /nl/features connection-handling.xml cookies.xml error-handling.xml file-upload.xml http-auth.xml images.xml persistent-connections.xml remote-files.xml /nl/functions apache.xml array.xml aspell.xml bc.xml calendar.xml ccvs.xml classobj.xml com.xml cpdf.xml curl.xml cybercash.xml datetime.xml dba.xml dbase.xml dbm.xml dir.xml dl.xml domxml.xml errorfunc.xml exec.xml fdf.xml filepro.xml filesystem.xml ftp.xml funchand.xml gettext.xml http.xml hw.xml ibase.xml icap.xml ifx.xml image.xml imap.xml info.xml ldap.xml mail.xml math.xml mcal.xml mcrypt.xml mhash.xml misc.xml msql.xml mssql.xml mysql.xml network.xml nis.xml oci8.xml oracle.xml outcontrol.xml pcre.xml pdf.xml pfpro.xml pgsql.xml posix.xml pspell.xml readline.xml recode.xm From: Derick Rethans (d.rethans <email protected>)
Date: 10/10/00

derick Tue Oct 10 15:07:58 2000 EDT

  Added files:
    /phpdoc lang-nl.ent
    /phpdoc/nl bookinfo.xml chapters.ent preface.xml
    /phpdoc/nl/appendices debugger.xml escaping.xml history.xml
                                 http-stuff.xml migration.xml phpdevel.xml
                                 regexp.xml
    /phpdoc/nl/chapters config.xml copyright.xml install.xml intro.xml
                               security.xml
    /phpdoc/nl/features connection-handling.xml cookies.xml
                               error-handling.xml file-upload.xml
                               http-auth.xml images.xml
                               persistent-connections.xml remote-files.xml
    /phpdoc/nl/functions apache.xml array.xml aspell.xml bc.xml
                                calendar.xml ccvs.xml classobj.xml com.xml
                                cpdf.xml curl.xml cybercash.xml datetime.xml
                                dba.xml dbase.xml dbm.xml dir.xml dl.xml
                                domxml.xml errorfunc.xml exec.xml fdf.xml
                                filepro.xml filesystem.xml ftp.xml
                                funchand.xml gettext.xml http.xml hw.xml
                                ibase.xml icap.xml ifx.xml image.xml imap.xml
                                info.xml ldap.xml mail.xml math.xml mcal.xml
                                mcrypt.xml mhash.xml misc.xml msql.xml
                                mssql.xml mysql.xml network.xml nis.xml
                                oci8.xml oracle.xml outcontrol.xml pcre.xml
                                pdf.xml pfpro.xml pgsql.xml posix.xml
                                pspell.xml readline.xml recode.xml regex.xml
                                satellite.xml sem.xml session.xml shmop.xml
                                snmp.xml sockets.xml strings.xml swf.xml
                                sybase.xml uodbc.xml url.xml var.xml
                                vmailmgr.xml wddx.xml xml.xml yaz.xml zlib.xml
    /phpdoc/nl/language basic-syntax.xml constants.xml
                               control-structures.xml expressions.xml
                               functions.xml oop.xml operators.xml
                               references.xml types.xml variables.xml

  Modified files:
    /phpdoc manual.xml.in
  Log:
  - Added the Dutch translation tree


Index: phpdoc/manual.xml.in
diff -u phpdoc/manual.xml.in:1.31 phpdoc/manual.xml.in:1.32
--- phpdoc/manual.xml.in:1.31 Sun Oct 1 08:10:25 2000
+++ phpdoc/manual.xml.in Tue Oct 10 15:07:52 2000
@@ -35,6 +35,10 @@
<!ENTITY % language-defs SYSTEM "lang-fr.ent">
]]>

+<![%lang-nl;[
+<!ENTITY % language-defs SYSTEM "lang-nl.ent">
+]]>
+
<![%lang-pt-BR;[
<!ENTITY % language-defs SYSTEM "lang-pt_BR.ent">
]]>

Index: phpdoc/lang-nl.ent
+++ phpdoc/lang-nl.ent
<!ENTITY PHPManual "PHP Handleiding">
<!ENTITY Date "Datum:">
<!ENTITY GettingStarted "Om te beginnen">
<!ENTITY LanguageReference "Syntax">
<!ENTITY Features "Functionaliteit">
<!ENTITY FunctionReference "Functie naslag">
<!ENTITY Appendixes "Appendixes">

<!ENTITY % global.chapters SYSTEM "nl/chapters.ent">

<!ENTITY available "beschikbaar in">
Index: phpdoc/nl/bookinfo.xml
+++ phpdoc/nl/bookinfo.xml

   <author>
    <firstname>Stig</firstname><surname>S�ther Bakken</surname>
   </author>

   <author>
    <firstname>Alexander</firstname><surname>Aulbach</surname>
   </author>

   <author>
    <firstname>Egon</firstname><surname>Schmid</surname>
   </author>

   <author>
    <firstname>Jim</firstname><surname>Winstead</surname>
   </author>

   <author>
    <firstname>Lars Torben</firstname><surname>Wilson</surname>
   </author>

   <author>
    <firstname>Rasmus</firstname><surname>Lerdorf</surname>
   </author>

   <author>
    <firstname>Zeev</firstname><surname>Suraski</surname>
   </author>

   <author>
    <firstname>Andrei</firstname><surname>Zmievski</surname>
   </author>

</authorgroup>

  <pubdate>&php.build-date;</pubdate>

  <authorgroup id="editors">
   <editor>
    <firstname>Matthieu</firstname><surname>Koolman</surname>
   </editor>
   <editor>
    <firstname>Derick</firstname><surname>Rethans</surname>
   </editor>
  </authorgroup>

  <copyright>
   <year>1997</year>
   <year>1998</year>
   <year>1999</year>
   <year>2000</year>
   <holder>the PHP Documentation Group</holder>
  </copyright>

  <legalnotice id="copyright">
   <title>Copyright</title>
   <simpara>
    This manual is © Copyright 1997, 1998, 1999, 2000 by the PHP
    Documentation Group. The members of this group are listed <link
    linkend="authors">on the front page of this manual</link>.
   </simpara>
   <simpara>
    This manual can be redistributed under the terms of the GNU
    General Public License as published by the Free Software
    Foundation; either version 2 of the License, or (at your option)
    any later version.
   </simpara>
  </legalnotice>

</bookinfo>

Index: phpdoc/nl/chapters.ent
+++ phpdoc/nl/chapters.ent
<!ENTITY preface SYSTEM "preface.xml">
<!ENTITY bookinfo SYSTEM "bookinfo.xml">

<!ENTITY chapter.copyright SYSTEM "chapters/copyright.xml">
<!ENTITY chapter.introduction SYSTEM "chapters/intro.xml">
<!ENTITY chapter.install SYSTEM "chapters/install.xml">
<!ENTITY chapter.config SYSTEM "chapters/config.xml">
<!ENTITY chapter.security SYSTEM "chapters/security.xml">

<!ENTITY features.http-auth SYSTEM "features/http-auth.xml">
<!ENTITY features.cookies SYSTEM "features/cookies.xml">
<!ENTITY features.file-upload SYSTEM "features/file-upload.xml">
<!ENTITY features.remote-files SYSTEM "features/remote-files.xml">
<!ENTITY features.connection-handling SYSTEM "features/connection-handling.xml">
<!ENTITY features.error-handling SYSTEM "features/error-handling.xml">
<!ENTITY features.images SYSTEM "features/images.xml">
<!ENTITY features.persistent-connections SYSTEM "features/persistent-connections.xml">

<!ENTITY language.basic-syntax SYSTEM "language/basic-syntax.xml">
<!ENTITY language.types SYSTEM "language/types.xml">
<!ENTITY language.variables SYSTEM "language/variables.xml">
<!ENTITY language.constants SYSTEM "language/constants.xml">
<!ENTITY language.expressions SYSTEM "language/expressions.xml">
<!ENTITY language.operators SYSTEM "language/operators.xml">
<!ENTITY language.functions SYSTEM "language/functions.xml">
<!ENTITY language.control-structures SYSTEM "language/control-structures.xml">
<!ENTITY language.oop SYSTEM "language/oop.xml">
<!ENTITY language.references SYSTEM "language/references.xml">

<!ENTITY reference.apache SYSTEM "functions/apache.xml">
<!ENTITY reference.array SYSTEM "functions/array.xml">
<!ENTITY reference.aspell SYSTEM "functions/aspell.xml">
<!ENTITY reference.bc SYSTEM "functions/bc.xml">
<!ENTITY reference.calendar SYSTEM "functions/calendar.xml">
<!ENTITY reference.ccvs SYSTEM "functions/ccvs.xml">
<!ENTITY reference.classobj SYSTEM "functions/classobj.xml">
<!ENTITY reference.com SYSTEM "functions/com.xml">
<!ENTITY reference.cpdf SYSTEM "functions/cpdf.xml">
<!ENTITY reference.curl SYSTEM "functions/curl.xml">
<!ENTITY reference.cybercash SYSTEM "functions/cybercash.xml">
<!ENTITY reference.datetime SYSTEM "functions/datetime.xml">
<!ENTITY reference.dba SYSTEM "functions/dba.xml">
<!ENTITY reference.dbase SYSTEM "functions/dbase.xml">
<!ENTITY reference.dbm SYSTEM "functions/dbm.xml">
<!ENTITY reference.dir SYSTEM "functions/dir.xml">

<!ENTITY reference.domxml SYSTEM "functions/domxml.xml">
<!ENTITY reference.errorfunc SYSTEM "functions/errorfunc.xml">
<!ENTITY reference.exec SYSTEM "functions/exec.xml">
<!ENTITY reference.fdf SYSTEM "functions/fdf.xml">
<!ENTITY reference.filepro SYSTEM "functions/filepro.xml">
<!ENTITY reference.filesystem SYSTEM "functions/filesystem.xml">
<!ENTITY reference.ftp SYSTEM "functions/ftp.xml">
<!ENTITY reference.funchand SYSTEM "functions/funchand.xml">
<!ENTITY reference.gettext SYSTEM "functions/gettext.xml">
<!ENTITY reference.http SYSTEM "functions/http.xml">
<!ENTITY reference.hw SYSTEM "functions/hw.xml">
<!ENTITY reference.ibase SYSTEM "functions/ibase.xml">
<!ENTITY reference.icap SYSTEM "functions/icap.xml">
<!ENTITY reference.ifx SYSTEM "functions/ifx.xml">
<!ENTITY reference.image SYSTEM "functions/image.xml">
<!ENTITY reference.imap SYSTEM "functions/imap.xml">
<!ENTITY reference.info SYSTEM "functions/info.xml">
<!ENTITY reference.ldap SYSTEM "functions/ldap.xml">
<!ENTITY reference.mail SYSTEM "functions/mail.xml">
<!ENTITY reference.math SYSTEM "functions/math.xml">
<!ENTITY reference.mcal SYSTEM "functions/mcal.xml">
<!ENTITY reference.mcrypt SYSTEM "functions/mcrypt.xml">
<!ENTITY reference.mhash SYSTEM "functions/mhash.xml">
<!ENTITY reference.misc SYSTEM "functions/misc.xml">
<!ENTITY reference.msql SYSTEM "functions/msql.xml">
<!ENTITY reference.mssql SYSTEM "functions/mssql.xml">
<!ENTITY reference.mysql SYSTEM "functions/mysql.xml">
<!ENTITY reference.network SYSTEM "functions/network.xml">
<!ENTITY reference.nis SYSTEM "functions/nis.xml">
<!ENTITY reference.oci8 SYSTEM "functions/oci8.xml">
<!ENTITY reference.oracle SYSTEM "functions/oracle.xml">
<!ENTITY reference.outcontrol SYSTEM "functions/outcontrol.xml">
<!ENTITY reference.pcre SYSTEM "functions/pcre.xml">
<!ENTITY reference.pdf SYSTEM "functions/pdf.xml">
<!ENTITY reference.pfpro SYSTEM "functions/pfpro.xml">
<!ENTITY reference.pgsql SYSTEM "functions/pgsql.xml">
<!ENTITY reference.posix SYSTEM "functions/posix.xml">
<!ENTITY reference.pspell SYSTEM "functions/pspell.xml">
<!ENTITY reference.readline SYSTEM "functions/readline.xml">
<!ENTITY reference.recode SYSTEM "functions/recode.xml">
<!ENTITY reference.regex SYSTEM "functions/regex.xml">
<!ENTITY reference.satellite SYSTEM "functions/satellite.xml">
<!ENTITY reference.sem SYSTEM "functions/sem.xml">
<!ENTITY reference.session SYSTEM "functions/session.xml">
<!ENTITY reference.shmop SYSTEM "functions/shmop.xml">
<!ENTITY reference.snmp SYSTEM "functions/snmp.xml">
<!ENTITY reference.sockets SYSTEM "functions/sockets.xml">
<!ENTITY reference.strings SYSTEM "functions/strings.xml">
<!ENTITY reference.swf SYSTEM "functions/swf.xml">
<!ENTITY reference.sybase SYSTEM "functions/sybase.xml">
<!ENTITY reference.uodbc SYSTEM "functions/uodbc.xml">
<!ENTITY reference.url SYSTEM "functions/url.xml">
<!ENTITY reference.var SYSTEM "functions/var.xml">
<!ENTITY reference.vmailmgr SYSTEM "functions/vmailmgr.xml">
<!ENTITY reference.wddx SYSTEM "functions/wddx.xml">
<!ENTITY reference.xml SYSTEM "functions/xml.xml">
<!ENTITY reference.yaz SYSTEM "functions/yaz.xml">
<!ENTITY reference.zlib SYSTEM "functions/zlib.xml">

<!ENTITY appendix.migration SYSTEM "appendices/migration.xml">
<!ENTITY appendix.development SYSTEM "appendices/phpdevel.xml">
<!ENTITY appendix.debugger SYSTEM "appendices/debugger.xml">

Index: phpdoc/nl/preface.xml
+++ phpdoc/nl/preface.xml

<preface id="preface">
<title>Preface</title>

  <abstract>
   <simpara>
    <acronym>PHP</acronym>, which stands for "PHP: Hypertext
    Preprocessor", is an HTML-embedded scripting language. Much
    of its syntax is borrowed from C, Java and Perl with a couple of
    unique PHP-specific features thrown in. The goal of the language
    is to allow web developers to write dynamically generated pages
    quickly.
   </simpara>
  </abstract>

  <sect1 id="about">
   <title>About this Manual</title>
   <para>
    This manual is written in <acronym>XML</acronym> using the <ulink
     url="&url.docbook.xml;">DocBook XML DTD</ulink>, using <ulink
     url="&url.dsssl;"><acronym>DSSSL</acronym></ulink> (Document
     Style and Semantics Specification Language) for formatting. The
     tools used for formatting <acronym>HTML</acronym>,
     <acronym>TeX</acronym> and <acronym>RTF</acronym> versions are
     <ulink url="&url.jade;">Jade</ulink>, written by <ulink
     url="&url.jclark;">James Clark</ulink> and <ulink
     url="&url.dbstyle;">The Modular DocBook Stylesheets</ulink>
     written by <ulink url="&url.nwalsh;">Norman Walsh</ulink>.
     PHP's documentation framework is maintained by &link.stig;.
   </para>
   <para>
    Daily HTML snapshots of the manual, including translations, can be
    found at <ulink
    url="&url.php.snaps.manual;">&url.php.snaps.manual;</ulink>.
   </para>
  </sect1>

</preface>

Index: phpdoc/nl/appendices/debugger.xml
+++ phpdoc/nl/appendices/debugger.xml
<appendix id="debugger">
<title>The PHP Debugger</title>

<sect1 id="debugger-using">
<title>Using the Debugger</title>

   <para>
    PHP's internal debugger is useful for tracking down evasive bugs.
    The debugger works by connecting to a <acronym>TCP</acronym> port
    for every time PHP starts up. All error messages from that
    request will be sent to this TCP connection. This information is
    intended for "debugging server" that can run inside an
    <acronym>IDE</acronym> or programmable editor (such as Emacs).
   </para>
   <para>
    How to set up the debugger:
    <orderedlist>
     <listitem>
      <simpara>
       Set up a TCP port for the debugger in the <link
       linkend="configuration.file">configuration file</link> (<link
       linkend="ini.debugger.port">debugger.port</link>) and enable it
       (<link linkend="ini.debugger.enabled">debugger.enabled</link>).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Set up a TCP listener on that port somewhere (for example
       <command>socket -l -s 1400</command> on UNIX).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       In your code, run
       "debugger_on(<replaceable>host</replaceable>)", where
       <replaceable>host</replaceable> is the IP number or name of the
       host running the <acronym>TCP</acronym> listener.
      </simpara>
     </listitem>
    </orderedlist>
    Now, all warnings, notices etc. will show up on that listener
    socket, <emphasis>even if you them turned off with
    <function>error_reporting</function></emphasis>.
   </para>
   <note>
    <para>
         The code for the debugger has not been ported to PHP 4, at the
         present time only PHP 3 supports the debugger code.
        </para>
   </note>
  </sect1>

  <sect1 id="debugger-protocol">
   <title>Debugger Protocol</title>
   <para>
    The debugger protocol is line-based. Each line has a
    <emphasis>type</emphasis>, and several lines compose a
    <emphasis>message</emphasis>. Each message starts with a line of
    the type <literal>start</literal> and terminates with a line of
    the type <literal>end</literal>. PHP may send lines for different
    messages simultaneously.
   </para>
   <para>
    A line has this format:
    <informalexample>
     <literallayout>
<replaceable>date</replaceable> <replaceable>time</replaceable>
<replaceable>host</replaceable>(<replaceable>pid</replaceable>)
<replaceable>type</replaceable>:
<replaceable>message-data</replaceable>
     </literallayout>
    </informalexample>
    <variablelist>
     <varlistentry>
      <term><replaceable>date</replaceable></term>
      <listitem>
       <simpara>
        Date in ISO 8601 format
        (<replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>)
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>time</replaceable></term>
      <listitem>
       <simpara>Time including microseconds:
        <replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>uuuuuu</replaceable>
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>host</replaceable></term>
      <listitem>
       <simpara>
        DNS name or IP address of the host where the script error was
        generated.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>pid</replaceable></term>
      <listitem>
       <simpara>
        PID (process id) on <replaceable>host</replaceable> of the
        process with the PHP script that generated this error.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>type</replaceable></term>
      <listitem>
       <para>
        Type of line. Tells the receiving program about what it
        should treat the following data as:
        <table>
         <title>Debugger Line Types</title>
         <tgroup cols="2">
          <thead>
           <row>
            <entry>Name</entry>
            <entry>Meaning</entry>
           </row>
          </thead>
          <tbody>
           <row>
            <entry><literal>start</literal></entry>
            <entry>
             Tells the receiving program that a debugger message
             starts here. The contents of
             <replaceable>data</replaceable> will be the type of error
             message, listed below.
            </entry>
           </row>
           <row>
            <entry><literal>message</literal></entry>
            <entry>The PHP error message.</entry>
           </row>
           <row>
            <entry><literal>location</literal></entry>
            <entry>
             File name and line number where the error occured. The
             first <literal>location</literal> line will always
             contain the top-level location.
             <replaceable>data</replaceable> will contain
             <literal><replaceable>file</replaceable>:<replaceable>line</replaceable></literal>.
             There will always be a <literal>location</literal> line
             after <literal>message</literal> and after every
             <literal>function</literal>.
            </entry>
           </row>
           <row>
            <entry>
             <literal>frames</literal></entry> <entry>Number of frames
             in the following stack dump. If there are four frames,
             expect information about four levels of called functions.
             If no "frames" line is given, the depth should be assumed
             to be 0 (the error occured at top-level).
            </entry>
           </row>
           <row>
            <entry>
             <literal>function</literal></entry>
            <entry>
             Name of function where the error occured. Will be
             repeated once for every level in the function call
             stack.
            </entry>
           </row>
           <row>
            <entry><literal>end</literal></entry>
            <entry>
             Tells the receiving program that a debugger message ends
             here.
            </entry>
           </row>
          </tbody>
         </tgroup>
        </table>
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable>data</replaceable></term>
      <listitem>
       <simpara>Line data.</simpara>
      </listitem>
     </varlistentry>
    </variablelist>

    <table>
     <title>Debugger Error Types</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Debugger</entry>
        <entry>PHP Internal</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><errortype>warning</errortype></entry>
        <entry><errortype>E_WARNING</errortype></entry>
       </row>
       <row>
        <entry><errortype>error</errortype></entry>
        <entry><errortype>E_ERROR</errortype></entry>
       </row>
       <row>
        <entry><errortype>parse</errortype></entry>
        <entry><errortype>E_PARSE</errortype></entry>
       </row>
       <row>
        <entry><errortype>notice</errortype></entry>
        <entry><errortype>E_NOTICE</errortype></entry>
       </row>
       <row>
        <entry><errortype>core-error</errortype></entry>
        <entry><errortype>E_CORE_ERROR</errortype></entry>
       </row>
       <row>
        <entry><errortype>core-warning</errortype></entry>
        <entry><errortype>E_CORE_WARNING</errortype></entry>
       </row>
       <row>
        <entry><errortype>unknown</errortype></entry>
        <entry>(any other)</entry>
       </row>
      </tbody>
     </tgroup>
    </table>

    <example>
     <title>Example Debugger Message</title>
     <literallayout>
1998-04-05 23:27:400966 lucifer.guardian.no(20481) start: notice
1998-04-05 23:27:400966 lucifer.guardian.no(20481) message: Uninitialized variable
1998-04-05 23:27:400966 lucifer.guardian.no(20481) location: (null):7
1998-04-05 23:27:400966 lucifer.guardian.no(20481) frames: 1
1998-04-05 23:27:400966 lucifer.guardian.no(20481) function: display
1998-04-05 23:27:400966 lucifer.guardian.no(20481) location: /home/ssb/public_html/test.php3:10
1998-04-05 23:27:400966 lucifer.guardian.no(20481) end: notice
     </literallayout>
    </example>
   </para>
  </sect1>

</appendix>

Index: phpdoc/nl/appendices/escaping.xml
+++ phpdoc/nl/appendices/escaping.xml
<chapt>Escaping data
  <sect>PHP string escape chars
  <sect>URL encoding (GET)
  <sect>POST method
  <sect>Escaping for databases

Index: phpdoc/nl/appendices/history.xml
+++ phpdoc/nl/appendices/history.xml
<chapt>PHP's history
<sect>Overview of PHP's development

Index: phpdoc/nl/appendices/http-stuff.xml
+++ phpdoc/nl/appendices/http-stuff.xml
<chapt>Proxies, caching and misc. HTTP stuff
  <sect>Setting an expiry date on generated pages
  <sect>Using phpLastModified
  <sect>CGI version: why does images break (w/solution)

Index: phpdoc/nl/appendices/migration.xml
+++ phpdoc/nl/appendices/migration.xml
<appendix id="migration">
<title>Migrating from PHP/FI 2.0 to PHP 3.0</title>

<sect1 id="migration-about">
  <title>About the incompatbilities in 3.0</title>
  <simpara>
   PHP 3.0 is rewritten from the ground up. It has a proper parser
   that is much more robust and consistent than 2.0's. 3.0 is also
   significantly faster, and uses less memory. However, some of
   these improvements have not been possible without compatibility
   changes, both in syntax and functionality.</simpara>

  <simpara>
   In addition, PHP's developers have tried to clean up both PHP's
   syntax and semantics in version 3.0, and this has also caused some
   incompatibilities. In the long run, we believe that these changes
   are for the better.</simpara>

  <simpara>
   This chapter will try to guide you through the incompatibilities
   you might run into when going from PHP/FI 2.0 to PHP 3.0 and help
   you resolve them. New features are not mentioned here unless
   necessary.</simpara>

  <simpara>
   A conversion program that can automatically convert your old
   PHP/FI 2.0 scripts exists. It can be found in the <filename class="directory">convertor</filename> subdirectory of the PHP 3.0
   distribution. This program only catches the syntax changes though,
   so you should read this chapter carefully anyway.</simpara></sect1>

<sect1 id="migration-startendtags">
<title>Start/end tags</title>

  <para>
   The first thing you probably will notice is that PHP's start and end
   tags have changed. The old <literal><? ></literal> form has been
   replaced by three new possible forms:
   <example>
    <title>Migration: old start/end tags</title>
    <programlisting>
<? echo "This is PHP/FI 2.0 code.\n"; >
</programlisting></example>

As of version 2.0, PHP/FI also supports this variation:

<example><title>Migration: first new start/end tags</title>
<programlisting>
<? echo "This is PHP 3.0 code!\n"; ?>
</programlisting></example>

   Notice that the end tag now consists of a question mark and a
   greater-than character instead of just greater-than. However, if
   you plan on using XML on your server, you will get problems with
   the first new variant, because PHP may try to execute the XML
   markup in XML documents as PHP code. Because of this, the
   following variation was introduced:

<example><title>Migration: second new start/end tags</title>
<programlisting>
<?php echo "This is PHP 3.0 code!\n"; ?>
</programlisting></example>

   Some people have had problems with editors that don't understand
   the processing instruction tags at all. Microsoft FrontPage is one
   such editor, and as a workaround for these, the following variation
   was introduced as well:

<example><title>Migration: third new start/end tags</title>
<programlisting>
<script language="php">

echo "This is PHP 3.0 code!\n";

</script>
</programlisting></example></para></sect1>

<sect1 id="migration-if-endif">
<title>if..endif syntax</title>

  <para>
   The `alternative' way to write if/elseif/else statements, using if();
   elseif(); else; endif; cannot be efficiently implemented without
   adding a large amount of complexity to the 3.0 parser. Because of
   this, the syntax has been changed:
   <example>
    <title>Migration: old if..endif syntax</title>
    <programlisting>
if ($foo);
    echo "yep\n";
elseif ($bar);
    echo "almost\n";
else;
    echo "nope\n";
endif;
</programlisting></example>
   <example>
    <title>Migration: new if..endif syntax</title>
    <programlisting>
if ($foo):
    echo "yep\n";
elseif ($bar):
    echo "almost\n";
else:
    echo "nope\n";
endif;
</programlisting></example>

Notice that the semicolons have been replaced by colons in all
statements but the one terminating the expression (endif).</para></sect1>

<sect1 id="migration-while">
  <title>while syntax</title>
  <para>
   Just like with if..endif, the syntax of while..endwhile has changed
   as well:
   <example><title>Migration: old while..endwhile syntax</title>
   <programlisting>
while ($more_to_come);
    ...
endwhile;
</programlisting></example>
   <example><title>Migration: new while..endwhile syntax</title>
   <programlisting>
while ($more_to_come):
    ...
endwhile;
</programlisting></example>
  </para>
  <warning>
   <simpara>
    If you use the old while..endwhile syntax in PHP 3.0, you will get
    a never-ending loop.
   </simpara>
  </warning></sect1>

<sect1 id="migration-expr">
  <title>Expression types</title>
  <simpara>
   PHP/FI 2.0 used the left side of expressions to determine what type
   the result should be. PHP 3.0 takes both sides into account when
   determining result types, and this may cause 2.0 scripts to behave
   unexpectedly in 3.0.</simpara>
  <simpara></simpara>

  <para>
   Consider this example:
   <informalexample><programlisting>
$a[0]=5;
$a[1]=7;

$key = key($a);
while ("" != $key) {
echo "$keyn";
next($a);
}
</programlisting></informalexample>

   In PHP/FI 2.0, this would display both of $a's indices. In PHP
   3.0, it wouldn't display anything. The reason is that in PHP 2.0,
   because the left argument's type was string, a string comparison
   was made, and indeed <literal>""</literal> does not equal
   <literal>"0"</literal>, and the loop went through. In PHP 3.0,
   when a string is compared with an integer, an integer comparison is
   made (the string is converted to an integer). This results in
   comparing <literal>atoi("")</literal> which is
   <literal>0</literal>, and <literal>variablelist</literal> which is
   also <literal>0</literal>, and since <literal>0==0</literal>, the
   loop doesn't go through even once.

  </para>
  <para>
   The fix for this is simple. Replace the while statement with:
   <informalexample><programlisting>
while ((string)$key != "") {
</programlisting></informalexample></para></sect1>

<sect1 id="migration-errors">
  <title>Error messages have changed</title>
  <simpara>
   PHP 3.0's error messages are usually more accurate than 2.0's were,
   but you no longer get to see the code fragment causing the error.
   You will be supplied with a file name and a line number for the
   error, though.
  </simpara></sect1>

<sect1 id="migration-booleval">
  <title>Short-circuited boolean evaluation</title>
  <simpara>
   In PHP 3.0 boolean evaluation is short-circuited. This means that
   in an expression like <literal>(1 || test_me())</literal>, the
   function <function>test_me</function> would not be executed since
   nothing can change the result of the expression after the
   <literal>1</literal>.</simpara>

  <simpara>
   This is a minor compatibility issue, but may cause unexpected
   side-effects.</simpara></sect1>

<sect1 id="migration-truefalse">
  <title>Function true/false return values</title>
  <simpara>
   Most internal functions have been rewritten so they return TRUE
   when successful and FALSE when failing, as opposed to 0 and -1 in
   PHP/FI 2.0, respectively. The new behaviour allows for more
   logical code, like <literal>$fp = fopen("/your/file") or
    fail("darn!");</literal>. Because PHP/FI 2.0 had no clear rules
   for what functions should return when they failed, most such
   scripts will probably have to be checked manually after using the
   2.0 to 3.0 convertor.</simpara>
  <para>
   <example>
    <title>Migration from 2.0: return values, old code</title>
    <programlisting>
$fp = fopen($file, "r");
if ($fp == -1);
    echo("Could not open $file for reading<br>\n");
endif;
</programlisting>
   </example>
   <example>
    <title>Migration from 2.0: return values, new code</title>
    <programlisting>
$fp = <email protected>($file, "r") or print("Could not open $file for reading<br>\n");
</programlisting>
   </example></para></sect1>

<sect1 id="migration-other">
<title>Other incompatibilities</title>

   <itemizedlist>
    <listitem><simpara>
      The PHP 3.0 Apache module no longer supports Apache versions
      prior to 1.2. Apache 1.2 or later is required.</simpara></listitem>

    <listitem><simpara> <function>echo</function> no longer
    supports a format string. Use the
    <function>printf</function> function instead.</simpara></listitem>

    <listitem><simpara>
      In PHP/FI 2.0, an implementation side-effect caused
      <literal>$foo[0]</literal> to have the same effect as
      <literal>$foo</literal>. This is not true for PHP 3.0.</simpara></listitem>

    <listitem><simpara>
      Reading arrays with <literal>$array[]</literal> is no longer
      supported</simpara>

     <simpara>
      That is, you cannot traverse an array by having a loop that does
      <literal>$data = $array[]</literal>. Use
      <function>current</function> and <function>next</function>
      instead.</simpara>
     <simpara>
      Also, <literal>$array1[] = $array2</literal> does not append the
      values of <literal>$array2</literal> to <literal>$array1</literal>,
      but appends <literal>$array2</literal> as the last entry of
      <literal>$array1</literal>. See also multidimensional array
      support.</simpara></listitem>

    <listitem>
     <simpara> <literal>"+"</literal> is no longer overloaded as a
     concatenation operator for strings, instead it converts it's
     arguments to numbers and performs numeric addition. Use
     <literal>"."</literal> instead.</simpara></listitem>
   </itemizedlist>

        <example>
          <title>Migration from 2.0: concatenation for strings</title>
          <programlisting>
echo "1" + "1";
</programlisting>

         <para>
          In PHP 2.0 this would echo 11, in PHP 3.0 it would echo 2. Instead
          use:

<para>
This would echo 2 in both PHP 2.0 and 3.0.

</appendix>

Index: phpdoc/nl/appendices/phpdevel.xml
+++ phpdoc/nl/appendices/phpdevel.xml
<appendix id="phpdevel">
<title>PHP development</title>

<sect1 id="phpdevel-addfunc">
  <title>Adding functions to PHP 3</title>
  <sect2 id="phpdevel-addfunc-prototype">
   <title>Function Prototype</title>
   <para>
    All functions look like this:
    <programlisting>
void php3_foo(INTERNAL_FUNCTION_PARAMETERS) {

}
    </programlisting>
    Even if your function doesn't take any arguments, this is how it is
    called.</para></sect2>

  <sect2 id="phpdevel-addfunc-args">
   <title>Function Arguments</title>
   <para>
    Arguments are always of type pval. This type contains a union
    which has the actual type of the argument. So, if your function
    takes two arguments, you would do something like the following at
    the top of your function:</para>

   <para>
    <example>
     <title>Fetching function arguments</title>
     <programlisting>
pval *arg1, *arg2;
if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) {
   WRONG_PARAM_COUNT;
}
     </programlisting>
    </example>

    NOTE: Arguments can be passed either by value or by reference. In
    both cases you will need to pass &(pval *) to getParameters. If
    you want to check if the n'th parameter was sent to you by
    reference or not, you can use the function,
    ParameterPassedByReference(ht,n). It will return either 1 or 0.</para>

   <simpara>
    When you change any of the passed parameters, whether they are
    sent by reference or by value, you can either start over with the
    parameter by calling pval_destructor on it, or if it's an ARRAY
    you want to add to, you can use functions similar to the ones in
    internal_functions.h which manipulate return_value as an ARRAY.</simpara>

   <simpara>
    Also if you change a parameter to IS_STRING make sure you first
    assign the new estrdup()'ed string and the string length, and only
    later change the type to IS_STRING. If you change the string of a
    parameter which already IS_STRING or IS_ARRAY you should run
    pval_destructor on it first.</simpara></sect2>

  <sect2 id="phpdevel-addfunc-varargs">
   <title>Variable Function Arguments</title>
   <para>
    A function can take a variable number of arguments. If your function can
    take either 2 or 3 arguments, use the following:</para>

   <para>
    <example>
     <title>Variable function arguments</title>
     <programlisting>
pval *arg1, *arg2, *arg3;
int arg_count = ARG_COUNT(ht);

if (arg_count < 2 || arg_count > 3 ||
    getParameters(ht,arg_count,&arg1,&arg2,&arg3)==FAILURE) {
    WRONG_PARAM_COUNT;
}
    </programlisting>
    </example></para></sect2>

  <sect2 id="phpdevel-addfunc-using-args">
   <title>Using the Function Arguments</title>
   <para>
    The type of each argument is stored in the pval type field. This
    type can be any of the following:

    <table>
     <title>PHP Internal Types</title>
     <tgroup cols="2">
      <tbody>
       <row>
        <entry>IS_STRING</entry>
        <entry>String</entry>
       </row>
       <row>
        <entry>IS_DOUBLE</entry>
        <entry>Double-precision floating point</entry>
       </row>
       <row>
        <entry>IS_LONG</entry>
        <entry>Long integer</entry>
       </row>
       <row>
        <entry>IS_ARRAY</entry>
        <entry>Array</entry>
       </row>
       <row>
        <entry>IS_EMPTY</entry>
        <entry>None</entry>
       </row>
       <row>
        <entry>IS_USER_FUNCTION</entry>
        <entry>??</entry>
       </row>
       <row>
        <entry>IS_INTERNAL_FUNCTION</entry>
        <entry>?? (if some of these cannot be passed to a function - delete)</entry>
       </row>
       <row>
        <entry>IS_CLASS</entry>
        <entry>??</entry>
       </row>
       <row>
        <entry>IS_OBJECT</entry>
        <entry>??</entry>
       </row>
      </tbody>
     </tgroup>
    </table></para>

   <para>
    If you get an argument of one type and would like to use it as
    another, or if you just want to force the argument to be of a
    certain type, you can use one of the following conversion
    functions:

    <programlisting>
convert_to_long(arg1);
convert_to_double(arg1);
convert_to_string(arg1);
convert_to_boolean_long(arg1); /* If the string is "" or "0" it becomes 0, 1 otherwise */
convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE depending on string */
     </programlisting></para>

   <simpara>
    These function all do in-place conversion. They do not return anything.</simpara>

   <para>
    The actual argument is stored in a union; the members are:
    <itemizedlist>
     <listitem><simpara>IS_STRING: arg1->value.str.val</simpara></listitem>
     <listitem><simpara>IS_LONG: arg1->value.lval</simpara></listitem>
     <listitem><simpara>IS_DOUBLE: arg1->value.dval</simpara></listitem>
    </itemizedlist></para></sect2>

  <sect2 id="phpdevel-addfunc-memmgmt">
   <title>Memory Management in Functions</title>
   <simpara>
    Any memory needed by a function should be allocated with either
    emalloc() or estrdup(). These are memory handling abstraction
    functions that look and smell like the normal malloc() and
    strdup() functions. Memory should be freed with efree().</simpara>

   <simpara>
    There are two kinds of memory in this program: memory which is
    returned to the parser in a variable, and memory which you need for
    temporary storage in your internal function. When you assign a
    string to a variable which is returned to the parser you need to
    make sure you first allocate the memory with either emalloc() or
    estrdup(). This memory should NEVER be freed by you, unless you
    later in the same function overwrite your original assignment
    (this kind of programming practice is not good though).</simpara>

   <simpara>
    For any temporary/permanent memory you need in your
    functions/library you should use the three emalloc(), estrdup(),
    and efree() functions. They behave EXACTLY like their counterpart
    functions. Anything you emalloc() or estrdup() you have to efree()
    at some point or another, unless it's supposed to stick around
    until the end of the program; otherwise, there will be a memory
    leak. The meaning of "the functions behave exactly like their
    counterparts" is: if you efree() something which was not
    emalloc()'ed nor estrdup()'ed you might get a segmentation
    fault. So please take care and free all of your wasted memory.</simpara>

   <simpara>
    If you compile with "-DDEBUG", PHP 3 will print out a list of all
    memory that was allocated using emalloc() and estrdup() but never
    freed with efree() when it is done running the specified script.</simpara></sect2>

  <sect2 id="phpdevel-addfunc-symtab">
   <title>Setting Variables in the Symbol Table</title>
   <para>
    A number of macros are available which make it easier to set a
    variable in the symbol table:

    <itemizedlist>
     <listitem><simpara>SET_VAR_STRING(name,value) <footnoteref linkend="symtab-1"/></simpara></listitem>
     <listitem><simpara>SET_VAR_DOUBLE(name,value)</simpara></listitem>
     <listitem><simpara>SET_VAR_LONG(name,value)</simpara></listitem>
    </itemizedlist></para>

   <para>
    <footnote id="symtab-1">
     <simpara>
      Be careful here. The value part must be malloc'ed manually because
      the memory management code will try to free this pointer later. Do
      not pass statically allocated memory into a SET_VAR_STRING.</simpara>
    </footnote></para>

   <simpara>
    Symbol tables in PHP 3.0 are implemented as hash tables. At any
    given time, &symbol_table is a pointer to the 'main' symbol
    table, and active_symbol_table points to the currently active
    symbol table (these may be identical like in startup, or
    different, if you're inside a function).</simpara>

   <para>
    The following examples use 'active_symbol_table'. You should
    replace it with &symbol_table if you specifically want to work
    with the 'main' symbol table. Also, the same functions may be
    applied to arrays, as explained below.</para>

   <para>
    <example>
     <title>Checking whether $foo exists in a symbol table</title>
     <programlisting>
if (hash_exists(active_symbol_table,"foo",sizeof("foo"))) { exists... }
else { doesn't exist }
     </programlisting>
    </example>

    <example>
     <title>Finding a variable's size in a symbol table</title>
     <programlisting>
hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue);
check(pvalue.type);
     </programlisting>
    </example>

    Arrays in PHP 3.0 are implemented using the same hashtables as
    symbol tables. This means the two above functions can also be
    used to check variables inside arrays.</para>

   <simpara>
    If you want to define a new array in a symbol table, you should do
    the following.</simpara>

   <simpara>
    First, you may want to check whether it exists and abort
    appropiately, using hash_exists() or hash_find().</simpara>

   <simpara>
    Next, initialize the array:</simpara>

   <para>
    <example>
     <title>Initializing a new array</title>
     <programlisting>
pval arr;

if (array_init(&arr) == FAILURE) { failed... };
hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL);
     </programlisting>
    </example>

    This code declares a new array, named $foo, in the active symbol
    table. This array is empty.</para>

   <simpara>
    Here's how to add new entries to it:</simpara>

   <para>
    <example>
     <title>Adding entries to a new array</title>
     <programlisting>
pval entry;

entry.type = IS_LONG;
entry.value.lval = 5;

/* defines $foo["bar"] = 5 */
hash_update(arr.value.ht,"bar",sizeof("bar"),&entry,sizeof(pval),NULL);

/* defines $foo[7] = 5 */
hash_index_update(arr.value.ht,7,&entry,sizeof(pval),NULL);

/* defines the next free place in $foo[],
* $foo[8], to be 5 (works like php2)
*/
hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL);
     </programlisting>
    </example>

    If you'd like to modify a value that you inserted to a hash, you
    must first retrieve it from the hash. To prevent that overhead,
    you can supply a pval ** to the hash add function, and it'll be
    updated with the pval * address of the inserted element inside the
    hash. If that value is NULL (like in all of the above examples) -
    that parameter is ignored.</para>

   <simpara>
    hash_next_index_insert() uses more or less the same logic as
    "$foo[] = bar;" in PHP 2.0.</simpara>

   <simpara>
    If you are building an array to return from a function, you can
    initialize the array just like above by doing:</simpara>

<programlisting>
if (array_init(return_value) == FAILURE) { failed...; }
</programlisting>

<simpara>
...and then adding values with the helper functions:</simpara>

   <programlisting>
add_next_index_long(return_value,long_value);
add_next_index_double(return_value,double_value);
add_next_index_string(return_value,estrdup(string_value));
   </programlisting>

   <para>
    Of course, if the adding isn't done right after the array
    initialization, you'd probably have to look for the array first:

    <programlisting>
pval *arr;

if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE) { can't find... }
else { use arr->value.ht... }
    </programlisting></para>

   <simpara>
    Note that hash_find receives a pointer to a pval pointer, and not
    a pval pointer.</simpara>

   <simpara>
    Just about any hash function returns SUCCESS or FAILURE (except
    for hash_exists(), which returns a boolean truth value).</simpara></sect2>

  <sect2 id="phpdevel-addfunc-retsimple">
   <title>Returning simple values</title>
   <simpara>
    A number of macros are available to make returning values from a
    function easier.</simpara>

   <para>
    The RETURN_* macros all set the return value and return from the
    function:
    <itemizedlist>
     <listitem><simpara>RETURN</simpara></listitem>
     <listitem><simpara>RETURN_FALSE</simpara></listitem>
     <listitem><simpara>RETURN_TRUE</simpara></listitem>
     <listitem><simpara>RETURN_LONG(l)</simpara></listitem>
     <listitem><simpara>RETURN_STRING(s,dup) If dup is true, duplicates the string</simpara></listitem>
     <listitem><simpara>RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l).</simpara></listitem>
     <listitem><simpara>RETURN_DOUBLE(d)</simpara></listitem>
    </itemizedlist></para>

   <para>
    The RETVAL_* macros set the return value, but do not return.
    <itemizedlist>
     <listitem><simpara>RETVAL_FALSE</simpara></listitem>
     <listitem><simpara>RETVAL_TRUE</simpara></listitem>
     <listitem><simpara>RETVAL_LONG(l)</simpara></listitem>
     <listitem><simpara>RETVAL_STRING(s,dup) If dup is true, duplicates the string</simpara></listitem>
     <listitem><simpara>RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l).</simpara></listitem>
  &n