Some cleanup in FAQ section

Closes GH-327.
This commit is contained in:
George Peter Banyard 2021-01-12 06:33:38 +00:00 committed by Christoph M. Becker
parent 175b731219
commit b8e1b1357d
7 changed files with 12 additions and 307 deletions

View file

@ -226,12 +226,7 @@
special reserved PHP variable that contains all web server information.
It is known as a superglobal. See the related manual page on
<link linkend="language.variables.superglobals">superglobals</link>
for more information. These special variables were introduced in PHP
<link xlink:href="&url.php.release4.1.0;">4.1.0</link>. Before this time, we used
the older <varname>$HTTP_*_VARS</varname> arrays instead,
such as <varname>$HTTP_SERVER_VARS</varname>. As of PHP 5.4.0
these older variables have been removed. (See also the note on
<link linkend="tutorial.oldcode">old code</link>.)
for more information.
</para>
</note>
<para>
@ -454,52 +449,6 @@ Hi Joe. You are 22 years old.
</para>
</section>
<section xml:id="tutorial.oldcode">
<info><title>Using old code with new versions of PHP</title></info>
<para>
Now that PHP has grown to be a popular scripting language, there are
a lot of public repositories and libraries containing code you can reuse.
The PHP developers have largely tried to preserve backwards compatibility,
so a script written for an older version will run (ideally) without changes
in a newer version of PHP. In practice, some changes will usually be needed.
</para>
<para>
Two of the most important recent changes that affect old code are:
<itemizedlist>
<listitem>
<simpara>
The old <varname>$HTTP_*_VARS</varname> arrays are not available as of
PHP 5.4.0. The following
<link linkend="language.variables.superglobals">superglobal arrays</link>
were introduced in PHP <link xlink:href="&url.php.release4.1.0;">4.1.0</link>.
They are: <varname>$_GET</varname>, <varname>$_POST</varname>,
<varname>$_COOKIE</varname>, <varname>$_SERVER</varname>,
<varname>$_FILES</varname>, <varname>$_ENV</varname>,
<varname>$_REQUEST</varname>, and <varname>$_SESSION</varname>.
</simpara>
</listitem>
<listitem>
<simpara>
External variables are no longer registered in the global scope by
default. In other words, as of PHP
<link xlink:href="&url.php.release4.2.0;">4.2.0</link> the PHP directive
<literal>register_globals</literal> is
<emphasis>off</emphasis> by default in &php.ini;. The preferred
method of accessing these values is via the superglobal arrays mentioned
above. Older scripts, books, and tutorials may rely on this
directive being <literal>on</literal>. If it were <literal>on</literal>,
for example, one could use <varname>$id</varname> from the URL
<literal>http://www.example.com/foo.php?id=42</literal>. Whether on
or off, <varname>$_GET['id']</varname> is available.
</simpara>
</listitem>
</itemizedlist>
For more details on these changes, see the section on
<link linkend="language.variables.predefined">predefined variables</link>
and links therein.
</para>
</section>
<section xml:id="tutorial.whatsnext">
<info><title>What's next?</title></info>
<para>

View file

@ -187,71 +187,6 @@
</answer>
</qandaentry>
<qandaentry xml:id="faq.build.apache">
<question>
<para>
I can't figure out how to build PHP with Apache 1.3.
</para>
</question>
<answer>
<para>
This is actually quite easy. Follow these steps carefully:
<itemizedlist>
<listitem>
<simpara>
Grab the latest Apache 1.3 distribution from
<link xlink:href="&url.apache.source;">&url.apache.source;</link>.
</simpara>
</listitem>
<listitem>
<simpara>
Ungzip and untar it somewhere, for example
<filename>/usr/local/src/apache-1.3</filename>.
</simpara>
</listitem>
<listitem>
<simpara>
Compile PHP by first running
<command>./configure --with-apache=/&lt;path&gt;/apache-1.3</command>
(substitute &lt;path&gt; for the actual path to your apache-1.3 directory).
</simpara>
</listitem>
<listitem>
<simpara>
Type <command>make</command> followed by <command>make install</command>
to build PHP and copy the necessary files to the Apache distribution tree.
</simpara>
</listitem>
<listitem>
<simpara>
Change directories into to your <filename>/&lt;path&gt;/apache-1.3/src</filename>
directory and edit the <filename>Configuration</filename> file.
Add to the file:
<literal>AddModule modules/php4/libphp4.a</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Type: <command>./configure</command> followed by <literal>make</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
You should now have a PHP-enabled httpd binary!
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
<emphasis>Note:</emphasis> You can also use the new Apache
<literal>./configure</literal> script. See the instructions in
the <literal>README.configure</literal> file which is part of
your Apache distribution. Also have a look at the <filename>INSTALL</filename>
file in the PHP distribution.
</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq.build.not-running">
<question>
<para>

