svn: /phpdoc/ja/trunk/language/ attributes.xml functions.xml

Added: phpdoc/ja/trunk/language/attributes.xml
===================================================================
--- phpdoc/ja/trunk/language/attributes.xml	                        (rev 0)
+++ phpdoc/ja/trunk/language/attributes.xml	2020-12-05 11:50:21 UTC (rev 351900)
@@ -0,0 +1,378 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 351898 Maintainer: mumumu Status: working -->
+ <chapter xml:id="language.attributes" xmlns="http://docbook.org/ns/docbook">
+  <title>Attributes</title>
+  <sect1 xml:id="language.attributes.overview">
+   <title>Attributes overview</title>
+   <?phpdoc print-version-for="attributes"?>
+
+   <para>
+    Attributes allow to add structured, machine-readable metadata information
+    on declarations in code: Classes, methods, functions, parameters,
+    properties and constants can be the target of an attribute. The metadata
+    defined by attributes can then be inspected at runtime using the
+    <link linkend="book.reflection">Reflection
+     APIs</link>. Attributes could therefore be thought of as a configuration
+    language embedded directly into code.
+   </para>
+
+   <para>
+    With attributes the generic implementation of a
+    feature and its concrete use in an application can be decoupled. In a way it is
+    comparable to interfaces and their implementations. But where
+    interfaces and implementations are about code, attributes are about
+    annotating extra information and configuration. Interfaces can
+    be implemented by classes, yet attributes can also be declared
+    on methods, functions, parameters, properties and class constants.
+    As such they are more flexible than interfaces.
+   </para>
+
+    <para>
+     A simple example of attribute usage is to convert an interface
+     that has optional methods to use attributes. Lets assume an
+     <literal>ActionHandler</literal>
+      interface representing an operation in an application, where some
+      implementations of an action handler require setup and others do not. Instead of requiring all classes
+      that implement <literal>ActionHandler</literal> to implement
+       a method <literal>setUp()</literal>,
+        we use an attribute that can be used instead. One benefit
+        of this approach is that we can use the attribute several times.
+    </para>
+
+   <example>
+    <title>Implementing optional methods of an interface with Attributes</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+interface ActionHandler
+{
+    public function execute();
+}
+
+#[Attribute]
+class SetUp {}
+
+class CopyFile implements ActionHandler
+{
+      public string $fileName;
+      public string $targetDirectory;
+
+      #[SetUp]
+      public function fileExists()
+      {
+          if (!file_exists($this->fileName)) {
+              throw new RuntimeException("File does not exist");
+          }
+      }
+
+      #[SetUp]
+      public function targetDirectoryExists()
+      {
+          @mkdir($this->targetDirectory);
+      }
+
+      public function execute()
+      {
+          copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
+      }
+}
+
+function executeAction(ActionHandler $actionHandler) {
+      $reflection = new ReflectionObject($actionHandler);
+
+      foreach ($reflection->getMethods() as $method) {
+          $attributes = $reflection->getAttributes(SetUp::class)
+
+          if (count($attributes) > 0) {
+              $methodName = $method->getName();
+
+              $actionHandler->$methodName();
+          }
+      }
+
+      $actionHandler->execute();
+}
+
+$copyAction = new CopyFile();
+$copyAction->fileName = "/tmp/foo.jpg";
+$copyAction->targetDirectory = "/home/user";
+
+executeAction($copyAction);
+]]>
+     </programlisting>
+    </example>
+  </sect1>
+
+  <sect1 xml:id="language.attributes.syntax">
+   <title>Attribute syntax</title>
+
+   <para>
+    There are several parts to the attributes syntax. First, attribute
+    declaration are always enclosed with a starting
+    <literal>#[</literal> and a corresponding ending
+    <literal>]</literal>. Inside, one or many attributes are listed,
+    seperated by comma. The attribute name is an unqualified, qualified
+    or fully-qualified name as described in <link linkend="language.namespaces.basics">Using Namespaces Basics</link>.
+    Arguments to the attribute are optional, but are enclosed in the usual parenthesis <literal>()</literal>.
+    Arguments to attributes can only be literal values or constant expressions. Both positional and
+    named arguments syntax can be used.
+   </para>
+
+   <para>
+    Attribute names and their arguments are resolved to a class and the arguments are passed to its constructor,
+    when an instance of the attribute is requested through the Reflection API. As such
+    a class should be introduced for each attribute.
+   </para>
+
+   <example>
+    <title>Attribute Syntax</title>
+
+    <programlisting role="php">
+<![CDATA[
+<?php
+// a.php
+namespace MyExample;
+
+use Attribute;
+
+#[Attribute]
+class MyAttribute
+{
+    const VALUE = 'value';
+
+    private $value;
+
+    public function __construct($value = null)
+    {
+        $this->value = $value;
+    }
+}
+
+// b.php
+
+namespace Another;
+
+use MyExample\MyAttribute;
+
+#[MyAttribute]
+#[\MyExample\MyAttribute]
+#[MyAttribute(1234)]
+#[MyAttribute(value: 1234)]
+#[MyAttribute(MyAttribute::VALUE)]
+#[MyAttribute(array("key" => "value"))]
+#[MyAttribute(100 + 200)]
+class Thing
+{
+}
+
+#[MyAttribute(1234), MyAttribute(5678)]
+class AnotherThing
+{
+}
+]]>
+    </programlisting>
+   </example>
+  </sect1>
+
+
+  <sect1 xml:id="language.attributes.reflection">
+   <title>Reading Attributes with the Reflection API</title>
+
+   <para>
+    To access attributes from classes, methods, functions, parameters, properties and class constants,
+    the Reflection API provides the method <function>getAttributes</function> on each of the corresponding
+    Reflection objects. This method returns an array of <classname>ReflectionAttribute</classname> instances
+    that can be queried for attribute name, arguments and to instantiate an instance of the represented attribute.
+   </para>
+
+   <para>
+    This separation of reflected attribute representation from actual instance increases control of the programmer
+    to handle errors regarding missing attribute classes, mistyped or missing arguments. Only after
+    calling <function>newInstance</function>, objects of the attribute class are instantiated and the correct matching of arguments
+    is validated, not earlier.
+   </para>
+
+   <example>
+    <title>Reading Attributes using Reflection API</title>
+
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+#[Attribute]
+class MyAttribute
+{
+    public $value;
+
+    public function __construct($value)
+    {
+        $this->value = $value;
+    }
+}
+
+#[MyAttribute(value: 1234)]
+class Thing
+{
+}
+
+function dumpAttributeData($reflection) {
+    $attributes = $reflection->getAttributes();
+
+    foreach ($attributes as $attribute) {
+       var_dump($attribute->getName());
+       var_dump($attribute->getArguments());
+       var_dump($attribute->newInstance());
+    }
+}
+
+dumpAttributeData(new ReflectionClass(Thing::class));
+/*
+string(11) "MyAttribute"
+array(1) {
+  ["value"]=>
+  int(1234)
+}
+object(MyAttribute)#3 (1) {
+  ["value"]=>
+  int(1234)
+}
+*/
+
+]]>
+    </programlisting>
+   </example>
+
+   <para>
+    Instead of iterating all attributes on the reflection instance, only those
+    of a particular attribute class can be
+    retrieved by passing the searched attribute class name as argument.
+   </para>
+
+   <example>
+    <title>Reading Specific Attributes using Reflection API</title>
+
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+function dumpMyAttributeData($reflection) {
+    $attributes = $reflection->getAttributes(MyAttribute::class);
+
+    foreach ($attributes as $attribute) {
+       var_dump($attribute->getName());
+       var_dump($attribute->getArguments());
+       var_dump($attribute->newInstance());
+    }
+}
+
+dumpAttributeData(new ReflectionClass(Thing::class));
+]]>
+     </programlisting>
+    </example>
+  </sect1>
+
+  <sect1 xml:id="language.attributes.classes">
+   <title>Declaring Attribute Classes</title>
+
+   <para>
+    While not strictly required it is recommended to create an actual class for every attribute.
+    In the most simple case only an empty class is needed with the <literal>#[Attribute]</literal> attribute declared
+    that can be imported from the global namespace with a use statement.
+   </para>
+
+  <example>
+   <title>Using target specification to restrict where attributes can be used</title>
+
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+namespace Example;
+
+use Attribute;
+
+#[Attribute]
+class MyAttribute
+{
+}
+]]>
+   </programlisting>
+  </example>
+
+  <para>
+   To restrict the type of declaration an attribute can be assigned to, a bitmask can be passed as the first
+   argument to the <literal>#[Attribute]</literal> declaration.
+  </para>
+
+  <example>
+   <title>Simple Attribute Class</title>
+
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+namespace Example;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
+class MyAttribute
+{
+}
+]]>
+    </programlisting>
+
+    <para>
+     Declaring <classname>MyAttribute</classname> on another type will now throw an exception during
+     the call to <function>ReflectionAttribute::newInstance</function>
+    </para>
+   </example>
+
+   <para>
+    By default an attribute can only be used once per declaration. If the attribute should be repeatable on declarations it must
+    be specified as part of the bitmask to the <literal>#[Attribute]</literal> declaration.
+   </para>
+
+   <example>
+    <title>Using IS_REPEATBLE to allow attribute on a declaration multiple times</title>
+
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+namespace Example;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
+class MyAttribute
+{
+}
+]]>
+    </programlisting>
+
+   </example>
+  </sect1>
+ </chapter>
+
+<!-- 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
+-->


