svn: /phpdoc/en/trunk/language/ errors/basics.xml errors/php7.xml errors.xml

From: Date: Sun, 09 Aug 2015 01:15:47 +0000
Subject: svn: /phpdoc/en/trunk/language/ errors/basics.xml errors/php7.xml errors.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-13535@lists.php.net to get a copy of this message
aharvey Sun, 09 Aug 2015 01:15:47 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=337352 Log: Add embryonic error handling section, since we don't have one place for this. Changed paths: A phpdoc/en/trunk/language/errors/ A phpdoc/en/trunk/language/errors/basics.xml A phpdoc/en/trunk/language/errors/php7.xml A phpdoc/en/trunk/language/errors.xml Added: phpdoc/en/trunk/language/errors/basics.xml =================================================================== --- phpdoc/en/trunk/language/errors/basics.xml (rev 0) +++ phpdoc/en/trunk/language/errors/basics.xml 2015-08-09 01:15:47 UTC (rev 337352) @@ -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 +--> + Added: phpdoc/en/trunk/language/errors/php7.xml =================================================================== --- phpdoc/en/trunk/language/errors/php7.xml (rev 0) +++ phpdoc/en/trunk/language/errors/php7.xml 2015-08-09 01:15:47 UTC (rev 337352) @@ -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 +--> + Added: phpdoc/en/trunk/language/errors.xml =================================================================== --- phpdoc/en/trunk/language/errors.xml (rev 0) +++ phpdoc/en/trunk/language/errors.xml 2015-08-09 01:15:47 UTC (rev 337352) @@ -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 +-->

« previous php.doc.cvs (#13535) next »