View file

@ -37,11 +37,6 @@
<para>Can I access Microsoft Access databases?</para>
</question>
<answer>
<para>
Yes. You already have all the tools you need if you are running
entirely under Windows 9x/Me, or NT/2000, where you can use
ODBC and Microsoft's ODBC drivers for Microsoft Access databases.
</para>
<para>
If you are running PHP on a Unix box and want to talk to MS Access
on a Windows box you will need Unix ODBC drivers.
@ -150,76 +145,6 @@
</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq.databases.mysql.deprecated">
<question>
<para>
Why is the MySQL extension (ext/mysql) that I've been using for over
10 years discouraged from use? Is it deprecated? What do I use instead?
How can I migrate?
</para>
</question>
<answer>
<para>
There are three MySQL extensions, as described under the
<link linkend="mysqlinfo.api.choosing">Choosing a MySQL API</link> section. The old API
should not be used, it is deprecated as of PHP 5.5.0 and has been moved to PECL as of PHP 7.0.0.
You are strongly encouraged
to write all new code with either <link linkend="book.mysqli">mysqli</link> or
<link linkend="ref.pdo-mysql">PDO_MySQL</link>.
</para>
<para>
Migration scripts are not available at this time, although the mysqli API contains both
a procedural and OOP API, with the procedural version being similar to ext/mysql.
</para>
<para>
It is not possible to mix the extensions. So, for example, passing a mysqli connection to
PDO_MySQL or ext/mysql will not work.
</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq.databases.mysqlresource">
<question>
<para>
Why do I get an error that looks something like this:
"Warning: 0 is not a MySQL result index in &lt;file&gt;
on line &lt;x&gt;" or "Warning: Supplied argument is not
a valid MySQL result resource in &lt;file&gt; on line &lt;x&gt;"?
</para>
</question>
<answer>
<para>
You are trying to use a result identifier that is 0. The 0 indicates
that your query failed for some reason. You need to check for errors
after submitting a query and before you attempt to use the returned
result identifier. The proper way to do this is with code similar
to the following:
<programlisting role="php">
<![CDATA[
<?php
$result = mysql_query("SELECT * FROM tables_priv");
if (!$result) {
echo mysql_error();
exit;
}
?>
]]>
</programlisting>
or
<programlisting role="php">
<![CDATA[
<?php
$result = mysql_query("SELECT * FROM tables_priv")
or die("Bad query: " . mysql_error());
?>
]]>
</programlisting>
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>

View file

@ -418,7 +418,7 @@ cgi error:
</question>
<answer>
<para>
On Windows 7, XP, Vista, 2008, 2012 and up:
On Windows:
<itemizedlist>
<listitem><para>
Go to Control Panel and open the System icon (Start → Control Panel)
@ -447,38 +447,12 @@ cgi error:
</para></listitem>
</itemizedlist>
</para>
<para>
On Windows 98/Me you need to edit the <filename>autoexec.bat</filename>
file:
<itemizedlist>
<listitem><para>
Open the Notepad (Start → Run and enter notepad)
</para></listitem>
<listitem><para>
Open the <filename>C:\autoexec.bat</filename> file
</para></listitem>
<listitem><para>
Locate the line with PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;..... and add:
<literal>;C:\php</literal> to the end of the line
</para></listitem>
<listitem><para>
Save the file and restart your computer
</para></listitem>
</itemizedlist>
</para>
<note>
<simpara>
Be sure to reboot after following the steps above to ensure that the
<envar>PATH</envar> changes are applied.
</simpara>
</note>
<para>
The PHP manual used to promote the copying of files into the Windows
system directory, this is because this directory
(<filename>C:\Windows</filename>, <filename>C:\WINNT</filename>, etc.)
is by default in the system's <envar>PATH</envar>. Copying files into the Windows
system directory has long since been deprecated and may cause problems.
</para>
</answer>
</qandaentry>
@ -523,29 +497,6 @@ cgi error:
</para></listitem>
</itemizedlist>
</para>
<para>
On Windows 98/Me you need to edit the <filename>autoexec.bat</filename>
file:
<itemizedlist>
<listitem><para>
Open the Notepad (Start → Run and enter notepad)
</para></listitem>
<listitem><para>
Open the <filename>C:\autoexec.bat</filename> file
</para></listitem>
<listitem><para>
Add a new line to the end of the file: <literal>set
PHPRC=C:\php</literal> (replace <literal>C:\php</literal> with the
directory where &php.ini; is located). Please note that the path
cannot contain spaces. For instance, if you have installed PHP in
<filename>C:\Program Files\PHP</filename>, you would enter
<filename>C:\PROGRA~1\PHP</filename> instead.
</para></listitem>
<listitem><para>
Save the file and restart your computer
</para></listitem>
</itemizedlist>
</para>
</answer>
</qandaentry>

