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

Hooks reflection #4110

Open
wants to merge 21 commits into
base: master
Choose a base branch
from
Open

Hooks reflection #4110

Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
38dc68b
Add reflection stubs for property hooks
Girgias Nov 11, 2024
251dde9
Document getHook().
Crell Nov 20, 2024
a223e45
Formatting fixes from Girgias
Crell Nov 20, 2024
f1ea0fd
Remove buggy markup.
Crell Nov 20, 2024
e785925
Remove unnecessary changelogs.
Crell Dec 1, 2024
c886f17
Document hasHook()
Crell Dec 1, 2024
ab2bad6
Document getSettableType()
Crell Dec 1, 2024
f5bd564
Document getHooks()
Crell Dec 1, 2024
f3e03c1
Document hasHooks()
Crell Dec 1, 2024
cb40073
Document isFinal()
Crell Dec 1, 2024
619f35c
Update isPublic() to warn about more involved writes.
Crell Dec 1, 2024
3ccdcd6
Document isPrivateSet() and isProtectedSet()
Crell Dec 1, 2024
30a6b0d
Document setRawValue()
Crell Dec 1, 2024
8ae95ef
Document getRawValue()
Crell Dec 1, 2024
c546679
Document isVirtual()
Crell Dec 1, 2024
1443547
Remove stray template code.
Crell Dec 1, 2024
dcdd281
Document PropertyHookType.
Crell Dec 1, 2024
70af0e9
Document isAbstract()
Crell Dec 1, 2024
6c45349
Some XML nits
Girgias Dec 13, 2024
56a73e5
Document touch() doesn't clear the stat cache.
Crell Dec 13, 2024
a204b11
Make examples generate output.
Crell Dec 14, 2024
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/reflection/book.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@
&reference.reflection.reflectionattribute;
&reference.reflection.reflector;
&reference.reflection.reflectionexception;
&reference.reflection.propertyhooktype;

</book>

Expand Down
57 changes: 57 additions & 0 deletions reference/reflection/propertyhooktype.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
<?xml version="1.0" encoding="utf-8"?>
<reference xmlns="http://docbook.org/ns/docbook" xml:id="enum.reflection.propertyhooktype" role="enum">
<title>The \PropertyHookType Enum</title>
<titleabbrev>\PropertyHookType</titleabbrev>

<partintro>
<section xml:id="enum.reflection.propertyhooktype.intro">
&reftitle.intro;
<simpara>
The <enumname>\PropertyHookType</enumname> enum lists the legal
types of <link linkend="language.oop5.property-hooks">property hook</link>.
</simpara>
</section>

<section xml:id="enum.reflection.propertyhooktype.synopsis">
&reftitle.enumsynopsis;

<enumsynopsis>
<enumname>\PropertyHookType</enumname>

<enumitem>
<enumidentifier>Get</enumidentifier>
<enumitemdescription>
Indicates a <literal>get</literal> hook.
</enumitemdescription>
</enumitem>

<enumitem>
<enumidentifier>Set</enumidentifier>
<enumitemdescription>
Indicates a <literal>set</literal> hook.
</enumitemdescription>
</enumitem>
</enumsynopsis>
</section>
</partintro>
</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
-->
91 changes: 91 additions & 0 deletions reference/reflection/reflectionproperty/gethook.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionproperty.gethook" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionProperty::getHook</refname>
<refpurpose>Returns a reflection object for a specified hook.</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="ReflectionProperty">
<modifier>public</modifier> <type class="union"><type>ReflectionMethod</type><type>null</type></type><methodname>ReflectionProperty::getHook</methodname>
<methodparam><type>PropertyHookType</type><parameter>type</parameter></methodparam>
</methodsynopsis>
<simpara>
Gets the reflection of the property's hook, if any.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>PropertyHookType</parameter></term>
<listitem>
<simpara>
The type of hook to request.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
If the requested hook is defined, a <classname>ReflectionMethod</classname> instance will be returned.
If not, the method will return &null;
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example xml:id="reflectionproperty.gethook.example.basic">
<title><methodname>ReflectionProperty::getHook</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
class Example
{
public string $name { get => "Name here"; }
}