Property changes on: phpdoc/ja/trunk/language/attributes.xml
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL
\ No newline at end of property
Modified: phpdoc/ja/trunk/language/functions.xml
===================================================================
--- phpdoc/ja/trunk/language/functions.xml	2020-12-05 11:48:59 UTC (rev 351899)
+++ phpdoc/ja/trunk/language/functions.xml	2020-12-05 11:50:21 UTC (rev 351900)
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 351733 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 351733 Maintainer: takagi Status: working -->
 <!-- CREDITS: hirokawa,mumumu -->
  <chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook">
   <title>関数</title>
@@ -230,6 +230,29 @@
 ]]>
     </programlisting>
    </example>
+   <para>
+    As of PHP 8.0.0, passing optional arguments after mandatory arguments
+    is deprecated. This can generally be resolved by dropping the default value.
+    One exception to this rule are arguments of the form
+    <code>Type $param = null</code>, where the &null; default makes the type implicitly
+    nullable. This usage remains allowed, though it is recommended to use an
+    explicit nullable type instead.
+   </para>
+   <example>
+    <title>Passing optional arguments after mandatory arguments</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function foo($a = [], $b) {} // Before
+function foo($a, $b) {}      // After
+
+function bar(A $a = null, $b) {} // Still allowed
+function bar(?A $a, $b) {}       // Recommended
+?>
+]]>
+    </programlisting>
+   </example>
+
    <sect2 xml:id="functions.arguments.by-reference">
     <title>引数の参照渡し</title>

