Allow source counts to be cached: implement ::doCount() instead of ::count()

Ah, right, this requires #3190815: Source count caching broken: impossible to enable source count caching for SqlBase-based source plugins (plus, unneeded cache I/O) 😬

+++ b/src/Plugin/migrate/source/d7/FileEntityConfigSourceBase.php
@@ -164,7 +164,7 @@ abstract class FileEntityConfigSourceBase extends ConfigSourceBase {
-  public function count($refresh = FALSE) {
+  public function doCount() {

Nit: should be protected.

#3190815: Source count caching broken: impossible to enable source count caching for SqlBase-based source plugins (plus, unneeded cache I/O) landed! 🥳

1. +++ b/src/Plugin/migrate/source/d7/ConfigSourceBase.php
   @@ -13,4 +14,26 @@ abstract class ConfigSourceBase extends DrupalSqlBase {
   +   * @todo Remove after Drupal core 8.x and 9.0.x are out of support.
   

   Übernit: s/out of support/unsupported/ 🤓

2. +++ b/src/Plugin/migrate/source/d7/ConfigSourceBase.php
   @@ -13,4 +14,26 @@ abstract class ConfigSourceBase extends DrupalSqlBase {
   +    if (MigrationPluginTool::sourcePluginCountIsCacheable()) {
   +      return parent::count($refresh);
   +    }
   +
   +    return $this->initializeIterator()->count();
   

   This does: "When cacheable, do not call our override, but instead call the parent implementation, which is what will call ::doCount() on 9.1 & 9.2, but not 8.9 & 9.0." 👍

3. +++ b/src/Utility/MigrationPluginTool.php
   @@ -11,6 +11,56 @@ use Drupal\Core\Plugin\PluginBase;
   +  /**
   +   * Determines whether SqlBase source plugins might have cacheable counts.
   +   *
   +   * @todo Remove after Drupal core 8.x and 9.0.x are out of support.
   +   *
   +   * @see https://drupal.org/i/3215106
   +   *
   +   * @return bool
   +   *   TRUE if migration source plugins extending SqlBase might have cacheable
   +   *   counts, FALSE otherwise.
   +   */
   +  public static function sourcePluginCountIsCacheable() :bool {
   

   🤓 Nit: I think the name is a bit misleading here.

   I think
   public static function cacheableSourceCountSupportedByCore() would be clearer.

4. +++ b/src/Utility/MigrationPluginTool.php
   @@ -11,6 +11,56 @@ use Drupal\Core\Plugin\PluginBase;
   +    // Drupal core 9.1 is the oldest minor which got the fix - but every release
   +    // prior to 9.1.9 does not have cacheable source plugin counts.
   +    if (
   +      version_compare($version_normalized, '9.1.9', 'ge') &&
   +      version_compare($version_normalized, '9.2', 'lt')
   +    ) {
   +      return TRUE;
   +    }
   +
   +    // Core 9.2 versions: alpha1 was released without the fix.
   +    if (version_compare($version_normalized, '9.2.0-alpha2', 'ge')) {
   +      return TRUE;
   +    }
   

   👏 This is next-level BC — even includes consideration for alpha releases!

5. +++ b/tests/src/Kernel/Plugin/migrate/source/d7/MediaMigrationSourceTestBase.php
   @@ -61,11 +62,41 @@ abstract class MediaMigrationSourceTestBase extends MigrateSqlSourceTestBase {
   +    if (MigrationPluginTool::sourcePluginCountIsCacheable()) {
   +      /** @var \Drupal\Core\Cache\MemoryCounterBackend $cache **/
   +      $cache = \Drupal::cache('migrate');
   +      if ($expected_cache_key) {
   +        // Verify the the computed cache key.
   +        $reflector = new \ReflectionObject($plugin);
   +        $property = $reflector->getProperty('database');
   +        $property->setAccessible(TRUE);
   +        $this->assertSame($expected_cache_key, $property->getValue($plugin));
   +
   +        // Cache miss prior to calling ::count().
   +        $this->assertFalse($cache->get($expected_cache_key, 'cache'));
   +
   +        $this->assertSame([], $cache->getCounter('set'));
   +        $count = $plugin->count();
   +        $this->assertSame($expected_count, $count);
   +        $this->assertSame([$expected_cache_key => 1], $cache->getCounter('set'));
   +
   +        // Cache hit afterwards.
   +        $cache_item = $cache->get($expected_cache_key, 'cache');
   +        $this->assertNotSame(FALSE, $cache_item, 'This is not a cache hit.');
   +        $this->assertSame($expected_count, $cache_item->data);
   +      }
   

   This is copied from the core test coverage that I worked on.

   👍 I think this is to be 100% certain that source count caching works as expected — and that's fine of course!