$rClass = new \ReflectionClass(Example::class);
$rProp = $rClass->getProperty('name');
$rProp->getHook(PropertyHookType::Get); // Returns an instance of \ReflectionMethod.
$rProp->getHook(PropertyHookType::Set); // Returns null.
Copy link
Member

Choose a reason for hiding this comment

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

I would prefer a var_dump() (possible using ::class) with a screen tag instead of a comment, as those are more annoying for translations.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hm. In that case, do we even need the screen tag anymore? Just have it show output and leave it to the new wasm runner.

Copy link
Member

Choose a reason for hiding this comment

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

Yes, I have php/web-php#1180 to reuse the output.

I don't see the point in forcing everyone to run WASM, and require JS, just to see the expected output.

?>
]]>
</programlisting>
</example>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><classname>ReflectionMethod</classname></member>
<member><classname>PropertyHookType</classname></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
-->
92 changes: 92 additions & 0 deletions reference/reflection/reflectionproperty/gethooks.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionproperty.gethooks" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionProperty::getHooks</refname>
<refpurpose>Returns an array of all hooks on this property</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="ReflectionProperty">
<modifier>public</modifier> <type>array</type><methodname>ReflectionProperty::getHooks</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns a list of all hooks on this property.
</simpara>
</refsect1>

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

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
an array of <classname>ReflectionMethod</classname> objects keyed by the hook they are for.
Girgias marked this conversation as resolved.
Show resolved Hide resolved
For example, a property with both <literal>get</literal> and <literal>set</literal> hooks will return
a 2 element array with string keys <literal>get</literal> and <literal>set</literal>,
each of which are a <classname>ReflectionMethod</classname> object.
The order in which they are returned is explicitly undefined.
If no hooks are defined, an empty array is returned.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example xml:id="reflectionproperty.gethooks.example.basic">
<title><methodname>ReflectionProperty::getHooks</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
class Example
{
public string $name { get => "Name here"; }

public int $count;
}

$rClass = new \ReflectionClass(Example::class);
$rProp = $rClass->getProperty('name');
// Returns ['get' => ReflectionMethod()]
$rProp->getHooks();

$rProp = $rClass->getProperty('count');
// Returns []
$rProp->getHooks();
Crell marked this conversation as resolved.
Show resolved Hide resolved
?>
]]>
</programlisting>
</example>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><classname>ReflectionMethod</classname></member>
<member><methodname>ReflectionProperty::hasHooks</methodname></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
-->
108 changes: 108 additions & 0 deletions reference/reflection/reflectionproperty/getrawvalue.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionproperty.getrawvalue" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionProperty::getRawValue</refname>
<refpurpose>Returns the value of a property, bypassing a get hook if defined</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="ReflectionProperty">
<modifier>public</modifier> <type>mixed</type><methodname>ReflectionProperty::getRawValue</methodname>
<methodparam><type>object</type><parameter>object</parameter></methodparam>
</methodsynopsis>
&warn.undocumented.func;
<simpara>
Returns the value of a property, bypassing a <literal>get</literal> hook if defined.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>object</parameter></term>
<listitem>
<simpara>
The object from which to retrieve a value.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
The stored value of the property, bypassing a <literal>get</literal> hook if defined.
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<simpara>
If the property is virtual, an <classname>Error</classname> will be thrown,
as there is no raw value to retrieve.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example xml:id="reflectionproperty.getrawvalue.example.basic">
<title><methodname>ReflectionProperty::getRawValue</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
class Example
{
public string $tag {
get => strtolower($this->tag);
}
}

$example = new Example();
$example->tag = 'PHP';

$rClass = new \ReflectionClass(Example::class);
$rProp = $rClass->getProperty('tag');

// These would go through the get hook, so would produce "php".
print $example->tag;
print $rProp->getValue($example);

// But this would bypass the hook and produce "PHP".
print $rProp->setRawValue($example);
?>
]]>
</programlisting>
</example>
Crell marked this conversation as resolved.
Show resolved Hide resolved
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><link linkend="language.oop5.visibility-members-aviz">Asymmetric property visibility</link></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
-->
Loading