wincache-ucache-add.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 32040dd7e5d98c136502134110681f80443dd000 Maintainer: evvc Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.wincache-ucache-add" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>wincache_ucache_add</refname>
  <refpurpose>Добавляет переменную в пользовательский кеш, только если переменная ещё не существует в кеше</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>wincache_ucache_add</methodname>
   <methodparam><type>string</type><parameter>key</parameter></methodparam>
   <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <methodsynopsis>
   <type>bool</type><methodname>wincache_ucache_add</methodname>
   <methodparam><type>array</type><parameter>values</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>unused</parameter><initializer>NULL</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>ttl</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   Добавляет переменную в пользовательский кеш, только если эта переменная ещё не существует в кеше.
   Добавленная переменная остаётся в пользовательском кеше, пока не истечёт срок её действия
   или она не будет удалена с помощью функций <function>wincache_ucache_delete</function> или <function>wincache_ucache_clear</function>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>key</parameter></term>
     <listitem>
      <para>
       Сохраняет переменную с использованием этого имени <parameter>key</parameter>. Если переменная с таким же <parameter>key</parameter>
       уже существует, завершится ошибкой и вернёт &false;. <parameter>key</parameter> чувствителен к регистру.
       Чтобы переопределить значение, даже если <parameter>key</parameter> уже существует, используйте функцию <function>wincache_ucache_set</function>.
       <parameter>key</parameter> также может принимать массив пар имя => значение, где имена будут использоваться в качестве ключей.
       Это можно использовать для добавления нескольких значений в кеш за одну операцию, что позволяет избежать состояния гонки.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
       Значение переменной, которую необходимо сохранить. <parameter>Value</parameter> поддерживает все типы данных, кроме ресурсов,
       таких как дескрипторы файлов.
       Параметр игнорируется, если первым аргументом является массив. Общее руководство - передать &null; в качестве <parameter>value</parameter>
       при использовании массива <parameter>key</parameter>.
       Если <parameter>value</parameter> является объектом или массивом, содержащим объекты,
       то объекты будут сериализованы. Подробнее о сериализации объектов смотрите в описании <link linkend="object.sleep">__sleep()</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>values</parameter></term>
     <listitem>
      <para>
       Ассоциативный массив ключей и значений.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>ttl</parameter></term>
     <listitem>
      <para>
       Время, в течение которого переменная находится в кеше, в секундах. После того, как значение, указанное в <parameter>ttl</parameter>
       будет передано, сохранённая переменная будет удалена из кеша.
       Параметр принимает значение по умолчанию <literal>0</literal>, что означает, что переменная останется в кеше,
       пока она не будет явно удалена с помощью функций <function>wincache_ucache_delete</function> или <function>wincache_ucache_clear</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   Если <parameter>key</parameter> является строкой, функция возвращает &true; в случае успешного выполнения и &false; в случае возникновения ошибки.
  </simpara>
  <para>
   Если <parameter>key</parameter> является массивом, функция возвращает:
   <itemizedlist spacing="compact">
    <listitem>
     <simpara>
      Если все пары имя => значение в массиве могут быть установлены, функция возвращает пустой массив;
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Если все пары имя => значение в массиве не могут быть установлены, функция возвращает &false;;
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Если некоторые из них могут быть установлены, а другие - нет,
      функция возвращает массив с парами name => value, которые не удалось добавить в пользовательский кеш.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Пример использования <function>wincache_ucache_add</function> с <parameter>key</parameter> в виде строки</title>
    <programlisting role="php">
<![CDATA[
<?php
$bar = 'BAR';
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_get('foo'));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
bool(true)
bool(false)
string(3) "BAR"
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Пример использования <function>wincache_ucache_add</function> с <parameter>key</parameter> в виде массива</title>
    <programlisting role="php">
<![CDATA[
<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(0) { }
array(4) {
  ["green"]=> int(-1)
  ["Blue"]=> int(-1)
  ["yellow"]=> int(-1)
  ["cyan"]=> int(-1)
}
string(1) "6"
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>wincache_ucache_set</function></member>
    <member><function>wincache_ucache_get</function></member>
    <member><function>wincache_ucache_delete</function></member>
    <member><function>wincache_ucache_clear</function></member>
    <member><function>wincache_ucache_exists</function></member>
    <member><function>wincache_ucache_meminfo</function></member>
    <member><function>wincache_ucache_info</function></member>
    <member><link linkend="object.sleep">__sleep()</link></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
-->