Skip to content

Commit

Permalink
PHP 8.4: Document StreamBucket (#4297)
Browse files Browse the repository at this point in the history
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
  • Loading branch information
kocsismate and cmb69 authored Dec 20, 2024
1 parent f6678a7 commit 32caa89
Show file tree
Hide file tree
Showing 7 changed files with 210 additions and 33 deletions.
3 changes: 3 additions & 0 deletions language-snippets.ent
Original file line number Diff line number Diff line change
Expand Up @@ -2677,6 +2677,9 @@ objects. Otherwise, a <classname>PharException</classname> will be thrown.</par
<varname linkend="streamwrapper.props.context">streamWrapper::$context</varname>
property is updated if a valid context is passed to the caller function.</para></note>'>

<!ENTITY stream.bucket.param '<parameter>bucket</parameter> expects a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was expected.'>
<!ENTITY stream.bucket.return 'This function returns a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was returned.'>

<!-- Gmagick -->
<!ENTITY gmagick.return.success 'Returns &true; on success.'>
<!ENTITY gmagick.gmagickexception.throw 'Throws an
Expand Down
23 changes: 21 additions & 2 deletions reference/stream/functions/stream-bucket-append.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,34 @@
<methodsynopsis>
<type>void</type><methodname>stream_bucket_append</methodname>
<methodparam><type>resource</type><parameter>brigade</parameter></methodparam>
<methodparam><type>object</type><parameter>bucket</parameter></methodparam>
<methodparam><type>StreamBucket</type><parameter>bucket</parameter></methodparam>
</methodsynopsis>

&warn.undocumented.func;

</refsect1>

</refentry>
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>&stream.bucket.param;</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
49 changes: 22 additions & 27 deletions reference/stream/functions/stream-bucket-make-writeable.xml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>object</type><type>null</type></type><methodname>stream_bucket_make_writeable</methodname>
<type class="union"><type>StreamBucket</type><type>null</type></type><methodname>stream_bucket_make_writeable</methodname>
<methodparam><type>resource</type><parameter>brigade</parameter></methodparam>
</methodsynopsis>
<para>
Expand Down Expand Up @@ -40,34 +40,30 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a bucket object with the properties listed below or &null;.
<variablelist>
<varlistentry>
<term>
<property>data</property>
(<type>string</type>)
</term>
<listitem>
<para>
<parameter>data</parameter> <literal>bucket</literal> The current string in the bucket.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<property>datalen</property>
(<type>integer</type>)
</term>
<listitem>
<para>
<parameter>datalen</parameter> <literal>bucket</literal> The length of the string in the bucket.
</para>
</listitem>
</varlistentry>
</variablelist>
Returns a bucket object or &null;.
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>&stream.bucket.return;</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
Expand All @@ -78,7 +74,6 @@
</para>
</refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
23 changes: 21 additions & 2 deletions reference/stream/functions/stream-bucket-new.xml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>object</type><methodname>stream_bucket_new</methodname>
<type>StreamBucket</type><methodname>stream_bucket_new</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>buffer</parameter></methodparam>
</methodsynopsis>
Expand All @@ -20,8 +20,27 @@

</refsect1>

</refentry>
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>&stream.bucket.return;</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
23 changes: 21 additions & 2 deletions reference/stream/functions/stream-bucket-prepend.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<methodsynopsis>
<type>void</type><methodname>stream_bucket_prepend</methodname>
<methodparam><type>resource</type><parameter>brigade</parameter></methodparam>
<methodparam><type>object</type><parameter>bucket</parameter></methodparam>
<methodparam><type>StreamBucket</type><parameter>bucket</parameter></methodparam>
</methodsynopsis>
<para>
This function can be called to prepend a bucket to a bucket brigade. It
Expand Down Expand Up @@ -50,6 +50,26 @@
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>&stream.bucket.param;</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
Expand Down Expand Up @@ -81,7 +101,6 @@ print file_get_contents('php://filter/read=test/resource=foo');
</para>
</refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
121 changes: 121 additions & 0 deletions reference/stream/streambucket.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<reference xml:id="class.streambucket" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

<title>The StreamBucket class</title>
<titleabbrev>StreamBucket</titleabbrev>

<partintro>

<section xml:id="streambucket.intro">
&reftitle.intro;
<simpara>
A stream bucket is a chunk of a stream which can be extracted from bucket brigades.
</simpara>
</section>

<section xml:id="streambucket.synopsis">
&reftitle.classsynopsis;

<classsynopsis class="class">
<ooclass>
<modifier>final</modifier>
<classname>StreamBucket</classname>
</ooclass>

<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>
<modifier>readonly</modifier>
<type>resource</type>
<varname linkend="streambucket.props.bucket">bucket</varname>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<modifier>readonly</modifier>
<type>string</type>
<varname linkend="streambucket.props.data">data</varname>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<modifier>readonly</modifier>
<type>int</type>
<varname linkend="streambucket.props.datalen">datalen</varname>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<modifier>readonly</modifier>
<type>int</type>
<varname linkend="streambucket.props.datalength">dataLength</varname>
</fieldsynopsis>
</classsynopsis>
</section>

<section xml:id="streambucket.props">
&reftitle.properties;
<variablelist>
<varlistentry xml:id="streambucket.props.bucket">
<term>resource <varname>bucket</varname></term>
<listitem>
<simparapara>A <literal>userfilter.bucket</literal> resource.</simparapara>
</listitem>
</varlistentry>
<varlistentry xml:id="streambucket.props.data">
<term>string <varname>data</varname></term>
<listitem>
<simparapara>The current string in the bucket.</simparapara>
</listitem>
</varlistentry>
<varlistentry xml:id="streambucket.props.datalen">
<term>int <varname>datalen</varname></term>
<listitem>
<simparapara>
The length of the string in the bucket.
Deprecated as of PHP 8.4 in favor of <literal>StreamBucket::$dataLength</literal>.
</simparapara>
</listitem>
</varlistentry>
<varlistentry xml:id="streambucket.props.dataLength">
<term>int <varname>dataLength</varname></term>
<listitem>
<simparapara>The length of the string in the bucket.</simparapara>
</listitem>
</varlistentry>
</variablelist>
</section>

<section role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>stream_bucket_new</function></member>
<member><function>stream_bucket_append</function></member>
<member><function>stream_bucket_prepend</function></member>
<member><function>stream_bucket_make_writeable</function></member>
</simplelist>
</section>

</partintro>

&reference.stream.entities.streambucket;

</reference>
<!-- 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
-->
1 change: 1 addition & 0 deletions reference/stream/versions.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
Do NOT translate this file
-->
<versions>
<function name="streambucket" from="PHP 8 &gt;= 8.4.0"/>
<function name="stream_bucket_append" from="PHP 5, PHP 7, PHP 8"/>
<function name="stream_bucket_make_writeable" from="PHP 5, PHP 7, PHP 8"/>
<function name="stream_bucket_new" from="PHP 5, PHP 7, PHP 8"/>
Expand Down

0 comments on commit 32caa89

Please sign in to comment.