mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Update the documentation for Memcached::get*() for breaking API changes introduced in v3.0
-- Provided by Martin Georgiev git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@342643 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Peter Cowburn
parent
1cf8f88730
commit
7e2f7b05e2
5 changed files with 284 additions and 39 deletions
|
|
@ -323,6 +323,41 @@
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.have-msgpack">
|
||||
<term><constant>Memcached::HAVE_MSGPACK</constant></term>
|
||||
<listitem>
|
||||
<para>Indicates whether msgpack serializer support is available.</para>
|
||||
<para>Type: <literal>boolean</literal>.</para>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.have-session">
|
||||
<term><constant>Memcached::HAVE_SESSION</constant></term>
|
||||
<listitem>
|
||||
<para>Type: <literal>boolean</literal>.</para>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.have-sasl">
|
||||
<term><constant>Memcached::HAVE_SASL</constant></term>
|
||||
<listitem>
|
||||
<para>Type: <literal>boolean</literal>.</para>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.get-extended">
|
||||
<term><constant>Memcached::GET_EXTENDED</constant></term>
|
||||
<listitem>
|
||||
<para>A flag for <function>Memcached::get</function>, <function>Memcached::getMulti</function> and
|
||||
<function>Memcached::getMultiByKey</function> to ensure that the CAS token values
|
||||
are returned as well.</para>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.get-preserve-order">
|
||||
<term><constant>Memcached::GET_PRESERVE_ORDER</constant></term>
|
||||
<listitem>
|
||||
|
|
@ -484,6 +519,55 @@
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.res-auth-problem">
|
||||
<term><constant>Memcached::RES_AUTH_PROBLEM</constant></term>
|
||||
<listitem>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.res-auth-failure">
|
||||
<term><constant>Memcached::RES_AUTH_FAILURE</constant></term>
|
||||
<listitem>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.res-auth-continue">
|
||||
<term><constant>Memcached::RES_AUTH_CONTINUE</constant></term>
|
||||
<listitem>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.res-e2big">
|
||||
<term><constant>Memcached::RES_E2BIG</constant></term>
|
||||
<listitem>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.res-key-too-big">
|
||||
<term><constant>Memcached::RES_KEY_TOO_BIG</constant></term>
|
||||
<listitem>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.res-server-temporarily-disabled">
|
||||
<term><constant>Memcached::RES_SERVER_TEMPORARILY_DISABLED</constant></term>
|
||||
<listitem>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry xml:id="memcached.constants.res-server-memory-allocation-failure">
|
||||
<term><constant>Memcached::RES_SERVER_MEMORY_ALLOCATION_FAILURE</constant></term>
|
||||
<listitem>
|
||||
<para>Available as of Memcached 3.0.0.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</appendix>
|
||||
|
||||
|
|
|
|||
|
|
@ -13,13 +13,13 @@
|
|||
<modifier>public</modifier> <type>mixed</type><methodname>Memcached::get</methodname>
|
||||
<methodparam><type>string</type><parameter>key</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>callable</type><parameter>cache_cb</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>float</type><parameter role="reference">cas_token</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>int</type><parameter>$flags</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
<function>Memcached::get</function> returns the item that was previously
|
||||
stored under the <parameter>key</parameter>. If the item is found and
|
||||
<parameter>cas_token</parameter> variable is provided, it will contain the
|
||||
CAS token value for the item. See
|
||||
for <parameter>flags</parameter> is given <constant>Memcached::GET_EXTENDED</constant>,
|
||||
it will return the CAS token value for the item. See
|
||||
<methodname>Memcached::cas</methodname> for how to use CAS tokens. <link
|
||||
linkend="memcached.callbacks">Read-through caching callback</link> may be
|
||||
specified via <parameter>cache_cb</parameter> parameter.
|
||||
|
|
@ -49,10 +49,11 @@
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>cas_token</parameter></term>
|
||||
<term><parameter>flags</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The variable to store the CAS token in.
|
||||
Flags to control the returned result. When value of <constant>Memcached::GET_EXTENDED</constant>
|
||||
is given will return the CAS token.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -116,6 +117,29 @@ if (!($ip = $m->get('ip_block'))) {
|
|||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="changelog">
|
||||
&reftitle.changelog;
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>&Version;</entry>
|
||||
<entry>&Description;</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>3.0.0</entry>
|
||||
<entry>
|
||||
The <parameter role="reference">cas_token</parameter> parameter was removed.
|
||||
Instead <parameter>flags</parameter> was added and when it is given the value of <constant>Memcached::GET_EXTENDED</constant> it will ensure the CAS token to be fetched.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
<methodparam><type>string</type><parameter>server_key</parameter></methodparam>
|
||||
<methodparam><type>string</type><parameter>key</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>callable</type><parameter>cache_cb</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>float</type><parameter role="reference">cas_token</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
<function>Memcached::getByKey</function> is functionally equivalent to
|
||||
|
|
@ -53,10 +53,11 @@
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>cas_token</parameter></term>
|
||||
<term><parameter>flags</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The variable to store the CAS token in.
|
||||
Flags to control the returned result. When value of <constant>Memcached::GET_EXTENDED</constant>
|
||||
is given will return the CAS token.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -73,6 +74,29 @@
|
|||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="changelog">
|
||||
&reftitle.changelog;
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>&Version;</entry>
|
||||
<entry>&Description;</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>3.0.0</entry>
|
||||
<entry>
|
||||
The <parameter role="reference">cas_token</parameter> parameter was removed.
|
||||
Instead <parameter>flags</parameter> was added and when it is given the value of <constant>Memcached::GET_EXTENDED</constant> it will ensure the CAS token to be fetched.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -12,32 +12,30 @@
|
|||
<methodsynopsis>
|
||||
<modifier>public</modifier> <type>mixed</type><methodname>Memcached::getMulti</methodname>
|
||||
<methodparam><type>array</type><parameter>keys</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>array</type><parameter role="reference">cas_tokens</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
<function>Memcached::getMulti</function> is similar to
|
||||
<methodname>Memcached::get</methodname>, but instead of a single key
|
||||
item, it retrieves multiple items the keys of which are specified in the
|
||||
<parameter>keys</parameter> array. If <parameter>cas_tokens</parameter>
|
||||
variable is provided, it is filled with the CAS token values for the found
|
||||
items.
|
||||
<parameter>keys</parameter> array.
|
||||
<note>
|
||||
<para>
|
||||
Unlike <methodname>Memcached::get</methodname> it is not possible to
|
||||
specify a read-through cache callback for
|
||||
<function>Memcached::getMulti</function>, because the memcache protocol
|
||||
does not provide information on which keys were not found in the multi-key
|
||||
request.
|
||||
Before v3.0 a second argument <parameter role="reference">cas_tokens</parameter> was in use.
|
||||
It was filled with the CAS token values for the found items.
|
||||
The <parameter role="reference">cas_tokens</parameter> parameter was removed in v3.0 of the extension.
|
||||
It was replaced with a new flag <constant>Memcached::GET_EXTENDED</constant>
|
||||
that needs is to be used as the value for <parameter>flags</parameter>.
|
||||
</para>
|
||||
</note>
|
||||
</para>
|
||||
<para>
|
||||
The <parameter>flags</parameter> parameter can be used to specify
|
||||
additional options for <function>Memcached::getMulti</function>. Currently,
|
||||
the only available option is
|
||||
<constant>Memcached::GET_PRESERVE_ORDER</constant> that ensures that the
|
||||
additional options for <function>Memcached::getMulti</function>.
|
||||
<constant>Memcached::GET_PRESERVE_ORDER</constant> ensures that the
|
||||
keys are returned in the same order as they were requested in.
|
||||
<constant>Memcached::GET_EXTENDED</constant> ensures that the
|
||||
CAS tokens will be fetched too.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
@ -53,14 +51,6 @@
|
|||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>cas_tokens</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The variable to store the CAS tokens for the found items.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>flags</parameter></term>
|
||||
<listitem>
|
||||
|
|
@ -85,10 +75,48 @@
|
|||
&reftitle.examples;
|
||||
<para>
|
||||
<example>
|
||||
<title><function>Memcached::getMulti</function> example</title>
|
||||
<title><function>Memcached::getMulti</function> example for Memcached v3</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
// Valid for v3 of the extension
|
||||
|
||||
$m = new Memcached();
|
||||
$m->addServer('localhost', 11211);
|
||||
|
||||
$items = array(
|
||||
'key1' => 'value1',
|
||||
'key2' => 'value2',
|
||||
'key3' => 'value3'
|
||||
);
|
||||
$m->setMulti($items);
|
||||
$result = $m->getMulti(array('key1', 'key3', 'badkey'));
|
||||
var_dump($result);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
array(2) {
|
||||
["key1"]=>
|
||||
string(6) "value1"
|
||||
["key3"]=>
|
||||
string(6) "value3"
|
||||
}
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><function>Memcached::getMulti</function> example for Memcached v1 and v2</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
// Valid for v1 and v2 of the extension
|
||||
|
||||
$m = new Memcached();
|
||||
$m->addServer('localhost', 11211);
|
||||
|
||||
|
|
@ -122,12 +150,60 @@ array(2) {
|
|||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><constant>Memcached::GET_PRESERVE_ORDER</constant> example</title>
|
||||
<title><constant>Memcached::GET_PRESERVE_ORDER</constant> example for Memcached v3</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
// Valid for v3 of the extension
|
||||
|
||||
$m = new Memcached();
|
||||
$m->addServer('localhost', 11211);
|
||||
|
||||
$data = array(
|
||||
'foo' => 'foo-data',
|
||||
'bar' => 'bar-data',
|
||||
'baz' => 'baz-data',
|
||||
'lol' => 'lol-data',
|
||||
'kek' => 'kek-data',
|
||||
);
|
||||
|
||||
$m->setMulti($data, 3600);
|
||||
|
||||
$keys = array_keys($data);
|
||||
$keys[] = 'zoo';
|
||||
$got = $m->getMulti($keys, Memcached::GET_PRESERVE_ORDER);
|
||||
|
||||
foreach ($got as $k => $v) {
|
||||
echo "$k $v\n";
|
||||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
foo foo-data
|
||||
bar bar-data
|
||||
baz baz-data
|
||||
lol lol-data
|
||||
kek kek-data
|
||||
zoo
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><constant>Memcached::GET_PRESERVE_ORDER</constant> example for Memcached v1 and v2</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
// Valid for v1 and v2 of the extension
|
||||
|
||||
$m = new Memcached();
|
||||
$m->addServer('localhost', 11211);
|
||||
|
||||
|
|
@ -167,6 +243,29 @@ zoo
|
|||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="changelog">
|
||||
&reftitle.changelog;
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>&Version;</entry>
|
||||
<entry>&Description;</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>3.0.0</entry>
|
||||
<entry>
|
||||
The <parameter role="reference">cas_tokens</parameter> parameter was removed.
|
||||
The <constant>Memcached::GET_EXTENDED</constant> was added and when passed as a flag it ensures the CAS tokens to be fetched.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -13,7 +13,6 @@
|
|||
<modifier>public</modifier> <type>array</type><methodname>Memcached::getMultiByKey</methodname>
|
||||
<methodparam><type>string</type><parameter>server_key</parameter></methodparam>
|
||||
<methodparam><type>array</type><parameter>keys</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>string</type><parameter role="reference">cas_tokens</parameter></methodparam>
|
||||
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
|
|
@ -44,14 +43,6 @@
|
|||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>cas_tokens</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The variable to store the CAS tokens for the found items.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>flags</parameter></term>
|
||||
<listitem>
|
||||
|
|
@ -72,6 +63,29 @@
|
|||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="changelog">
|
||||
&reftitle.changelog;
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>&Version;</entry>
|
||||
<entry>&Description;</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>3.0.0</entry>
|
||||
<entry>
|
||||
The <parameter role="reference">cas_tokens</parameter> parameter was removed.
|
||||
The <constant>Memcached::GET_EXTENDED</constant> was added and when passed as a flag it ensures the CAS tokens to be fetched.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<para>
|
||||
|
|
|
|||
Loading…
Reference in a new issue