svn: /phpdoc/ru/trunk/ language/attributes.xml language/types/numeric-strings.xml reference/apcu/functions/apcu-key-info.xml reference/intl/dateformatter-constants.xml

Added: phpdoc/ru/trunk/language/attributes.xml
===================================================================
--- phpdoc/ru/trunk/language/attributes.xml	                        (rev 0)
+++ phpdoc/ru/trunk/language/attributes.xml	2020-12-07 09:46:42 UTC (rev 351945)
@@ -0,0 +1,377 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 351926 Maintainer: rjhdby Status: ready -->
+<!-- Reviewed: no -->
+
+<chapter xml:id="language.attributes" xmlns="http://docbook.org/ns/docbook">
+ <title>Атрибуты</title>
+ <sect1 xml:id="language.attributes.overview">
+  <title>Введение в атрибуты</title>
+  <?phpdoc print-version-for="attributes"?>
+
+  <para>
+   Атрибуты позволяют добавлять структурированные, машиночитаемые метаданные для
+   следующих деклараций в коде: классы, методы, функции, параметры, свойства и константы класса.
+   Привязанные метаданные можно получить во время исполнения используя
+   <link linkend="book.reflection">Reflection API</link>.
+   Таким образом, атрибуты можно рассматривать как язык конфигурации, встроенный
+   непосредственно в код.
+  </para>
+
+  <para>
+   С помощью атрибутов можно разделить абстрактную реализацию какого
+   либо функционала и особенности его использования в коде. В некотором
+   смасле это можно сравнить с разделением интерфейса и его реализаций.
+   Но интерфейсы и реализации - это про код, а атрибуты - про добавление
+   дополнитебьной информации и конфигурацию. Интерфейсы могут
+   реализовываться только классами, тогда как атрибуты также применимы для
+   методов, функций, параметров, свойств и констант классов. Таким образом
+   они представляют собой гораздо более гибкий механизм, чем интерфейсы.
+  </para>
+
+  <para>
+   Давайте разберём использование атрибутов на простом примере реализации опциональных
+   методов для интерфейса . Примем, что интерфейс <literal>ActionHandler</literal> описывает некую
+   операцию в приложении. Одни реализации этого интерфейса требуют
+   предварительной настройки, а другие нет. И, вместо того, чтобы вносить в
+   интерфейс <literal>ActionHandler</literal> дополнительный метод
+   <literal>setUp()</literal>, который для части реализаций будет пустым,
+   мы используем атрибуты. Одним из преимуществ этого подхода является то,
+   что мы можем использовать атрибут несколько раз.
+  </para>
+
+  <example>
+   <title>Реализация опциональных методов интерфейса с помощью атрибутов</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("Файл не найден");
+        }
+    }
+
+    #[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 = $method->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>Синтаксис атрибутов</title>
+
+  <para>
+   Синтаксис атрибутов состоит из нескольких частей. Во-первых, декларация
+   атрибута всегда начинается с символа <literal>#[</literal> и заканчивается
+   <literal>]</literal>. Внутри перечисление из одного или более, разделённых запятой, атрибутов.
+   Атрибуты можно задавать с помощью неполных, полных и абсолютных имён, как описано в разделе
+   <link linkend="language.namespaces.basics">Использование пространства имен: основы</link>.
+   Аргументы атрибутов опциональны, но если они есть, то заключаются в скобки <literal>()</literal>.
+   Аргументы атрибутов могут быть либо конкретными значениями, либо константными выражениями. Для аргументов можно
+   использовать как позиционный синтаксис, так и синтаксис именованных аргументов.
+  </para>
+
+  <para>
+   Когда атрибут запрафивается с помощью Reflection API, его имя трактуется как имя класса, а аргументы передаются в его конструктор.
+   Таким образом, для каждого атрубита должен существовать соответствующий класс.
+  </para>
+
+  <example>
+   <title>Синтаксис атрибутов</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>Чтение атрибутов с помощью Reflection API</title>
+
+  <para>
+   Для доступа к атрибутам классов, методов, функций, параметров, свойств и констант класса, в Reflection API
+   присутствует метод <function>getAttributes</function> для каждого из перечисленных объектов рефлексии.
+   Этот метод возвращает массив экземпляров <classname>ReflectionAttribute</classname>, у которого можно запросить
+   имя атрибута и его аргументы, а также и инстанцировать объект представляющий атрибут.
+  </para>
+
+  <para>
+   Такое отделение свойств атрибута от явного инстанцирования даёт программисту более полный контроль над
+   обработкой ошибок, связанных с отсутствующим классом атрибута и некорректностью его аргументов.
+   Объект атрибута будет создан и проверен на корректность аргументов только после вызова
+   <function>newInstance</function>, не раньше.
+  </para>
+
+  <example>
+   <title>Чтение атрибутов с помощью 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>
+    Вместо того, чтобы последовательно перебирать все атрибуты объекта рефлексии,
+    можно указать имя класса в качестве аргумента и получить только подходящие атрибуты.
+   </para>
+
+   <example>
+    <title>Чтение конкретных атрибутов с помощью 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>Объявление классов атрибутов</title>
+
+   <para>
+    Создавать классы для атрибутов не обязательно, но крайне рекомендуется.
+    В самом простом случае, требуется просто пустой класс с атибутом <literal>#[Attribute]</literal>, который
+    можно импортировать из глобального пространства имён с помощью оператора use.
+   </para>
+
+   <example>
+    <title>Ограничение допустимых целей для использования атрибута</title>
+
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+namespace Example;
+
+use Attribute;
+
+#[Attribute]
+class MyAttribute
+{
+}
+]]>
+    </programlisting>
+   </example>
+
+   <para>
+    Для ограничения того, с каким типом деклараций можно использовать конкретный атрибут, можно передать
+    битовую маску первым параметром в <literal>#[Attribute]</literal>.
+   </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>
+     После этого, аннотирование атрибутом <classname>MyAttribute</classname> чего либо, отличного от метода или функции приведёт
+     к выбросу исключения при вызове <function>ReflectionAttribute::newInstance</function>
+    </para>
+   </example>
+
+   <para>
+    По умолчанию, атрибут можно использовать только один раз для каждой сущности. Если нужна возможность указывать
+    несколько одинаковых атрибутов для одной сущности - можно выставить соответствующий флаг в битовой маске
+    для декларации <literal>#[Attribute]</literal>.
+   </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/ru/trunk/language/attributes.xml
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ 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/ru/trunk/language/types/numeric-strings.xml
===================================================================
--- phpdoc/ru/trunk/language/types/numeric-strings.xml	2020-12-07 08:25:14 UTC (rev 351944)
+++ phpdoc/ru/trunk/language/types/numeric-strings.xml	2020-12-07 09:46:42 UTC (rev 351945)
@@ -71,7 +71,8 @@
   <title>Поведение до PHP 8.0.0</title>
   <para>
    До PHP 8.0.0, строка считалась числовой только в случае, если она
