cache/upgrade.txt

   1 This files describes API changes in /cache/stores/* - cache store plugins.
   2 Information provided here is intended especially for developers.
   3
   4 === 4.3 ===
   5 * A new cache_helper::result_found() helper has been added to assist with cache value validation
   6 * Implementations of the following methods, deprecated since 3.10, have been removed and can no longer be used:
   7   - `\core\lock\lock::extend`
   8   - `\core\lock\lock_factory::extend_lock`
   9   - `\core\lock\lock_factory::supports_recursion`
  10 * The automatic locking options 'requirelockingread' and 'requirelockingwrite' have been removed.
  11   These features are not used in core, were recommended against in the documentation, had significant
  12   bugs, and had no useful purpose. 'requirelockingbeforewrite' is still available to check that manual
  13   locking has been applied.
  14 * The acquire_lock function within cache loaders now throws an exception if it fails to obtain the
  15   lock after a timeout, instead of returning false.
  16 * The functions set_many, delete, and delete_many now all throw exceptions if you are using
  17   'requirelockingbeforewrite' and do not have a lock, same as the set function.
  18
  19 === 4.2 ===
  20 * The memcached cachestore has been removed.
  21 * The mongodb cachestore has been removed.
  22
  23 === 4.1 ===
  24 * Added new `requirelockingbeforewrite` option for cache definitions. This will check that a lock for a given cache key already
  25   exists before it will perform a `set()` on that key. A `coding_exception` is thrown if the lock has not been acquired.
  26 * Added native locking to cachestore_file. This will use an instance of file_lock_factory pointing at a subdirectory in the same
  27   location as the cache instance, meaning a local file cache will have its locks stored locally. If file locks are disabled
  28   globally, it will fall back to use the default lock factory, which may not be in the same location as the cache. cachestore_file
  29   includes an additional setting to control how long it will wait for a lock before giving up, default is 60 seconds.
  30
  31 === 4.0 ===
  32 * Cache stores may implement new optional function cache_store::get_last_io_bytes() to provide
  33   information about the size of data transferred (shown in footer if performance info enabled).
  34 * The cache_store class now has functions cache_size_details(), store_total_size(), and
  35   estimate_stored_size(), related to size used by the cache. These can be overridden by a cache
  36   store to provide better information for the new cache usage admin page.
  37 * New functions cache::set_versioned() and cache::get_versioned() can be used to ensure correct
  38   behaviour when using a multi-level cache with early cache levels stored locally. (Used when
  39   rebuilding modinfo.) There is also a new interface cache_data_source_versionable which can
  40   be implemented if you want to make a data source that supports versioning.
  41
  42 === 3.10 ===
  43 * The function supports_recursion() from the lock_factory interface has been deprecated including the related implementations.
  44 * The function extend_lock() from the lock_factory interface has been deprecated without replacement including the related
  45   implementations.
  46 * The function extend() from the lock class has been deprecated without replacement.
  47 * The cache_factory class can now be overridden by an alternative cache config class, which can
  48   also now control the frontend display of the cache/admin.php page (see MDL-41492).
  49
  50 === 3.9 ===
  51 * The record_cache_hit/miss/set methods now take a cache_store instead of a cache_definition object
  52
  53 === 3.8 ===
  54 * The Redis cache store can now make use of the Zstandard compression algorithm (see MDL-66428).
  55
  56 === 3.7 ===
  57 * Upgraded MongoDB cache store to use the new lower level PHP-driver and MongoDB PHP Library.
  58 * The mongodb extension has replaced the old mongo extension. The mongodb pecl extension >= 1.5 must be installed to use MongoDB
  59 cache store.
  60
  61 === 3.6 ===
  62 * The `cache::now()` function now takes an optional boolean parameter to indicate that the cache should return a more
  63   accurate time, generated by the PHP `microtime` function.
  64 * The memcache store was removed as it is not compatible with PHP 7.0.
  65
  66 === 3.3 ===
  67 * Identifiers and invalidation events have been explictly been marked as incompatible and will
  68   throw a coding exception. Unexpected results would have occurred if the previous behaviour was attempted.
  69 * Identifiers are now part of loaded caches, so identifiers can only be set at cache::make()
  70   a coding_exception will be thrown if attempts are made at other times.
  71   Multiple calls to cache::make with different identifiers will produce 2 caches instead of changing the
  72   keyspace of a single cache.
  73
  74 === 3.2 ===
  75 * The following methods have been finally deprecated and should no longer be used.
  76   - cache_definition::should_be_persistent()
  77   - cache_definition::get_persistent_max_size()
  78   - cache::is_using_persist_cache()
  79   - cache::is_in_persist_cache()
  80   - cache::get_from_persist_cache()
  81   - cache::set_in_persist_cache()
  82   - cache::delete_from_persist_cache()
  83   - cache_store::cleanup()
  84 * cachestore_dummy::cleanup() has been deprecated.
  85 * cachestore_dummy::instance_deleted() implemented in lieu of cachestore_dummy::cleanup().
  86 * Added cache_store::unit_test_configuration() to calculate unit testing configuration.
  87 * Remove cache_store:initialise_unit_test_instance() as it is incompatible with cache_helper purge functions.
  88
  89 === 3.1 ===
  90 * Cache stores has a new feature DEREFERENCES_OBJECTS.
  91   This allows the cache loader to decide if it needs to handle dereferencing or whether the data
  92   coming directly to it has already had references resolved.
  93   - see supports_dereferencing_objects in store.php.
  94
  95 === 2.9 ===
  96 * Cache data source aggregation functionality has been removed. This functionality was found to be broken and unused.
  97   It was decided that rather than fixing it it should be removed.
  98   As well as the processing code being removed the following API changes have been made.
  99   The following changes have come about because of it:
 100    - cache_definition::$datasourceaggregate is deprecated an unused.
 101    - cache_definition::load Argument 3 (final arg) is now unused.
 102    - cache_factory::create_cache_from_definition Argument 4 (final arg) is now unused.
 103    - cache::make Argument 4 (final arg) is now unused.
 104 * cache_config_phpunittest has been renamed to cache_config_testing
 105 * New method cache_store::ready_to_be_used_for_testing() that returns true|false if the store is suitable and ready for use as the primary store during unit and acceptance tests.
 106 * cache_helper::get_stats structure we changed to include the cache mode.
 107
 108 === 2.7 ===
 109 * cache_store::is_ready is no longer abstract, calling cache_store::are_requirements_met by default.
 110
 111 === 2.6 ===
 112 * All cache instances are recorded and subsequent requests are given a reference to the original instance.
 113 * The persistent option for the cache definition has been deprecated. Please use the staticacceleration option instead.
 114 * There is a new static acceleration option. If enabled data passing through the cache is held onto.
 115 * The persistentmaxsize option has been renamed to staticaccelerationsize. It does the same thing.
 116 * cache_definition::should_be_persistent has been deprecated. Please call cache_definition::use_static_acceleration instead.
 117 * cache_definition::get_persistent_max_size has been deprecated. Please call cache_definition::get_static_acceleration_size instead.
 118 * cache::is_using_persist_cache() has been deprecated. Please call  cache::use_static_acceleration()
 119 * cache::is_in_persist_cache() has been deprecated. Please call  cache::static_acceleration_has()
 120 * cache::get_from_persist_cache() has been deprecated. Please call  cache::static_acceleration_get()
 121 * cache::set_in_persist_cache() has been deprecated. Please call  cache::static_acceleration_set()
 122 * cache::delete_from_persist_cache() has been deprecated. Please call cache::static_acceleration_delete()
 123 * If you have any custom cache loaders you will need to rename these methods if you have overriden them and adjust any calls you may have made to them.
 124
 125 === 2.5 ===
 126 * cleanup method renamed to instance_deleted.
 127   It is now called when the store is deleted as all comments suggested anyway.
 128 * instance_created method added.
 129   It is called when the store is created for the very first time.