<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.36 $ -->
<chapter xml:id="faq.using" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Using PHP</title>
  <titleabbrev>Using PHP</titleabbrev>

  <para>
   This section gathers many common errors that you may face 
   while writing PHP scripts.
  </para>

  <qandaset>
   <qandaentry xml:id="faq.using.anyform">
    <question>
     <para>
      I would like to write a generic PHP script that can handle data coming 
      from any form. How do I know which POST method variables are available?
     </para>
    </question>
    <answer>
     <para>
      PHP offers many <link linkend="language.variables.predefined">
      predefined variables</link>, like the superglobal <varname>
      $_POST</varname>.  You may loop through <varname>$_POST</varname>
      as it's an associate array of all POSTed values.  For example, let's
      simply loop through it with <link linkend="control-structures.foreach">
      foreach</link>, check for <function>empty</function> values,
      and print them out.
      <programlisting role="php">
<![CDATA[
<?php
$empty = $post = array();
foreach ($_POST as $varname => $varvalue) {
    if (empty($varvalue)) {
        $empty[$varname] = $varvalue;
    } else {
        $post[$varname] = $varvalue;
    }
}

print "<pre>";
if (empty($empty)) {
    print "None of the POSTed values are empty, posted:\n";
    var_dump($post);
} else {
    print "We have " . count($empty) . " empty values\n";
    print "Posted:\n"; var_dump($post);
    print "Empty:\n";  var_dump($empty);
    exit;
}
?>
]]>
      </programlisting>
     </para>
     
     &note.superglobals;

    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.addslashes">
    <question>
     <para>
      I need to convert all single-quotes (') to a backslash 
      followed by a single-quote (\'). How can I do this with a 
      regular expression?  I'd also like to convert " to \" and
      \ to \\.
     </para>
    </question>
    <answer>
     <para>
      The function <function>addslashes</function> will do this.  See
      also <function>mysql_escape_string</function>.  You may also
      strip backslashes with <function>stripslashes</function>.
     </para>

     &note.magicquotes.gpc;

    </answer>
   </qandaentry>
   
   <qandaentry xml:id="faq.using.stripslashes">
    <question>
     <para>
      All my " turn into \" and my ' turn into \', how do I get rid of all 
      these unwanted backslashes?  How and why did they get there?
     </para>
    </question>
    <answer>
     <para>
      The PHP function <function>stripslashes</function> will strip those
      backslashes from your <type>string</type>.  Most likely the backslashes 
      magically exist because the PHP directive 
      <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> is on.
     </para>
     
     &note.magicquotes.gpc;
     
    </answer>
   </qandaentry>   

   <qandaentry xml:id="faq.register-globals">
    <question>
     <para>
      How does the PHP directive register_globals affect me?
     </para>
    </question>
    <answer>
     <para>
      First, an explanation about what this ini setting does. Let's say the
      following URL is used:
      <literal>http://example.com/foo.php?animal=cat</literal>
      and in <filename>foo.php</filename> we might have the following
      PHP code:
     </para>
     <para>
      <programlisting role="php">
<![CDATA[
<?php
// Using $_GET here is preferred
echo $_GET['animal'];

// For $animal to exist, register_globals must be on
// DO NOT DO THIS
echo $animal;

// This applies to all variables, so $_SERVER too
echo $_SERVER['PHP_SELF'];

// Again, for $PHP_SELF to exist, register_globals must be on
// DO NOT DO THIS
echo $PHP_SELF;
?>
]]>
     </programlisting>
    </para>
    <para>
     The code above demonstrates how register_globals creates a lot of
     variables. For years this type of coding has been frowned upon, and for
     years it's been disabled by default. Note that PHP 6 removes this
     deprecated feature. So although most web hosts disable register_globals,
     there are still outdated articles, tutorials, and books that require it
     to be on. Plan accordingly.
    </para>
    <para>
     See also the following resources for additional information:
     <simplelist>
      <member>The <link linkend="ini.register-globals">register_globals</link> directive</member>
      <member>The <link linkend="security.globals">security chapter about register globals</link></member>
      <member><link linkend="language.variables.external">Handling external variables</link></member>
      <member>Use <link linkend="language.variables.superglobals">superglobals</link> instead</member>
     </simplelist>
    </para>
    <note>
     <para>
      In the example above, we used an <acronym>URL</acronym> that contained
      a QUERY_STRING. Passing information like this is done through a GET HTTP
      Request, so this is why the superglobal <varname>$_GET</varname> was used.
     </para>
    </note>
   </answer>
  </qandaentry>

   <qandaentry xml:id="faq.using.wrong-order">
    <question>
     <para>
      When I do the following, the output is printed in 
      the wrong order: 
     <programlisting role="php">
<![CDATA[
<?php
function myfunc($argument)
{
    echo $argument + 10;
}
$variable = 10;
echo "myfunc($variable) = " . myfunc($variable);
?>
]]>
    </programlisting>
     what's going on?
     </para>
    </question>
    <answer>
     <para>
      To be able to use the results of your function in an expression (such
      as concatenating it with other strings in the example above), you need
      to <function>return</function> the value, not <function>echo</function> 
      it.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.newlines">
    <question>
     <para>
      Hey, what happened to my newlines?
      <programlisting role="php">
<![CDATA[
<pre>
<?php echo "This should be the first line."; ?>
<?php echo "This should show up after the new line above."; ?>
</pre>
]]>
      </programlisting>
     </para>
    </question>
    <answer>
     <para>
      In PHP, the ending for a block of code is either "?&gt;" or
      "?&gt;\n" (where \n means a newline). So in the example above,
      the echoed sentences will be on one line, because PHP omits
      the newlines after the block ending. This means that you need to
      insert an extra newline after each block of PHP code to make
      it print out one newline.
     </para>
     <para>
      Why does PHP do this? Because when formatting normal HTML, this
      usually makes your life easier because you don't want that newline,
      but you'd have to create extremely long lines or otherwise make the
      raw page source unreadable to achieve that effect.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.headers-sent">
    <question>
     <para>
      I get the message 'Warning: Cannot send session cookie - headers already
      sent...' or 'Cannot add header information - headers already sent...'.
     </para>
    </question>
    <answer>
     <para>
      The functions <function>header</function>, <function>setcookie</function>,
      and the <link linkend="ref.session">session 
      functions</link> need to add headers to the output stream but headers 
      can only be sent before all other content.  There can be no output
      before using these functions, output such as HTML.  The function <function>
      headers_sent</function> will check if your script has already sent 
      headers and see also the <link linkend="ref.outcontrol">Output Control
      functions</link>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.header">
    <question>
     <para>
      I need to access information in the request header directly. 
      How can I do this?
     </para>
    </question>
    <answer>
     <para>
      The <function>getallheaders</function> function will do this if 
      you are running PHP as an Apache module. So, the following bit
      of code will show you all the request headers:
      <programlisting role="php">
<![CDATA[
<?php
$headers = getallheaders();
foreach ($headers as $name => $content) {
    echo "headers[$name] = $content<br />\n";
}
?>
]]>
      </programlisting>
     </para>
     <para>
      See also 
      <function>apache_lookup_uri</function>,
      <function>apache_response_headers</function>, and
      <function>fsockopen</function>
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.authentication">
    <question>
     <para>
      When I try to use authentication with IIS I get 'No Input file specified'.
     </para>
    </question>
    <answer>
     <para>
      The security model of IIS is at fault here. This is a problem
      common to all CGI programs running under IIS. A workaround is
      to create a plain HTML file (not parsed by PHP) as the entry page
      into an authenticated directory. Then use a META tag to redirect
      to the PHP page, or have a link to the PHP page. PHP will
      then recognize the authentication correctly. With the ISAPI
      module, this is not a problem. This should not effect other
      NT web servers. For more information, see: 
      <link xlink:href="&url.iis;">&url.iis;</link> and the manual
      section on <link linkend="features.http-auth">HTTP Authentication
      </link>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.iis.sharing">
    <question>
     <para>
      Windows: I can't access files shared on another computer using IIS
     </para>
    </question>
    <answer>
     <para>
      You have to change the <literal>Go to Internet Information
      Services</literal>. Locate your PHP file and go to its properties.
      Go to the <literal>File Security</literal> tab, <literal>Edit -&lt; 
      Anonymous access and authentication control</literal>.
     </para>
     <para>
      You can fix the problem either by unticking <literal>Anonymous
      Access</literal> and leaving <literal>Integrated Window
      Authentication</literal> ticked, or, by ticking <literal>Anonymous
      Access</literal> and editing the user as he may not have the access
      right. 
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.netscape">
    <question>
     <para>
      My PHP script works on IE and Lynx, but on Netscape some of
      my output is missing. When I do a "View Source" I see the 
      content in IE but not in Netscape.
     </para>
    </question>
    <answer>
     <para>
      Netscape is more strict regarding HTML tags (such as tables) then 
      IE.  Running your HTML output through a HTML validator, such as 
      <link xlink:href="&url.w3.validator;">validator.w3.org</link>, might 
      be helpful.  For example, a missing &lt;/table&gt; might cause this.
     </para>
     <para>
      Also, both IE and Lynx ignore any NULs (<literal>\0</literal>) in 
      the HTML stream, Netscape does not.  The best way to check for this is 
      to compile the <link linkend="features.commandline">command line</link> version of 
      PHP (also known as the CGI version) and run your script from the
      command line.  In *nix, pipe it through <literal>od -c</literal> and look 
      for any <literal>\0</literal> characters.  If you are on Windows you need 
      to find an editor or some other program that lets you look at binary files.  
      When Netscape sees a NUL in a file it will typically not output anything 
      else on that line whereas both IE and Lynx will. 
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.mixml">
    <question>
     <para>
      How am I supposed to mix XML and PHP? It complains 
      about my &lt;?xml tags!
     </para>
    </question>
    <answer>
     <para>
      In order to embed &lt;?xml straight into your PHP code, you'll have to turn off
      short tags by having the PHP directive 
      <link linkend="ini.short-open-tag">short_open_tags</link> set to 
      <literal>0</literal>.  You cannot set this directive with <function>
      ini_set</function>.  Regardless of <link linkend="ini.short-open-tag">
      short_open_tags</link> being on or off, you can do something like:
      <literal>&lt;?php echo '&lt;?xml'; ?&gt;</literal>.  The default
      for this directive is on.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.editor">
    <question>
     <para>
      How can I use PHP with FrontPage or some other HTML editor
      that insists on moving my code around?
     </para>
    </question>
    <answer>
     <para>
      One of the easiest things to do is to enable using ASP tags in your
      PHP code. This allows you to use the ASP-style &lt;% and %&gt; code
      delimiters. Some of the popular HTML editors handle those more
      intelligently (for now). To enable the ASP-style tags, you need
      to set the <link linkend="ini.asp-tags">asp_tags</link>
      &php.ini; variable, or use the 
      appropriate Apache directive.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.variables">
    <question>
     <para>
      Where can I find a complete list of variables are available to me 
      in PHP?
     </para>
    </question>
    <answer>
     <para>
      Read the manual page on <link linkend="language.variables.predefined">
      predefined variables</link> as it includes a partial list of predefined
      variables available to your script.  A complete list of available
      variables (and much more information) can be seen by calling the 
      <function>phpinfo</function> function.  Be sure to read the manual 
      section on <link linkend="language.variables.external">variables from 
      outside of PHP</link> as it describes common scenarios for 
      external variables, like from a HTML form, a Cookie, and the URL.
     </para>
     
     &note.registerglobals;

    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.freepdf">
    <question>
     <para>
      How can I generate PDF files without using the non-free and 
      commercial libraries like 
      <link linkend="ref.pdf">PDFLib</link>?  I'd like something that's 
      free and doesn't require external PDF libraries.
     </para>
    </question>
    <answer>
     <para>
      There are a few alternatives written in PHP such as 
      <link xlink:href="&url.pdf.ros;">&url.pdf.ros;</link>, 
      <link xlink:href="&url.pdf.fpdf;">&url.pdf.fpdf;</link>, 
      <link xlink:href="&url.pdf.pdf4php;">&url.pdf.pdf4php;</link>, and 
      <link xlink:href="&url.pdf.phppdflib;">&url.pdf.phppdflib;</link>.
      There is also the <link xlink:href="&url.pdf.panda;">Panda</link> module.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.cgi-vars">
    <question>
     <para>
      I'm trying to access one of the standard CGI
      variables (such as $DOCUMENT_ROOT or $HTTP_REFERER) in a user-defined
      function, and it can't seem to find it. What's wrong?
     </para>
    </question>
    <answer>
     <para>
      It's important to realize that the PHP directive <link
      linkend="ini.register-globals">register_globals</link> also affects
      server and environment variables.  When register_globals = off (the
      default is off since PHP 4.2.0), <varname>$DOCUMENT_ROOT</varname>
      will not exist. Instead, use <varname>$_SERVER['DOCUMENT_ROOT']
      </varname>.  If register_globals = on then the variables
      <varname>$DOCUMENT_ROOT</varname> and
      <varname>$GLOBALS['DOCUMENT_ROOT']</varname> will also exist.
     </para>
     <para>
      If you're sure register_globals = on and wonder why
      <varname>$DOCUMENT_ROOT</varname> isn't available inside functions,
      it's because these are like any other variables and would 
      require <literal>global $DOCUMENT_ROOT</literal> inside the
      function.  See also the manual page on 
      <link linkend="language.variables.scope">variable scope</link>.  It's
      preferred to code with register_globals = off.
     </para>
     
     &note.superglobals;

    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.using.shorthandbytes">
    <question>
     <para>
      A few PHP directives may also take on shorthand byte values, as opposed
      to only <type>integer</type> byte values.  What are all the available
      shorthand byte options?  And can I use these outside of &php.ini;?
     </para>
    </question>
    <answer>
     <para>
      The available options are K (for Kilobytes), M (for Megabytes) and G (for
      Gigabytes; available since PHP 5.1.0), these are case insensitive.
      Anything else assumes bytes.
      <literal>1M</literal> equals one Megabyte or <literal>1048576</literal>
      bytes.  <literal>1K</literal> equals one Kilobyte or 
      <literal>1024</literal> bytes.  You may not use these shorthand 
      notations outside of &php.ini;, instead use an <type>integer</type> 
      value of bytes.  See the <function>ini_get</function> documentation for
      an example on how to convert these values.
     </para>
    </answer>
   </qandaentry>

  </qandaset>
 </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
-->