@@ -556,6 +579,111 @@
     </sect3>

    </sect2>
+
+   <sect2 xml:id="functions.named-arguments">
+    <title>Named Arguments</title>
+
+    <para>
+     PHP 8.0.0 introduced named arguments as an extension of the existing
+     positional parameters. Named arguments allow passing arguments to a
+     function based on the parameter name, rather than the parameter position.
+     This makes the meaning of the argument self-documenting, makes the
+     arguments order-independent and allows skipping default values arbitrarily.
+    </para>
+
+    <para>
+     Named arguments are passed by prefixing the value with the parameter name
+     followed by a colon. Using reserved keywords as parameter names is allowed.
+     The parameter name must be an identifier, specifying dynamically
+     is not allowed.
+    </para>
+
+    <example>
+     <title>Named argument syntax</title>
+     <programlisting role="php">
+      <![CDATA[
+<?php
+myFunction(paramName: $value);
+array_foobar(array: $value);
+
+// NOT supported.
+function_name($variableStoringParamName: $value);
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <example>
+     <title>Positional arguments versus named arguments</title>
+     <programlisting role="php">
+      <![CDATA[
+<?php
+// Using positional arguments:
+array_fill(0, 100, 50);
+
+// Using named arguments:
+array_fill(start_index: 0, num: 100, value: 50);
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <para>
+     The order in which the named arguments are passed does not matter.
+    </para>
+
+    <example>
+     <title>Same example as above with a different order of parameters</title>
+     <programlisting role="php">
+      <![CDATA[
+<?php
+array_fill(value: 50, num: 100, start_index: 0);
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <para>
+     Named arguments can be combined with positional arguments. In this case,
+     the named arguments must come after the positional arguments.
+     It is also possible to specify only some of the optional arguments of a
+     function, regardless of their order.
+    </para>
+
+    <example>
+     <title>Combining named arguments with positional arguments</title>
+     <programlisting role="php">
+      <![CDATA[
+<?php
+htmlspecialchars($string, double_encode: false);
+// Same as
+htmlspecialchars($string, ENT_COMPAT | ENT_HTML401, 'UTF-8', false);
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <para>
+     Passing the same parameter multiple times results in an Error exception.
+    </para>
+
+    <example>
+     <title>Error exception when passing the same parameter multiple times</title>
+     <programlisting role="php">
+      <![CDATA[
+<?php
+function foo($param) { ... }
+
+foo(param: 1, param: 2);
+// Error: Named parameter $param overwrites previous argument
+foo(1, param: 2);
+// Error: Named parameter $param overwrites previous argument
+?>
+]]>
+     </programlisting>
+    </example>
+
+   </sect2>
   </sect1>

   <sect1 xml:id="functions.returning-values">