Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ext/curl: add curl_share_init_persistent #4363

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
+238 −1
Open

ext/curl: add curl_share_init_persistent #4363

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
94ef10c
`ext/curl`: add `curl_share_init_persistent`
ericnorris Jan 7, 2025
4a1018b
address first round of PR comments
ericnorris Jan 8, 2025
fac4701
address second round of PR comments
ericnorris Jan 13, 2025
b6ab47d
style: reindent
ericnorris Jan 27, 2025
238f738
style: prefer `simpara`
ericnorris Jan 27, 2025
91bc4e4
use `<note>` and `<classname>`
ericnorris Jan 27, 2025
9b04644
style: don't indent final comment
ericnorris Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions reference/curl/book.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
&reference.curl.curlhandle;
&reference.curl.curlmultihandle;
&reference.curl.curlsharehandle;
&reference.curl.curlsharepersistenthandle;
&reference.curl.curlfile;
&reference.curl.curlstringfile;

Expand Down
80 changes: 80 additions & 0 deletions reference/curl/curlsharepersistenthandle.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<reference xml:id="class.curlsharepersistenthandle" 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 CurlSharePersistentHandle class</title>
<titleabbrev>CurlSharePersistentHandle</titleabbrev>

<partintro>

<!-- {{{ CurlSharePersistentHandle intro -->
<section xml:id="curlsharepersistenthandle.intro">
&reftitle.intro;
<para>
ericnorris marked this conversation as resolved.
Show resolved Hide resolved
Represents a persistent cURL "share" handle.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description should probably be synced with the one of CurlShareHandle (it's fine to update the other if the current wording is not good, but given they are so similar, they should have a similar documentation).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, my hesitation is that the description of CurlShareHandle is somewhat unique in that it is the result of converting a resource to an object, and that seems noteworthy enough to remain that way. What might you suggest changing CurlShareHandle to? Something like:

Represents a cURL "share" handle. Prior to PHP 8.0.0, this was a resource.

</para>
</section>
<!-- }}} -->

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

<!-- {{{ Synopsis -->
<classsynopsis class="class">
<ooclass>
<modifier>final</modifier>
<classname>CurlSharePersistentHandle</classname>
</ooclass>

<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>
<modifier>readonly</modifier>
<type>array</type>
<varname linkend="curlsharepersistenthandle.props.options">options</varname>
</fieldsynopsis>
</classsynopsis>
<!-- }}} -->

</section>

<!-- {{{ CurlSharePersistentHandle properties -->
<section xml:id="curlsharepersistenthandle.props">
&reftitle.properties;
<variablelist>
<varlistentry xml:id="curlsharepersistenthandle.props.options">
<term><varname>options</varname></term>
<listitem>
<para>An array of <constant>CURL_LOCK_DATA_*</constant> constants shared in this handle.</para>
ericnorris marked this conversation as resolved.
Show resolved Hide resolved
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- }}} -->


</partintro>

<!-- &reference.curl.entities.curlsharepersistenthandle; -->

</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
-->
ericnorris marked this conversation as resolved.
Show resolved Hide resolved
120 changes: 120 additions & 0 deletions reference/curl/functions/curl-share-init-persistent.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="function.curl-share-init-persistent" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>curl_share_init_persistent</refname>
<refpurpose>Initialize a <emphasis role="bold">persistent</emphasis> cURL share handle.</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>CurlSharePersistentHandle</type><methodname>curl_share_init_persistent</methodname>
<methodparam><type>array</type><parameter>share_options</parameter></methodparam>
</methodsynopsis>
<para>
Initialize a <emphasis role="bold">persistent</emphasis> cURL share handle with the given share options. Unlike <function>curl_share_init</function>, handles created by this function will not be destroyed at the end of the PHP request. If a persistent share handle with the same set of <literal>$share_options</literal> is found, it will be reused.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be mentioned that this behavior might vary depending on the Server API (e.g., CLI, FPM, Apache Module)?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps! Do we have any existing documentation that talks about the differences between SAPIs that I could reference directly or indirectly?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question, I don't know. It would definitely be useful to have this documented on php.net.

ericnorris marked this conversation as resolved.
Show resolved Hide resolved
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;

<variablelist>
<varlistentry>
<term><parameter>share_options</parameter></term>
<listitem>
<para>
A non-empty array of <constant>CURL_LOCK_DATA_*</constant> constants.
</para>
<para>
<emphasis role="bold">Note:</emphasis> <constant>CURL_LOCK_DATA_COOKIE</constant> is not allowed and, if specified, this function will throw a <exceptionname>ValueError</exceptionname>. Sharing cookies between PHP requests may lead to inadvertently mixing up sensitive cookies between users.
</para>
</listitem>
</varlistentry>
</variablelist>

</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Returns a persistent cURL share handle.
ericnorris marked this conversation as resolved.
Show resolved Hide resolved
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<simpara>
A <exceptionname>ValueError</exceptionname> is thrown when <literal>$share_options</literal> either: is empty, contains <constant>CURL_LOCK_DATA_COOKIE</constant>, or contains a value not matching a <constant>CURL_LOCK_DATA_*</constant> constant.
</simpara>
<simpara>
A <exceptionname>TypeError</exceptionname> is thrown when <literal>$share_options</literal> contains a value that cannot be cast to an integer.
</simpara>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if there's any hard rule around this (@Girgias?), but for the ext/random documentation I've made this a proper list and separate bullet points for each case. See:

doc-en/reference/random/random/randomizer/getfloat.xml

Lines 277 to 295 in 4d8af08

<itemizedlist>
<listitem>
<simpara>
If the value of <parameter>min</parameter> is not finite (<function>is_finite</function>),
a <classname>ValueError</classname> will be thrown.
</simpara>
</listitem>
<listitem>
<simpara>
If the value of <parameter>max</parameter> is not finite (<function>is_finite</function>),
a <classname>ValueError</classname> will be thrown.
</simpara>
</listitem>
<listitem>
<simpara>
If the requested interval does not contain any values,
a <classname>ValueError</classname> will be thrown.
</simpara>
</listitem>

In this case:

  • If <parameter>share_options</parameters> is empty, a <classname>ValueError</classname> will be thrown.
  • If <parameter>share_options</parameters> contains a value not matching a <constant>CURL_LOCK_DATA_<replaceable>*</replaceable></constant>, a <classname>ValueError</classname> will be thrown.
  • If <parameter>share_options</parameters> contains <constant>CURL_LOCK_DATA_COOKIE</constant>, a <classname>ValueError</classname> will be thrown.

The TypeError can possibly even be left out. While it's not strictly part of the method signature, passing invalid types will lead to value errors and the bit about “if you don't pass a CURL_LOCK_DATA_ constant you get an error” is probably sufficient.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, this is exactly the kind of thing I was looking for feedback on. I decided to leave the TypeError in since you can trigger it by doing something like curl_share_init_persistent(["q"]);.

</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example xml:id="function.curl-share-init-persistent.example.basic">
<title><function>curl_share_init_persistent</function> example</title>
<para>
This example will create a persistent cURL share handle and demonstrate sharing connections between them. If this is executed in a long-lived PHP SAPI, <literal>$sh</literal> will survive between SAPI requests.
</para>

<programlisting role="php">
<![CDATA[
<?php
// Create or retrieve a persistent cURL share handle set to share DNS lookups and connections.
$sh = curl_share_init([CURL_LOCK_DATA_DNS, CURL_LOCK_DATA_CONNECT]);

// Initialize the first cURL handle and assign the share handle to it
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// Execute the first cURL handle. This may reuse the connection from an earlier SAPI request.
curl_exec($ch1);

// Initialize the second cURL handle and assign the share handle to it
$ch2 = curl_init("http://example.com/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// Execute the second cURL handle. This will reuse the connection from $ch2.
ericnorris marked this conversation as resolved.
Show resolved Hide resolved
curl_exec($ch2);

// Close the cURL handles
curl_close($ch1);
curl_close($ch2);
?>

]]>
</programlisting>
</example>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>curl_setopt</function></member>
ericnorris marked this conversation as resolved.
Show resolved Hide resolved
</simplelist>
</refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
ericnorris marked this conversation as resolved.
Show resolved Hide resolved
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
-->
4 changes: 3 additions & 1 deletion reference/curl/versions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<!--
Do NOT translate this file
-->
<versions>
<versions>
<function name="curl_close" from="PHP 4 &gt;= 4.0.2, PHP 5, PHP 7, PHP 8"/>
<function name="curl_copy_handle" from="PHP 5, PHP 7, PHP 8"/>
<function name="curl_errno" from="PHP 4 &gt;= 4.0.3, PHP 5, PHP 7, PHP 8"/>
Expand Down Expand Up @@ -32,6 +32,7 @@
<function name="curl_share_errno" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
<function name="curl_share_strerror" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
<function name="curl_share_init" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/>
<function name="curl_share_init_persistent" from="PHP 8 &gt;= 8.5.0"/>
<function name="curl_share_setopt" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/>
<function name="curl_strerror" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/>
<function name="curl_unescape" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/>
Expand All @@ -53,6 +54,7 @@
<function name="curlhandle" from="PHP 8"/>
<function name="curlmultihandle" from="PHP 8"/>
<function name="curlsharehandle" from="PHP 8"/>
<function name="curlsharepersistenthandle" from="PHP 8 &gt;= 8.5.0"/>
</versions>

<!-- Keep this comment at the end of the file
Expand Down