ext/curl: add curl_share_init_persistent (#4363)

reference/curl/book.xml

@@ -29,6 +29,7 @@
  &reference.curl.curlhandle;
  &reference.curl.curlmultihandle;
  &reference.curl.curlsharehandle;
+ &reference.curl.curlsharepersistenthandle;
  &reference.curl.curlfile;
  &reference.curl.curlstringfile;
 

reference/curl/curlsharepersistenthandle.xml

@@ -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
+-->

reference/curl/functions/curl-share-init-persistent.xml

@@ -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
+-->

reference/curl/functions/curl-share-init.xml

@@ -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>

reference/curl/versions.xml

@@ -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"/>
@@ -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"/>
@@ -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