MDL-79446 reportbuilder: optional $suffix for generated alias/params.

Allows for, and documents, intended usage when the result of these
methods is used elsewhere (e.g. in `$DB->get_in_or_equal`).

reportbuilder/classes/local/helpers/database.php

@@ -39,47 +39,49 @@ class database {
     /**
      * Generates unique table/column alias that must be used in generated SQL
      *
+     * @param string $suffix Optional string to append to alias
      * @return string
      */
-    public static function generate_alias(): string {
+    public static function generate_alias(string $suffix = ''): string {
         static $aliascount = 0;
 
-        return static::GENERATE_ALIAS_PREFIX . ($aliascount++);
+        return static::GENERATE_ALIAS_PREFIX . ($aliascount++) . $suffix;
     }
 
     /**
      * Generate multiple unique table/column aliases, see {@see generate_alias} for info
      *
      * @param int $count
+     * @param string $suffix
      * @return string[]
      */
-    public static function generate_aliases(int $count): array {
-        return array_map([
-            static::class, 'generate_alias'
-        ], array_fill(0, $count, null));
+    public static function generate_aliases(int $count, string $suffix = ''): array {
+        return array_map([static::class, 'generate_alias'], array_fill(0, $count, $suffix));
     }
 
     /**
      * Generates unique parameter name that must be used in generated SQL
      *
+     * When passing the returned value to {@see \moodle_database::get_in_or_equal} it's recommended to define the suffix
+     *
+     * @param string $suffix Optional string to append to parameter name
      * @return string
      */
-    public static function generate_param_name(): string {
+    public static function generate_param_name(string $suffix = ''): string {
         static $paramcount = 0;
 
-        return static::GENERATE_PARAM_PREFIX . ($paramcount++);
+        return static::GENERATE_PARAM_PREFIX . ($paramcount++) . $suffix;
     }
 
     /**
      * Generate multiple unique parameter names, see {@see generate_param_name} for info
      *
      * @param int $count
+     * @param string $suffix
      * @return string[]
      */
-    public static function generate_param_names(int $count): array {
-        return array_map([
-            static::class, 'generate_param_name'
-        ], array_fill(0, $count, null));
+    public static function generate_param_names(int $count, string $suffix = ''): array {
+        return array_map([static::class, 'generate_param_name'], array_fill(0, $count, $suffix));
     }
 
     /**

reportbuilder/tests/local/helpers/database_test.php

@@ -37,6 +37,9 @@ class database_test extends advanced_testcase {
      */
     public function test_generate_alias(): void {
         $this->assertMatchesRegularExpression('/^rbalias(\d+)$/', database::generate_alias());
+
+        // Specify a suffix.
+        $this->assertMatchesRegularExpression('/^rbalias(\d+)_$/', database::generate_alias('_'));
     }
 
     /**
@@ -48,10 +51,20 @@ class database_test extends advanced_testcase {
         $this->assertCount(3, $aliases);
         [$aliasone, $aliastwo, $aliasthree] = $aliases;
 
+        $this->assertMatchesRegularExpression('/^rbalias(\d+)$/', $aliasone);
+        $this->assertMatchesRegularExpression('/^rbalias(\d+)$/', $aliastwo);
+        $this->assertMatchesRegularExpression('/^rbalias(\d+)$/', $aliasthree);
+
         // Ensure they are different.
         $this->assertNotEquals($aliasone, $aliastwo);
         $this->assertNotEquals($aliasone, $aliasthree);
         $this->assertNotEquals($aliastwo, $aliasthree);
+
+        // Specify a suffix.
+        [$aliasfour, $aliasfive] = database::generate_aliases(2, '_');
+        $this->assertNotEquals($aliasfour, $aliasfive);
+        $this->assertMatchesRegularExpression('/^rbalias(\d+)_$/', $aliasfour);
+        $this->assertMatchesRegularExpression('/^rbalias(\d+)_$/', $aliasfive);
     }
 
     /**
@@ -59,6 +72,9 @@ class database_test extends advanced_testcase {
      */
     public function test_generate_param_name(): void {
         $this->assertMatchesRegularExpression('/^rbparam(\d+)$/', database::generate_param_name());
+
+        // Specify a suffix.
+        $this->assertMatchesRegularExpression('/^rbparam(\d+)_$/', database::generate_param_name('_'));
     }
 
     /**
@@ -70,10 +86,20 @@ class database_test extends advanced_testcase {
         $this->assertCount(3, $params);
         [$paramone, $paramtwo, $paramthree] = $params;
 
+        $this->assertMatchesRegularExpression('/^rbparam(\d+)$/', $paramone);
+        $this->assertMatchesRegularExpression('/^rbparam(\d+)$/', $paramtwo);
+        $this->assertMatchesRegularExpression('/^rbparam(\d+)$/', $paramthree);
+
         // Ensure they are different.
         $this->assertNotEquals($paramone, $paramtwo);
         $this->assertNotEquals($paramone, $paramthree);
         $this->assertNotEquals($paramtwo, $paramthree);
+
+        // Specify a suffix.
+        [$paramfour, $paramfive] = database::generate_param_names(2, '_');
+        $this->assertNotEquals($paramfour, $paramfive);
+        $this->assertMatchesRegularExpression('/^rbparam(\d+)_$/', $paramfour);
+        $this->assertMatchesRegularExpression('/^rbparam(\d+)_$/', $paramfive);
     }
 
     /**

reportbuilder/upgrade.txt

@@ -1,6 +1,11 @@
 This file describes API changes in /reportbuilder/*
 Information provided here is intended especially for developers.
 
+=== 4.4 ===
+
+* The database helper `generate_alias[es]` and `generate_param_name[s]` methods now accept an optional `$suffix` argument for
+  appending additional string to the generated value
+
 === 4.3 ===
 
 * New external methods for retrieving system report data: