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 all commits
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
79 changes: 79 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,79 @@
<?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;
<simpara>
Represents a persistent cURL "share" handle.
</simpara>
</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>
<simpara>The <constant>CURL_LOCK_DATA_<replaceable>*</replaceable></constant> caches shared between requests using this handle.</simpara>
</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
-->
154 changes: 154 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,154 @@
<?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>
<simpara>
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
<parameter>share_options</parameter> is found, it will be reused.
</simpara>
</refsect1>

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

<variablelist>
<varlistentry>
<term><parameter>share_options</parameter></term>
<listitem>
<simpara>
A non-empty array of <constant>CURL_LOCK_DATA_<replaceable>*</replaceable></constant> constants.
</simpara>
<note>
<simpara>
<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.
</simpara>
</note>
</listitem>
</varlistentry>
</variablelist>

</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Returns a <classname>CurlSharePersistentHandle</classname>.
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<itemizedlist>
<listitem>
<simpara>
If <parameter>share_options</parameter> is empty, this function throws
a <exceptionname>ValueError</exceptionname>.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>share_options</parameter> contains a value not matching
a <constant>CURL_LOCK_DATA_<replaceable>*</replaceable></constant>,
this function throws a <classname>ValueError</classname>.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>share_options</parameter> contains
<constant>CURL_LOCK_DATA_COOKIE</constant>, this function throws a
<exceptionname>ValueError</exceptionname>.
</simpara>
</listitem>
<listitem>
<simpara>
If <parameter>share_options</parameter> contains a non-integer value,
this function throws a <exceptionname>TypeError</exceptionname>.
</simpara>
</listitem>
</itemizedlist>
</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>
<simpara>
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.
</simpara>

<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 $ch1.
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>
<member><function>curl_share_init</function></member>
</simplelist>
</refsect1>

</refentry>
<!-- 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/curl/functions/curl-share-init.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ curl_close($ch2);
<simplelist>
<member><function>curl_share_setopt</function></member>
<member><function>curl_share_close</function></member>
<member><function>curl_share_init_persistent</function></member>
</simplelist>
</para>
</refsect1>
Expand Down
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