(dev/core#174) CRM_Utils_Cache_Interface::set() should match PSR-16
authorTim Otten <totten@civicrm.org>
Tue, 19 Jun 2018 22:19:01 +0000 (15:19 -0700)
committerTim Otten <totten@civicrm.org>
Wed, 27 Jun 2018 21:29:52 +0000 (14:29 -0700)
commit858451a9cd8763ce8d12ca5b77c98cc028484c7a
treec4ac4d08803267c3069637097a2e7c0c10e65a49
parent2da67cc5bf2670122892aade13a6546263bf6e7d
(dev/core#174) CRM_Utils_Cache_Interface::set() should match PSR-16

Comparing `CRM_Utils_Cache_Interface::set()` and `Psr\SimpleCache\CacheInterface::set()`,
they agree on key details:

1. The first value is a string key.
2. The second value is a mixed field (string or number or array...).
3. The return value should be a boolean indicating success/failure.

There are two differences:

1. Our old interface didn't actually enforce the return-value in all cases. Should be better now.
2. PSR-16 accepts a third argument, `$ttl`, which defaults to `NULL`. In the NULL/default case,
   the semantics are the same (i.e. up to the discretion of the driver).
    1. Since no existing callers actually use this, we can (for moment) throw an
       error if someone tries to pass `$ttl` to a driver that doesn't support it.
3. The `$value` is pass-by-reference. However, this probably doesn't mean anything.
    1. In older Civi code, there was a tendenacy to pass-by-reference without any real
       need -- perhaps just speculation about performance.
    2. Most cache drivers serialize the value and send it elsewhere. References will
       not survive the process. If there's some code/caller/use-case that requires the
       references to work, then it's already broken for most drivers (except maybe `ArrayCache`).
    3. The old signature meant that callers had to say `$bar=123; $cache->set('foo', $bar)` rather than
       `$cache->set('foo', 123)`. This change relaxes the contract -- so that you can pass
       either `$bar` or `123.

See also: https://www.php-fig.org/psr/psr-16/
CRM/Utils/Cache/APCcache.php
CRM/Utils/Cache/ArrayCache.php
CRM/Utils/Cache/Interface.php
CRM/Utils/Cache/Memcache.php
CRM/Utils/Cache/Memcached.php
CRM/Utils/Cache/NoCache.php
CRM/Utils/Cache/Redis.php
CRM/Utils/Cache/SerializeCache.php
CRM/Utils/Cache/SqlGroup.php