-   начиналась с пробельных ситмволов. Если она завершалась пробельными символами -
+   <emphasis>начиналась</emphasis> с пробельных ситмволов. Если она
+   <emphasis>завершалась</emphasis> пробельными символами -
    она считалась префиксной числовой.
   </para>


Added: phpdoc/ru/trunk/reference/apcu/functions/apcu-key-info.xml
===================================================================
--- phpdoc/ru/trunk/reference/apcu/functions/apcu-key-info.xml	                        (rev 0)
+++ phpdoc/ru/trunk/reference/apcu/functions/apcu-key-info.xml	2020-12-07 09:46:42 UTC (rev 351945)
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 351787 Maintainer: rjhdby Status: ready -->
+<!-- Reviewed: no -->
+
+<refentry xml:id="function.apcu-key-info" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>apcu_key_info</refname>
+  <refpurpose>
+   Получить детальную информацию о ключе в кеше
+  </refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>array</type><methodname>apcu_key_info</methodname>
+   <methodparam><type>string</type><parameter>key</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Получить детальную информацию о ключе в кеше
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>key</parameter></term>
+     <listitem>
+      <para>
+       Получить детальную информацию о ключе в кеше
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &null; или массив с информацией
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Пример использования <function>apcu_key_info</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+apcu_add('a','b');
+var_dump(apcu_key_info('a'));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+array(7) {
+  ["hits"]=>
+  int(0)
+  ["access_time"]=>
+  int(1606701783)
+  ["mtime"]=>
+  int(1606701783)
+  ["creation_time"]=>
+  int(1606701783)
+  ["deletion_time"]=>
+  int(0)
+  ["ttl"]=>
+  int(0)
+  ["refs"]=>
+  int(0)
+}
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>apcu_store</function></member>
+    <member><function>apcu_fetch</function></member>
+    <member><function>apcu_delete</function></member>
+   </simplelist>
+  </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
+-->
\ No newline at end of file


