ext/curl: add curl_share_init_persistent

[ericnorris]

This PR adds documentation for curl_share_init_persistent and its respective CurlSharePersistentHandle class.

RFC: https://wiki.php.net/rfc/curl_share_persistence_improvement.

I wrote the documentation by running build/gen_stub.php and also copying bits from other curl documentation pages. Since this is my first time contributing to the PHP documentation, I expect I may have made some mistakes or missed some common patterns that are usually followed.

[pereorga]

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

[ericnorris]

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

[pereorga]

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

[TimWolla]

Some remarks.

[TimWolla]

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).

[ericnorris]

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.

[TimWolla]

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.

[ericnorris]

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"]);.

[Girgias]

Mainly XML markup things:

• XML indent is 1 space, please fix
• Please prefer simpara over para as per the new manual style.

[ericnorris]

Thanks for the review @Girgias, and let me know if my recent commits addressed your comments!

[Girgias]

Minor remaining nit, but LGTM now!

Thank you!