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

Add SensitiveParameterValue documentation #2165

Merged
merged 5 commits into from
Jan 11, 2023
Merged

Add SensitiveParameterValue documentation #2165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
aa607a5
Bootstrap SensitiveParameterValue with docgen
TimWolla Jan 10, 2023
6d57bb2
Run `gen_stub.php --replace-classsynopses` and `--replace-methodsynop…
TimWolla Jan 10, 2023
a9a0598
Add property
TimWolla Jan 10, 2023
4fe34a2
Add descriptions for SensitiveParameterValue
TimWolla Jan 10, 2023
c5626e0
Drop trailing whitespace
TimWolla Jan 10, 2023
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 language/predefined/interfaces.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
&language.predefined.stringable;
&language.predefined.unitenum;
&language.predefined.backedenum;
&language.predefined.sensitiveparametervalue;

</part>

Expand Down
101 changes: 101 additions & 0 deletions language/predefined/sensitiveparametervalue.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
<?xml version="1.0" encoding="utf-8"?>
<phpdoc:classref xml:id="class.sensitiveparametervalue" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The SensitiveParameterValue class</title>
<titleabbrev>SensitiveParameterValue</titleabbrev>

<partintro>

<!-- {{{ SensitiveParameterValue intro -->
<section xml:id="sensitiveparametervalue.intro">
&reftitle.intro;
<para>
The <classname>SensitiveParameterValue</classname> class allows wrapping sensitive
values to protect them against accidental exposure.
</para>
<para>
Values of parameters having the <classname>SensitiveParameter</classname> attribute
will automatically be wrapped inside of a <classname>SensitiveParameterValue</classname>
object within stack traces.
</para>
</section>
<!-- }}} -->

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

<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass>
<classname>SensitiveParameterValue</classname>
</ooclass>

<classsynopsisinfo>
<ooclass>
<modifier>final</modifier>
<classname>SensitiveParameterValue</classname>
</ooclass>
</classsynopsisinfo>

<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
<fieldsynopsis>
<modifier>private</modifier>
<modifier>readonly</modifier>
<type>mixed</type>
<varname linkend="sensitiveparametervalue.props.value">value</varname>
</fieldsynopsis>

<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.sensitiveparametervalue')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='SensitiveParameterValue'])">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.sensitiveparametervalue')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='SensitiveParameterValue'])">
<xi:fallback/>
</xi:include>
</classsynopsis>
<!-- }}} -->

</section>

<!-- {{{ Random\Randomizer properties -->
<section xml:id="sensitiveparametervalue.props">
&reftitle.properties;
<variablelist>
<varlistentry xml:id="sensitiveparametervalue.props.value">
<term><varname>value</varname></term>
<listitem>
<para>
The sensitive value to be protected against accidental exposure.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- }}} -->

</partintro>

&language.predefined.sensitiveparametervalue.construct;
&language.predefined.sensitiveparametervalue.debuginfo;
&language.predefined.sensitiveparametervalue.getvalue;
Comment on lines +77 to +79
Copy link
Member Author

Choose a reason for hiding this comment

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

FWIW: It's not great that no automated entity file is generated for classes outside of reference/ :-(

Copy link
Member

Choose a reason for hiding this comment

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

Indeed. Should be possible to also generate entities.*.xml for language/.


</phpdoc:classref>
<!-- 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
-->
69 changes: 69 additions & 0 deletions language/predefined/sensitiveparametervalue/construct.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="sensitiveparametervalue.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>SensitiveParameterValue::__construct</refname>
<refpurpose>Constructs a new SensitiveParameterValue object</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<constructorsynopsis role="SensitiveParameterValue">
<modifier>public</modifier> <methodname>SensitiveParameterValue::__construct</methodname>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</constructorsynopsis>
<para>

</para>

&warn.undocumented.func;

</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
An arbitrary value that should be stored inside the <classname>SensitiveParameterValue</classname> object.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<!-- Return values commented out, as constructors generally don't return a
value. Uncomment this if you do need a return values section (for
example, because there's also a procedural version of the method).
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>

</para>
</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
-->
52 changes: 52 additions & 0 deletions language/predefined/sensitiveparametervalue/debuginfo.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="sensitiveparametervalue.debuginfo" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>SensitiveParameterValue::__debugInfo</refname>
<refpurpose>Protects the sensitive value against accidental exposure</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="SensitiveParameterValue">
<modifier>public</modifier> <type>array</type><methodname>SensitiveParameterValue::__debugInfo</methodname>
<void/>
</methodsynopsis>
<para>
Returns an empty &array; to protect the sensitive value against accidental exposure when using <function>var_dump</function>.
</para>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
An empty &array;.
</para>
</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
-->
55 changes: 55 additions & 0 deletions language/predefined/sensitiveparametervalue/getvalue.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="sensitiveparametervalue.getvalue" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>SensitiveParameterValue::getValue</refname>
<refpurpose>Returns the sensitive value</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="SensitiveParameterValue">
<modifier>public</modifier> <type>mixed</type><methodname>SensitiveParameterValue::getValue</methodname>
<void/>
</methodsynopsis>
<para>

</para>

&warn.undocumented.func;

</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The sensitive value.
</para>
</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
-->
4 changes: 4 additions & 0 deletions language/predefined/versions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,10 @@
<function name="AllowDynamicProperties::__construct" from="PHP 8 &gt;= 8.2.0"/>
<function name="SensitiveParameter" from="PHP 8 &gt;= 8.2.0"/>
<function name="SensitiveParameter::__construct" from="PHP 8 &gt;= 8.2.0"/>
<function name="SensitiveParameterValue" from="PHP 8 &gt;= 8.2.0"/>
<function name="SensitiveParameterValue::__construct" from="PHP 8 &gt;= 8.2.0"/>
<function name="SensitiveParameterValue::__debugInfo" from="PHP 8 &gt;= 8.2.0"/>
<function name="SensitiveParameterValue::getValue" from="PHP 8 &gt;= 8.2.0"/>
</versions>
<!-- Keep this comment at the end of the file
Local variables:
Expand Down