Rewrite SoapClient constructor documentation #537
Conversation
IMSoP
force-pushed
the
soapclient-constructor-rewrite
branch
from
8d3e513 to
8d1db39
Compare
IMSoP
force-pushed
the
soapclient-constructor-rewrite
branch
from
28b193c to
cf4092e
Compare
IMSoP
force-pushed
the
soapclient-constructor-rewrite
branch
from
cf4092e to
9845255
Compare
This constructor takes a large number of options, most of which were effectively undocumented, leading to a very high volume of User Notes. Some examples and caveats from these notes have been incorporated. The descriptions here are largely based on reverse-engineering the source code (which isn't particularly well commented) and experimenting locally, so may not be 100% accurate, or capture differences between versions.
IMSoP
force-pushed
the
soapclient-constructor-rewrite
branch
from
8791d10 to
8a29bad
Compare
IMSoP
changed the title
| <entry> | ||
| Used with the deprecated | ||
| <link linkend="soapclient.construct.options.ssl-method"> | ||
| <parameter>ssl_method</parameter> option</link> |
There was a problem hiding this comment.
I'm not happy with the indentation here. I think the </link> should go on an own line, or the two lines should be joined (a bit long, but okay-ish). The same indentation occurs several times below.
| @@ -27,15 +26,17 @@ | |||
| <term><parameter>wsdl</parameter></term> | |||
| <listitem> | |||
| <para> | |||
| URI of the <literal>WSDL</literal> file or &null; if working in | |||
| <literal>non-WSDL</literal> mode. | |||
| URI of a WSDL file describing the service, which is used to automatically | |||
There was a problem hiding this comment.
We could mark-up WSDL as acronym (<acronym>WSDL</acronym>), although that wouln't do much, unless we'd actually define the acronym in https://github.com/php/doc-base/blob/master/entities/acronyms.xml.
| <variablelist> | ||
| <varlistentry xml:id="soapclient.construct.options.location"> | ||
| <term> | ||
| <parameter>location</parameter> |
There was a problem hiding this comment.
While it is not uncommon in the manual to use <parameter> for non-parameters, I don't think we should add more of this. A particular issue is that <parameter> tries to create a JS link to an actual parameter with that name. Instead of <parameter>, I suggest to use <literal> here (and below):
| <parameter>location</parameter> | |
| <literal>location</literal> |
| It must be a PEM encoded file which contains your certificate | ||
| and private key. |
There was a problem hiding this comment.
| It must be a PEM encoded file which contains your certificate | |
| and private key. | |
| It must be a PEM encoded file which contains the certificate | |
| and private key. |
| Note that the type names of an element is not necessarily the same as | ||
| the element (tag) name. |
There was a problem hiding this comment.
| Note that the type names of an element is not necessarily the same as | |
| the element (tag) name. | |
| Note that the type name of an element is not necessarily the same as | |
| the element (tag) name. |
| or SSL 3, respectively. | ||
| Specifying <constant>SOAP_SSL_METHOD_SSLv23</constant> has no effect; | ||
| the constant exists only for backwards compatibility. | ||
| As of PHP 7.2, specifying <constant>SOAP_SSL_METHOD_TLS</constant> |
There was a problem hiding this comment.
| As of PHP 7.2, specifying <constant>SOAP_SSL_METHOD_TLS</constant> | |
| As of PHP 7.2.0, specifying <constant>SOAP_SSL_METHOD_TLS</constant> |
| be supported by the installed OpenSSL library. | ||
| </para> | ||
| <para> | ||
| This option is <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. |
There was a problem hiding this comment.
I detest "shouting":
| This option is <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. | |
| This option is <emphasis>deprecated</emphasis> as of PHP 8.1.0. |
or
| This option is <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. | |
| This option is <emphasis role="strong">deprecated</emphasis> as of PHP 8.1.0. |
There was a problem hiding this comment.
While I agree in general, this particular combination is effectively standard style, because it's what's used in the entities in language-snippets.ent, and about a dozen other places.
There are only two instances of <emphasis>deprecated</emphasis> in the entire manual, and none at all of <emphasis role="strong">deprecated</emphasis> or DEPRECATED without any markup (except when mentioning the constant E_DEPRECATED).
I think if we want to standardise on a less shouty style, we should pick one and use it consistently.
There was a problem hiding this comment.
I'm aware (and not pleased) that we use upper case in the language-snippets, but changing that is additional effort for translators (well, not really much effort). I wouldn't want to add more shouting, though.
| <link linkend="soapclient.construct.options.stream-context"> | ||
| <parameter>stream_context</parameter></link> option with | ||
| the 'crypto_method' context parameter. | ||
| <example> |
There was a problem hiding this comment.
It might be better to use an <informalexample> here (since <example>s are numbered). That wouldn't accept a title, though.
|
@IMSoP Pinging author |
@IMSoP Might you have the time to raise the new PR? |
This constructor takes a large number of options, most of which
were effectively undocumented, leading to a very high volume of
User Notes. Some examples and caveats from these notes have been
incorporated.
The descriptions here are largely based on reverse-engineering
the source code (which isn't particularly well commented) and
experimenting locally, so may not be 100% accurate, or capture
differences between versions.