Reset API / ResettableInterface (brainstorming)

Coming from #2260187: [PP-1] Deprecate drupal_static() and drupal_static_reset()

Note: The term "cache" is ambiguous. It can mean caching in storage between requests (database, memcache, etc), or caching in a variable in the current request / PHP process. I personally prefer the term "buffer" for caching in a variable. So "cache" only refers to storage. This is the term I will use below.

Problem

The scenario:
- We want data that could be obtained through a discovery process, but this is too slow to do it more than once.
- Data should be buffered in a variable.
- This may be in places where we don't have a container available, only static and global stuff.
- We need a way to reset some or all of this buffered data.

Current solution:
Cache data with drupal_static().

Problem: This sucks for testing.

Proposed solution

This is not actually a complete solution, but rather a way to organize things.

Goal: Make the services themselves independent from the static / global state stuff.

Solution, part I

1. Introduce an interface ResettableInterface, somewhere in Drupal\Component\.

namespace Drupal\Component\..;

interface ResettableInterface {

  /**
   * Resets buffered data.
   */
  public function reset();
}

2. Implement whichever discovery process we are interested in as a "data provider", with or without parameters.

interface FooProviderInterface {
  public function getFoo($x, $y);
}

/**
 * Actually scans the filesystem, or whatever else is needed.
 */
class FooProvider_Discovery implements FooProviderInterface {
  ..
}

3. Implement a buffer decorator, which also implements ResettableInterface.

class FooProvider_Buffer implements FooProviderInterface, ResettableInterface {

  private $decorated;
  private $buffer = [];

  public function __construct(FooProviderInterface $decorated) {
    $this->decorated = $decorated;
  }

  public function reset() {
    $this->buffer = [];
  }

  public function getFoo($x, $y) {
    return isset($this->buffer[$x][$y])
      ? $this->buffer[$x][$y]
      : $this->buffer[$x][$y] = $this->decorated->getFoo();
  }
}

Solution, part II

Create tools that allow us to subscribe resettables.

interface ResettableSubscriberInterface {
  /**
   * Subscribes a resettable for reset events.
   *
   * @param ResettableInterface $resettable
   */
  public function subscribeResettable(ResettableInterface $resettable);
}

(Optionally, the subscribeResettable() could take a machine name as a second parameter.)

This thing can be passed around to object factories, e.g. like this:

class FooProviderUtil {
public static function createFooProviderWithBuffer(ResettableSubscriberInterface $resettableSubscriber) {
$provider = new FooProvider_Discovery();
$provider = new FooProvider_Buffer($provider);
$resettableSubscriber->subscribeResettable($provider);
return $provider;
}
}

Somewhere we have a component that can actually reset all or some of the subscribed resettables.
This can be live in the container, or in a static variable.

The main point is:
The actual data provider classes (FooProvider, and the buffer decorator) don't need to know about it.
And in tests, we can instantiate these data providers without any static stuff.

FooProvider "singleton".

Singletons are bad for many reasons.
Here we are simply being honest. This is for cases where we need static access, e.g. when no container is available. So let us not create something which looks like a regular object from outside, but uses ugly static variables on the inside.

Instead we use a singleton, which is technically equivalent to what we were already doing, but more honest.
And we are using the least bad version of singleton possible:
- The class does NOT manage its own instance.
- The instance constructor is not made private, so we can create as many instances as we want for testing.

This said: I am totally not sure about this part.
There are probably other options. It depends on the details of "we don't have a container yet".

And here it is:

class FooProviderSingleton {
  private static $instance;
  public static function getInstance() {
    return self::$instance !== NULL
      ? self::$instance
      : self::$instance = self::createInstance();
  }
  private static function createInstance() {
    $subscriber = ResettableSubscriberSingleton::getInstance();
    return FooProviderUtil::createFooProviderWithBuffer($subscriber);
  }
  /**
   * Optional static reset method.
   */
  public static function reset() {
    if (self::$instance !== NULL && self::$instance instanceof ResettableInterface) {
      self::$instance->reset();
    }
  }
  }
}

I don't care too much about the details of this singleton stuff.

The main point is:
- The code is still functionally equivalent with a function using drupal_static(). So, getting here won't break anything.
- The actual data provider implementation can be SOLID and nicely testable, and does not know about static instances of anything.
- This code can be refactored to something completely container-driven, without touching the data provider implementation. This is likely a BC break of some sort.