mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
MFB:
- Split reference.xml into book.xml, examples.xml & setup.xml
- Updated constants.xml to be an <appendix>
- Change the intro ID to intro.<extname>
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@247932 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson
parent
72c57a3d28
commit
1dcca9a1f2
6 changed files with 223 additions and 133 deletions
56
reference/apd/book.xml
Normal file
56
reference/apd/book.xml
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.2 $ -->
|
||||
<!-- Purpose: basic.php -->
|
||||
<!-- Membership: pecl -->
|
||||
|
||||
<book xml:id="book.apd" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Advanced PHP debugger</title>
|
||||
<titleabbrev>APD</titleabbrev>
|
||||
|
||||
<preface xml:id="intro.apd">
|
||||
&reftitle.intro;
|
||||
<para>
|
||||
APD is the Advanced PHP Debugger. It was written to provide profiling and
|
||||
debugging capabilities for PHP code, as well as to provide the ability to
|
||||
print out a full stack backtrace. APD supports interactive debugging, but
|
||||
by default it writes data to trace files. It also offers event based
|
||||
logging so that varying levels of information (including function calls,
|
||||
arguments passed, timings, etc.) can be turned on or off for individual
|
||||
scripts.
|
||||
<caution>
|
||||
<para>
|
||||
APD is a Zend Extension, modifying the way the internals of PHP handle
|
||||
function calls, and thus may or may not be compatible with other Zend
|
||||
Extensions (for example Zend Optimizer).
|
||||
</para>
|
||||
</caution>
|
||||
</para>
|
||||
</preface>
|
||||
|
||||
&reference.apd.setup;
|
||||
&reference.apd.constants;
|
||||
&reference.apd.examples;
|
||||
&reference.apd.reference;
|
||||
|
||||
</book>
|
||||
|
||||
<!-- 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
|
||||
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
|
||||
-->
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.2 $ -->
|
||||
<section xml:id="apd.constants" xmlns="http://docbook.org/ns/docbook">
|
||||
<!-- $Revision: 1.3 $ -->
|
||||
<appendix xml:id="apd.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
&reftitle.constants;
|
||||
&extension.constants;
|
||||
<table>
|
||||
|
|
@ -97,7 +97,7 @@
|
|||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</section>
|
||||
</appendix>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
|
|
|
|||
104
reference/apd/examples.xml
Normal file
104
reference/apd/examples.xml
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.2 $ -->
|
||||
|
||||
<appendix xml:id="apd.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
&reftitle.examples;
|
||||
<section xml:id="apd.examples.usage">
|
||||
<title>How to use PHP-APD in your scripts</title>
|
||||
<procedure>
|
||||
<step>
|
||||
<para>
|
||||
As the first line of your PHP script, call the apd_set_pprof_trace() function
|
||||
to start the trace:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
apd_set_pprof_trace();
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
You can insert the line anywhere in your script, but if you do not start
|
||||
tracing at the beginning of your script you discard profile data that might
|
||||
otherwise lead you to a performance bottleneck.
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
Now run your script. The dump output will be written to
|
||||
<filename>apd.dumpdir/pprof_pid.ext</filename>.
|
||||
<tip>
|
||||
<para>
|
||||
If you're running the CGI version of PHP, you will need to add the '-e'
|
||||
flag to enable extended information for apd to work properly. For
|
||||
example:
|
||||
<userinput>php -e -f script.php</userinput>
|
||||
</para>
|
||||
</tip>
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
To display formatted profile data, issue the <command>pprofp</command>
|
||||
command with the sort and display options of your choice. The formatted
|
||||
output will look something like:
|
||||
<screen>
|
||||
<![CDATA[
|
||||
bash-2.05b$ pprofp -R /tmp/pprof.22141.0
|
||||
|
||||
Trace for /home/dan/testapd.php
|
||||
Total Elapsed Time = 0.00
|
||||
Total System Time = 0.00
|
||||
Total User Time = 0.00
|
||||
|
||||
|
||||
Real User System secs/ cumm
|
||||
%Time (excl/cumm) (excl/cumm) (excl/cumm) Calls call s/call Memory Usage Name
|
||||
--------------------------------------------------------------------------------------
|
||||
100.0 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0000 0.0009 0 main
|
||||
56.9 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0005 0.0005 0 apd_set_pprof_trace
|
||||
28.0 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 preg_replace
|
||||
14.3 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 str_replace
|
||||
]]>
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
The -R option used in this example sorts the profile table by the amount
|
||||
of real time the script spent executing a given function. The "cumm call"
|
||||
column reveals how many times each function was called, and the "s/call"
|
||||
column reveals how many seconds each call to the function required, on
|
||||
average.
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
To generate a calltree file that you can import into the KCacheGrind
|
||||
profile analysis application, issue the <command>pprof2calltree</command>
|
||||
comand.
|
||||
</para>
|
||||
</step>
|
||||
</procedure>
|
||||
</section>
|
||||
</appendix>
|
||||
|
||||
<!-- 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
|
||||
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
|
||||
-->
|
||||
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.6 $ -->
|
||||
<!-- $Revision: 1.7 $ -->
|
||||
<section xml:id="apd.configuration" xmlns="http://docbook.org/ns/docbook">
|
||||
&reftitle.runtime;
|
||||
&extension.runtime;
|
||||
|
|
|
|||
|
|
@ -1,137 +1,24 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.8 $ -->
|
||||
<!-- Purpose: basic.php -->
|
||||
<!-- Membership: pecl -->
|
||||
<!-- $Revision: 1.9 $ -->
|
||||
|
||||
<reference xml:id="ref.apd" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Advanced PHP debugger</title>
|
||||
<titleabbrev>APD</titleabbrev>
|
||||
<partintro>
|
||||
|
||||
<section xml:id="apd.intro">
|
||||
&reftitle.intro;
|
||||
<para>
|
||||
APD is the Advanced PHP Debugger. It was written to provide profiling and
|
||||
debugging capabilities for PHP code, as well as to provide the ability to
|
||||
print out a full stack backtrace. APD supports interactive debugging, but
|
||||
by default it writes data to trace files. It also offers event based
|
||||
logging so that varying levels of information (including function calls,
|
||||
arguments passed, timings, etc.) can be turned on or off for individual
|
||||
scripts.
|
||||
<caution>
|
||||
<para>
|
||||
APD is a Zend Extension, modifying the way the internals of PHP handle
|
||||
function calls, and thus may or may not be compatible with other Zend
|
||||
Extensions (for example Zend Optimizer).
|
||||
</para>
|
||||
</caution>
|
||||
</para>
|
||||
</section>
|
||||
<reference xml:id="ref.apd" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>APD &Functions;</title>
|
||||
<partintro>
|
||||
<section xml:id="apd.contact">
|
||||
<title>Contact information</title>
|
||||
<para>
|
||||
If you have comments, bugfixes, enhancements or want to help developing
|
||||
this beast, you can send an mail to
|
||||
<link xlink:href="mailto:&email.apd;">&email.apd;</link>. Any help is very
|
||||
welcome.
|
||||
</para>
|
||||
</section>
|
||||
</partintro>
|
||||
|
||||
&reference.apd.configure;
|
||||
&reference.apd.entities.functions;
|
||||
|
||||
&reference.apd.ini;
|
||||
</reference>
|
||||
|
||||
<section xml:id="apd.resources">
|
||||
&reftitle.resources;
|
||||
&no.resource;
|
||||
</section>
|
||||
|
||||
&reference.apd.constants;
|
||||
|
||||
<section xml:id="apd.examples">
|
||||
<title>How to use PHP-APD in your scripts</title>
|
||||
<procedure>
|
||||
<step>
|
||||
<para>
|
||||
As the first line of your PHP script, call the apd_set_pprof_trace() function
|
||||
to start the trace:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
apd_set_pprof_trace();
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
You can insert the line anywhere in your script, but if you do not start
|
||||
tracing at the beginning of your script you discard profile data that might
|
||||
otherwise lead you to a performance bottleneck.
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
Now run your script. The dump output will be written to
|
||||
<filename>apd.dumpdir/pprof_pid.ext</filename>.
|
||||
<tip>
|
||||
<para>
|
||||
If you're running the CGI version of PHP, you will need to add the '-e'
|
||||
flag to enable extended information for apd to work properly. For
|
||||
example:
|
||||
<userinput>php -e -f script.php</userinput>
|
||||
</para>
|
||||
</tip>
|
||||
</para>
|
||||
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
To display formatted profile data, issue the <command>pprofp</command>
|
||||
command with the sort and display options of your choice. The formatted
|
||||
output will look something like:
|
||||
<screen>
|
||||
<![CDATA[
|
||||
bash-2.05b$ pprofp -R /tmp/pprof.22141.0
|
||||
|
||||
Trace for /home/dan/testapd.php
|
||||
Total Elapsed Time = 0.00
|
||||
Total System Time = 0.00
|
||||
Total User Time = 0.00
|
||||
|
||||
|
||||
Real User System secs/ cumm
|
||||
%Time (excl/cumm) (excl/cumm) (excl/cumm) Calls call s/call Memory Usage Name
|
||||
--------------------------------------------------------------------------------------
|
||||
100.0 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0000 0.0009 0 main
|
||||
56.9 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0005 0.0005 0 apd_set_pprof_trace
|
||||
28.0 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 preg_replace
|
||||
14.3 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 str_replace
|
||||
]]>
|
||||
</screen>
|
||||
</para>
|
||||
<para>
|
||||
The -R option used in this example sorts the profile table by the amount
|
||||
of real time the script spent executing a given function. The "cumm call"
|
||||
column reveals how many times each function was called, and the "s/call"
|
||||
column reveals how many seconds each call to the function required, on
|
||||
average.
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
To generate a calltree file that you can import into the KCacheGrind
|
||||
profile analysis application, issue the <command>pprof2calltree</command>
|
||||
comand.
|
||||
</para>
|
||||
</step>
|
||||
</procedure>
|
||||
</section>
|
||||
|
||||
<section xml:id="apd.contact">
|
||||
<title>Contact information</title>
|
||||
<para>
|
||||
If you have comments, bugfixes, enhancements or want to help developing
|
||||
this beast, you can send an mail to
|
||||
<link xlink:href="mailto:&email.apd;">&email.apd;</link>. Any help is very
|
||||
welcome.
|
||||
</para>
|
||||
</section>
|
||||
</partintro>
|
||||
|
||||
&reference.apd.entities.functions;
|
||||
|
||||
</reference>
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
|
|
@ -151,3 +38,4 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
|
|||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
|
||||
|
|
|
|||
42
reference/apd/setup.xml
Normal file
42
reference/apd/setup.xml
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.2 $ -->
|
||||
|
||||
<chapter xml:id="apd.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
&reftitle.setup;
|
||||
|
||||
<section xml:id="apd.requirements">
|
||||
&reftitle.required;
|
||||
&no.requirement;
|
||||
</section>
|
||||
|
||||
&reference.apd.configure;
|
||||
|
||||
&reference.apd.ini;
|
||||
|
||||
<section xml:id="apd.resources">
|
||||
&reftitle.resources;
|
||||
&no.resource;
|
||||
</section>
|
||||
|
||||
</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
|
||||
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
|
||||
-->
|
||||
|
||||
Loading…
Reference in a new issue