sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

- reviewed caching and response functions

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@233291 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Michael Wallner 2007-04-04 19:06:27 +00:00
parent 9f8717e53a
commit d4ba342695
12 changed files with 117 additions and 153 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
language-snippets.ent
View file

@ -785,6 +785,10 @@ function instead.</simpara></note>'>
<!ENTITY http.request.affects 'Affects the following request method(s) only:'>
<!ENTITY http.request.affects.any 'Affects any request method.'>
<!ENTITY note.http.send.API '<note><simpara>This function is supposed to be used in conjunction with
<function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
<!ENTITY note.http.send.API.mayuse '<note><simpara>This function may be used in conjunction with
<function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
<!ENTITY note.http.request.encodecookies '<note><simpara>The &link.http.request.option; <literal>encodecookies</literal> controls
whether the cookie values should be <function>urlencode</function>d.</simpara></note>'>
<!ENTITY note.http.request.affects.any '<note><simpara>&http.request.affects.any;</simpara></note>'>

42
reference/http/functions/caching/http-cache-etag.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-cache-etag">
<refnamediv>
@ -12,11 +12,10 @@
<type>bool</type><methodname>http_cache_etag</methodname>
<methodparam choice="opt"><type>string</type><parameter>etag</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to cache the sent entity by its ETag, either supplied or generated
by the hash algorithm specified by the
<link linkend="http.configuration">INI setting <literal>http.etag.mode</literal></link>.
by the hash algorithm specified by the &link.http.configuration;
<link linkend="http.configuration.etag.mode">http.etag.mode</link>.
</para>
<para>
If the clients <literal>If-None-Match</literal> header matches the supplied/calculated
@ -24,9 +23,13 @@
a <literal>304 Not Modified</literal> status code is issued.
</para>
<para>
A log entry is written to the cache log if the
&link.http.configuration; <literal>http.log.cache</literal>
is set and the cache attempt was successful.
A log entry is written to the cache log if the &link.http.configuration;
<link linkend="http.configuration.log.cache">http.log.cache</link> is set
and the cache attempt was successful.
</para>
&note.http.send.API.mayuse;
<para>
If this function is used outside the http_send_*() API, it facilitates the <function>ob_etaghandler</function>.
</para>
</refsect1>
<refsect1 role="parameters">
@ -37,7 +40,7 @@
<term><parameter>etag</parameter></term>
<listitem>
<para>
Custom ETag
custom ETag
</para>
</listitem>
</varlistentry>
@ -87,49 +90,32 @@
-->
<!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>http_cache_etag</function> example</title>
<para>
Any text that describes the purpose of the example, or
what goes on in the example should go here (inside the
<example> tag, not out
</para>
<programlisting role="php">
<![CDATA[
<?php
if ($anexample === true) {
echo 'Use the PEAR Coding Standards';
}
http_cache_etag();
http_send_data("data");
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Use the PEAR Coding Standards
]]>
</screen>
</example>
</para>
</refsect1>
-->
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_cache_last_modified</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>

37
reference/http/functions/caching/http-cache-last-modified.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-cache-last-modified">
<refnamediv>
@ -12,22 +12,21 @@
<type>bool</type><methodname>http_cache_last_modified</methodname>
<methodparam choice="opt"><type>int</type><parameter>timestamp_or_expires</parameter></methodparam>
</methodsynopsis>
<para>
Attempts to cache the sent entity by its last modification date.
</para>
<para>
If the supplied argument is greater than 0, it is handled as timestamp
and will be sent as date of last modification. If it is 0 or omitted,
the current time will be sent as Last-Modified date. If it's negative,
it is handled as expiration time in seconds, which means that if the
requested last modification date is not between the calculated timespan,
the current time will be sent as <literal>Last-Modified</literal> date.
If it's negative, it is handled as expiration time in seconds, which means
that if the requested last modification date is not between the calculated timespan,
the <literal>Last-Modified</literal> header is updated and the actual body will be sent.
</para>
<para>
A log entry will be written to the cache log if the
&link.http.configuration; <literal>http.log.cache</literal>
is set and the cache attempt was successful.
A log entry will be written to the cache log if the &link.http.configuration;
<link linkend="http.configuration.log.cache">http.log.cache</link> is set
and the cache attempt was successful.
</para>
</refsect1>
<refsect1 role="parameters">
@ -88,49 +87,35 @@
-->
<!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>http_cache_last_modified</function> example</title>
<para>
Any text that describes the purpose of the example, or
what goes on in the example should go here (inside the
<example> tag, not out
Caching for 5 seconds.
</para>
<programlisting role="php">
<![CDATA[
<?php
if ($anexample === true) {
echo 'Use the PEAR Coding Standards';
}
http_cache_last_modified(-5);
printf("%s\n", http_date());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Use the PEAR Coding Standards
]]>
</screen>
</example>
</para>
</refsect1>
-->
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_cache_etag</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>

42
reference/http/functions/responses/http-redirect.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-redirect">
<refnamediv>
@ -15,36 +15,24 @@
<methodparam choice="opt"><type>bool</type><parameter>session = FALSE</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>status</parameter></methodparam>
</methodsynopsis>
<para>
Redirect to the given url.
</para>
<para>
The supplied url will be expanded with <function>http_build_url</function>, the params array will
The supplied url will be expanded with <function>http_build_url</function>, the <parameter>params</parameter> array will
be treated with <function>http_build_str</function> and the session identification will be appended
if session is true.
</para>
<para>
The HTTP response code will be set according to status.
</para>
<para>
if <parameter>session</parameter> is true. The HTTP response code will be set according to <parameter>status</parameter>.
You can use one of the <link linkend="http.constants.redirect">redirect constants</link> for convenience.
</para>
<para>
Please see <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3">RFC 2616</ulink>
for which redirect response code to use in which situation.
</para>
<para>
By default PHP will decide which response status fits best.
for which redirect response code to use in which situation. By default PHP will decide which response status fits best.
</para>
<para>
To be RFC compliant, &quot;Redirecting to &lt;a&gt;URL&lt;/a&gt;.&quot; will be displayed,
if the client doesn't redirect immediately, and the request method was
another one than HEAD.
if the client doesn't redirect immediately, and the request method was another one than HEAD.
</para>
<para>
A log entry will be written to the redirect log, if the &link.http.configuration;
<emphasis>http.log.redirect</emphasis> is set and the redirect attempt was successful.
<link linkend="http.configuration.log.redirect">http.log.redirect</link> is set and the redirect attempt was successful.
</para>
</refsect1>
@ -130,36 +118,32 @@
-->
<!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>http_redirect</function> example</title>
<para>
Any text that describes the purpose of the example, or
what goes on in the example should go here (inside the
<example> tag, not out
</para>
<programlisting role="php">
<![CDATA[
<?php
if ($anexample === true) {
echo 'Use the PEAR Coding Standards';
}
http_redirect("relpath", array("name" => "value"), true, HTTP_REDIRECT_PERM);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Use the PEAR Coding Standards
HTTP/1.1 301 Moved Permanently
X-Powered-By: PHP/5.2.2
Content-Type: text/html
Location: http://www.example.com/curdor/relpath?name=value&PHPSESSID=abc
Redirecting to <a href="http://www.example.com/curdor/relpath?name=value&PHPSESSID=abc">http://www.example.com/curdor/relpath?name=value&PHPSESSID=abc</a>.
]]>
</screen>
</example>
</para>
</refsect1>
-->
<!-- Use when adding See Also links

16
reference/http/functions/responses/http-send-content-disposition.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-send-content-disposition">
<refnamediv>
@ -10,16 +10,15 @@
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>http_send_content_disposition</methodname>
<methodparam choice="opt"><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>inline = FALSE</parameter></methodparam>
</methodsynopsis>
<para>
Send the Content-Disposition. The Content-Disposition header is very useful
if the data actually sent came from a file or something similar, that should
be &quot;saved&quot; by the client/user (i.e. by browsers &quot;Save as...&quot; popup window).
</para>
&note.http.send.API;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@ -37,7 +36,7 @@
<term><parameter>inline</parameter></term>
<listitem>
<para>
if set to true and the user agent knows how to handle the content type,
if set to &true; and the user agent knows how to handle the content type,
it will probably not cause the popup window to be shown
</para>
</listitem>
@ -119,17 +118,16 @@ Use the PEAR Coding Standards
-->
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_send_data</function></member>
<member><function>http_send_file</function></member>
<member><function>http_send_stream</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>

20
reference/http/functions/responses/http-send-content-type.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-send-content-type">
<refnamediv>
@ -12,12 +12,10 @@
<type>bool</type><methodname>http_send_content_type</methodname>
<methodparam choice="opt"><type>string</type><parameter>content_type = 'application/x-octetstream'</parameter></methodparam>
</methodsynopsis>
<para>
Send the Content-Type of the sent entity. This is particularly important
if you use the <function>http_send</function> API.
Send the Content-Type of the sent entity.
</para>
&note.http.send.API;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@ -41,14 +39,13 @@
</para>
</refsect1>
<!-- Use when ERRORS exist
<refsect1 role="errors">
&reftitle.errors;
<para>
When does this function throw E_* level errors, or exceptions?
Raises an <constant>E_WARNING</constant> when the <parameter>content_type</parameter>
doesn't seem to contain a primary and a secondary part.
</para>
</refsect1>
-->
<!-- Use when a CHANGELOG exists
@ -108,17 +105,16 @@ Use the PEAR Coding Standards
-->
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_send_data</function></member>
<member><function>http_send_file</function></member>
<member><function>http_send_stream</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>

13
reference/http/functions/responses/http-send-data.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-send-data">
<refnamediv>
@ -12,11 +12,9 @@
<type>bool</type><methodname>http_send_data</methodname>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
Sends raw data with support for (multiple) range requests.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@ -107,17 +105,18 @@ Use the PEAR Coding Standards
-->
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_send_file</function></member>
<member><function>http_send_stream</function></member>
<member><function>http_throttle</function></member>
<member><function>http_send_content_type</function></member>
<member><function>http_send_content_disposition</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>

48
reference/http/functions/responses/http-send-file.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-send-file">
<refnamediv>
@ -12,11 +12,20 @@
<type>bool</type><methodname>http_send_file</methodname>
<methodparam><type>string</type><parameter>file</parameter></methodparam>
</methodsynopsis>
<para>
Sends a file with support for (multiple) range requests.
</para>
<para>
This functions behaviour and further action is dependent on the following
&link.http.configuration;s:
<link linkend="http.configuration.send.not_found_404">http.send.not_found_404</link>
&listendand; <link linkend="http.configuration.log.not_found">http.log.not_found</link>.
</para>
<para>
If the &link.http.configuration; <link linkend="http.configuration.send.not_found_404">http.send.not_found_404</link>
is enabled and the &link.http.configuration; <link linkend="http.configuration.log.not_found">http.log.not_found</link>
points to a writable file, a log message is written when the <parameter>file</parameter> was not found.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@ -75,49 +84,52 @@
-->
<!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>http_send_file</function> example</title>
<para>
Any text that describes the purpose of the example, or
what goes on in the example should go here (inside the
<example> tag, not out
</para>
<programlisting role="php">
<![CDATA[
<?php
if ($anexample === true) {
echo 'Use the PEAR Coding Standards';
}
http_send_content_disposition("document.pdf", true);
http_send_content_type("application/pdf");
http_throttle(0.1, 2048);
http_send_file("../report.pdf");
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Use the PEAR Coding Standards
HTTP/1.1 206 Partial Content
X-Powered-By: PHP/5.2.2
Accept-Ranges: bytes
Content-Length: 12345
Content-Range: bytes 0-12344
Content-Type: application/pdf
Content-Disposition: inline; filename="document.pdf"
%PDF...
]]>
</screen>
</example>
</para>
</refsect1>
-->
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_send_data</function></member>
<member><function>http_send_stream</function></member>
<member><function>http_throttle</function></member>
<member><function>http_send_content_type</function></member>
<member><function>http_send_content_disposition</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>

7
reference/http/functions/responses/http-send-last-modified.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-send-last-modified">
<refnamediv>
@ -12,11 +12,10 @@
<type>bool</type><methodname>http_send_last_modified</methodname>
<methodparam choice="opt"><type>int</type><parameter>timestamp</parameter></methodparam>
</methodsynopsis>
<para>
Send a <emphasis>Last-Modified</emphasis> header with a valid HTTP date.
</para>
&note.http.send.API.mayuse;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@ -26,7 +25,7 @@
<term><parameter>timestamp</parameter></term>
<listitem>
<para>
A Unix timestamp, converted it to a valid HTTP date;
a Unix timestamp, converted to a valid HTTP date;
if omitted, the current time will be sent
</para>
</listitem>

8
reference/http/functions/responses/http-send-status.xml
View file

@ -1,10 +1,10 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-send-status">
<refnamediv>
<refname>http_send_status</refname>
<refpurpose>Send status</refpurpose>
<refpurpose>Send HTTP response status</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@ -12,11 +12,9 @@
<type>bool</type><methodname>http_send_status</methodname>
<methodparam><type>int</type><parameter>status</parameter></methodparam>
</methodsynopsis>
<para>
Send HTTP status code.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@ -26,7 +24,7 @@
<term><parameter>status</parameter></term>
<listitem>
<para>
HTTP status code
HTTP status code (100-599)
</para>
</listitem>
</varlistentry>

11
reference/http/functions/responses/http-send-stream.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-send-stream">
<refnamediv>
@ -107,17 +107,18 @@ Use the PEAR Coding Standards
-->
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_send_data</function></member>
<member><function>http_send_file</function></member>
<member><function>http_throttle</function></member>
<member><function>http_send_content_type</function></member>
<member><function>http_send_content_disposition</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>

22
reference/http/functions/responses/http-throttle.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
<refentry id="function.http-throttle">
<refnamediv>
@ -10,15 +10,18 @@
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>http_throttle</methodname>
<methodparam choice="opt"><type>double</type><parameter>sec</parameter></methodparam>
<methodparam choice="opt"><type>float</type><parameter>sec</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>bytes = 40960</parameter></methodparam>
</methodsynopsis>
<para>
Sets the throttle delay and send buffer size for use with http_send() API.
Provides a basic throttling mechanism, which will yield the current process
resp. thread until the entity has been completely sent, though.
Sets the throttle delay and send buffer size.
</para>
<para>
Provides a basic throttling mechanism, which will yield the current process
resp. thread until the entity has been completely sent.
</para>
&note.http.send.API;
</refsect1>
<refsect1 role="parameters">
@ -94,7 +97,7 @@
// ~ 20 kbyte/s
# http_throttle(1, 20000);
# http_throttle(0.5, 10000);
# http_throttle(0.1, 2000);
http_throttle(0.1, 2000);
http_send_file('document.pdf');
?>
?>
@ -105,17 +108,16 @@ http_send_file('document.pdf');
</refsect1>
<!-- Use when adding See Also links
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function></function></member>
<member>Or <link linkend="somethingelse">something else</link></member>
<member><function>http_send_data</function></member>
<member><function>http_send_file</function></member>
<member><function>http_send_stream</function></member>
</simplelist>
</para>
</refsect1>
-->
</refentry>