Add embryonic error handling section, since we don't have one place for this.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@337352 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Adam Harvey 2015-08-09 01:15:47 +00:00
parent 5bdb18a52e
commit f0fe52e5a6
3 changed files with 198 additions and 0 deletions

40
language/errors.xml Normal file
View file

@ -0,0 +1,40 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="language.errors" xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd">
<title>Errors</title>
<sect1 phd:chunk="false" xml:id="language.errors.intro">
<title>Introduction</title>
<para>
Sadly, no matter how careful we are when writing our code, errors are a
fact of life. PHP will report errors, warnings and notices for many common
coding and runtime problems, and knowing how to detect and handle these
errors will make debugging much easier.
</para>
</sect1>
&language.errors.basics;
&language.errors.php7;
</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:"~/.phpdoc/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
-->

100
language/errors/basics.xml Normal file
View file

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="language.errors.basics" xmlns="http://docbook.org/ns/docbook">
<title>Basics</title>
<para>
PHP reports errors in response to a number of internal error conditions.
These may be used to signal a number of different conditions, and can be
displayed and/or logged as required.
</para>
<para>
Every error that PHP generates includes a type. A
<link linkend="errorfunc.constants">list of these types</link> is available,
along with a short description of their behaviour and how they can be
caused.
</para>
<sect2 xml:id="language.errors.basics.handling">
<title>Handling errors with PHP</title>
<para>
If no error handler is set, then PHP will handle any errors that occur
according to its configuration. Which errors are reported and which are
ignored is controlled by the
<link linkend="ini.error-reporting"><parameter>error_reporting</parameter></link>
php.ini directive, or at runtime by calling
<function>error_reporting</function>. It is strongly recommended that the
configuration directive be set, however, as some errors can occur before
execution of your script begins.
</para>
<para>
In a development environment, you should always set
<link linkend="ini.error-reporting"><parameter>error_reporting</parameter></link>
to <constant>E_ALL</constant>, as you need to be aware of and fix the
issues raised by PHP. In production, you may wish to set this to a less
verbose level such as
<code>E_ALL &amp; ~E_NOTICE &amp; ~E_STRICT &amp; ~E_DEPRECATED</code>, but
in many cases <constant>E_ALL</constant> is also appropriate, as it may
provide early warning of potential issues.
</para>
<para>
What PHP does with these errors depends on two further php.ini directives.
<link linkend="ini.display-errors"><parameter>display_errors</parameter></link>
controls whether the error is shown as part of the script's output. This
should always be disabled in a production environment, as it can include
confidential information such as database passwords, but is often useful to
enable in development, as it ensures immediate reporting of issues.
</para>
<para>
In addition to displaying errors, PHP can log errors when the
<link linkend="ini.log-errors"><parameter>log_errors</parameter></link>
directive is enabled. This will log any errors to the file or syslog
defined by
<link linkend="ini.error-log"><parameter>error_log</parameter></link>. This
can be extremely useful in a production environment, as you can log errors
that occur and then generate reports based on those errors.
</para>
</sect2>
<sect2 xml:id="language.errors.basics.user">
<title>User error handlers</title>
<para>
If PHP's default error handling is inadequate, you can also handle many
types of error with your own custom error handler by installing it with
<function>set_error_handler</function>. While some error types cannot be
handled this way, those that can be handled can then be handled in the way
that your script sees fit: for example, this can be used to show a custom
error page to the user and then report more directly than via a log, such
as by sending an e-mail.
</para>
</sect2>
</sect1>
<!-- 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:"~/.phpdoc/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
-->

58
language/errors/php7.xml Normal file
View file

@ -0,0 +1,58 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="language.errors.php7" xmlns="http://docbook.org/ns/docbook">
<title>Errors in PHP 7</title>
<para>
PHP 7 changes how most errors are reported by PHP. Instead of reporting
errors through the traditional error reporting mechanism used by PHP 5, most
errors are now reported by throwing <classname>Error</classname> exceptions.
</para>
<para>
As with normal exceptions, these <classname>Error</classname> exceptions
will bubble up until they reach the first matching
<link linkend="language.exceptions.catch"><literal>catch</literal></link>
block. If there are no matching blocks, then any default exception handler
installed with <function>set_exception_handler</function> will be called,
and if there is no default exception handler, then the exception will be
converted to a fatal error and will be handled like a traditional error.
</para>
<para>
As the <classname>Error</classname> hierarchy does not inherit from
<classname>Exception</classname>, code that uses
<code>catch (Exception $e) { ... }</code> blocks to handle uncaught
exceptions in PHP 5 will find that these <classname>Error</classname>s are
not caught by these blocks. Either a <code>catch (Error $e) { ... }</code>
block or a <function>set_exception_handler</function> handler is required.
</para>
<para>
A list of <classname>Error</classname> subclasses can be found in the
<link linkend="book.errorfunc">error function section</link> of the manual.
</para>
</sect1>
<!-- 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:"~/.phpdoc/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
-->