View file

@ -76,17 +76,16 @@
output.
</para>
<para>
PHP 5.5 provides
PHP provides
<link linkend="book.password">a native password hashing API</link> that
safely handles both <link linkend="function.password-hash">hashing</link>
and <link linkend="function.password-verify">verifying passwords</link>
in a secure manner. There is also
<link xlink:href="&url.password.compat;">a pure PHP compatibility library</link>
available for PHP 5.3.7 and later.
in a secure manner.
</para>
<!-- TODO Drop mention of crypt? -->
<para>
Another option is the <function>crypt</function> function, which
supports several hashing algorithms in PHP 5.3 and later. When using
supports several hashing algorithms. When using
this function, you are guaranteed that the algorithm you select is
available, as PHP contains native implementations of each supported
algorithm, in case one or more are not supported by your system.

View file

@ -12,6 +12,7 @@
<qandaset>
<qandaentry xml:id="faq.using.parameterorder">
<!-- TODO: Mention named arguments -->
<question>
<para>
I cannot remember the parameter order of PHP functions, are they random?
@ -300,9 +301,6 @@ foreach ($headers as $name => $content) {
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>
@ -324,23 +322,6 @@ foreach ($headers as $name => $content) {
</answer>
</qandaentry>
<qandaentry xml:id="faq.using.cgi-vars">
<question>
<para>
I'm trying to access one of the standard CGI
variables (such as <varname>$DOCUMENT_ROOT</varname> or
<varname>$HTTP_REFERER</varname>) in a user-defined
function, and it can't seem to find it. What's wrong?
</para>
</question>
<answer>
<para>
Use <varname>$_SERVER['DOCUMENT_ROOT']</varname> and
<varname>$_SERVER['HTTP_REFERER']</varname> instead.
</para>
</answer>
</qandaentry>
<qandaentry xml:id="faq.using.shorthandbytes">
<question>
<para>
@ -370,24 +351,6 @@ foreach ($headers as $name => $content) {
</note>
</answer>
</qandaentry>
<qandaentry xml:id="faq.using.windowslocalhostissue">
<question>
<para>
Windows: I keep getting connection timeouts when using <literal>localhost</literal>,
whereas <literal>"127.0.0.1"</literal> works?
</para>
</question>
<answer>
<para>
Prior to PHP 5.3.4, there was a bug in the network resolving code inside PHP that
caused <literal>localhost</literal> in all stream related situations to fail if IPv6
was enabled. To work around this issue you can either use <literal>"127.0.0.1"</literal>
or disable IPv6 resolving in the <filename>hosts</filename> file.
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>

View file

@ -99,12 +99,6 @@ to seed the random number generator with <function>srand</function> or
<function>mt_srand</function> as this is done automatically.
</simpara></note>'>
<!ENTITY note.registerglobals '<note xmlns="http://docbook.org/ns/docbook"><title>register_globals: important
note</title><para>As of PHP 4.2.0, the default value for the PHP directive
<literal>register_globals</literal> is <emphasis>
off</emphasis>. The PHP community discourages developers from relying on this directive, and encourages the use
of other means, such as the &link.superglobals;.</para></note>'>
<!ENTITY note.is-superglobal "<note xmlns='http://docbook.org/ns/docbook'><para>This is a 'superglobal', or
automatic global, variable. This simply means that it is available in
all scopes throughout a script. There is no need to do
@ -604,12 +598,6 @@ use.</simpara></note>'>
</varlistentry>
'>
<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP
<link xmlns="http://docbook.org/ns/docbook" linkend="language.variables.predefined">predefined variable</link>
arrays may be disabled with the
<literal>register_long_arrays</literal>
directive.'>
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the
value is measured in bytes. Shorthand notation, as described
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
@ -1783,36 +1771,31 @@ field_offset</parameter></term><listitem><para>The numerical field offset. The
<!ENTITY mysql.alternative.note '<para xmlns="http://docbook.org/ns/docbook">This extension was deprecated in PHP 5.5.0, and it was removed in PHP 7.0.0.
Instead, the <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extension should be used.
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and
<link linkend="faq.databases.mysql.deprecated">related FAQ</link> for more information.
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</para>'>
<!ENTITY mysql.alternative.note.4-3-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 4.3.0, and it
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</para>'>
<!ENTITY mysql.alternative.note.5-3-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.3.0, and it
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</para>'>
<!ENTITY mysql.alternative.note.5-4-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.4.0, and it
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</para>'>
<!ENTITY mysql.alternative.note.5-5-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.5.0, and it
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</para>'>
<!ENTITY mysql.close.connections.result.sets '<para xmlns="http://docbook.org/ns/docbook">