Property changes on: phpdoc/ru/trunk/reference/apcu/functions/apcu-key-info.xml
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ 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/ru/trunk/reference/intl/dateformatter-constants.xml
===================================================================
--- phpdoc/ru/trunk/reference/intl/dateformatter-constants.xml	2020-12-07 08:25:14 UTC (rev 351944)
+++ phpdoc/ru/trunk/reference/intl/dateformatter-constants.xml	2020-12-07 09:46:42 UTC (rev 351945)
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 351133 Maintainer: rjhdby Status: ready -->
+<!-- EN-Revision: 351939 Maintainer: rjhdby Status: ready -->
 <!-- Reviewed: yes Maintainer: sergey -->
 <!-- $Revision$ -->
 <section xml:id="intl.intldateformatter-constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -54,6 +54,62 @@
      <simpara>Наиболее сокращенный формат, только самые необходимые данные (12/13/52 или 3:30pm)</simpara>
     </listitem>
    </varlistentry>
+   <varlistentry xml:id="intldateformatter.constants.relative_full">
+    <term>
+     <constant>IntlDateFormatter::RELATIVE_FULL</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+      То же, что и <constant>IntlDateFormatter::FULL</constant>, но "вчера", "сегодня" и "завтра"
+      выводятся как <literal>yesterday</literal>, <literal>today</literal> и
+      <literal>tomorrow</literal>.
+      Доступно с PHP 8.0.0 только для <parameter>dateType</parameter>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="intldateformatter.constants.relative_long">
+    <term>
+     <constant>IntlDateFormatter::RELATIVE_LONG</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+      То же, что и <constant>IntlDateFormatter::LONG</constant>, но "вчера", "сегодня" и "завтра"
+      выводятся как <literal>yesterday</literal>, <literal>today</literal> и
+      <literal>tomorrow</literal>.
+      Доступно с PHP 8.0.0 только для <parameter>dateType</parameter>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="intldateformatter.constants.relative_medium">
+    <term>
+     <constant>IntlDateFormatter::RELATIVE_MEDIUM</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+      То же, что и <constant>IntlDateFormatter::MEDIUM</constant>, но "вчера", "сегодня" и "завтра"
+      выводятся как <literal>yesterday</literal>, <literal>today</literal> и
+      <literal>tomorrow</literal>.
+      Доступно с PHP 8.0.0 только для <parameter>dateType</parameter>.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="intldateformatter.constants.relative_short">
+    <term>
+     <constant>IntlDateFormatter::RELATIVE_SHORT</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+      То же, что и <constant>IntlDateFormatter::SHORT</constant>, но "вчера", "сегодня" и "завтра"
+      выводятся как <literal>yesterday</literal>, <literal>today</literal> и
+      <literal>tomorrow</literal>.
+      Доступно с PHP 8.0.0 только для <parameter>dateType</parameter>.
+     </simpara>
+    </listitem>
+   </varlistentry>
   </variablelist>
  </para>