Allow overriding name on issued certificates

- Useful for when a common template is used across multiple certification paths
- Overrides the certificate name when listing certificates to user
- Is used for PDF document names

Author: tmayfield-costrack

classes/certificate.php

@@ -110,7 +110,7 @@ public static function get_issues_for_template($templateid, $limitfrom, $limitnu
         $userfields = self::get_extra_user_fields($context);
 
         $sql = "SELECT ci.id as issueid, ci.code, ci.emailed, ci.timecreated, ci.userid, ci.templateid, ci.expires,
-                       t.name, ci.data, {$userfields}
+                       COALESCE(ci.name, t.name) AS name, ci.data, {$userfields}
                   FROM {tool_certificate_templates} t
                   JOIN {tool_certificate_issues} ci
                     ON (ci.templateid = t.id)
@@ -245,7 +245,7 @@ public static function get_issues_for_course(int $templateid, int $courseid, str
         $userfields = self::get_extra_user_fields($context);
 
         $sql = "SELECT ci.id as issueid, ci.code, ci.emailed, ci.timecreated, ci.userid, ci.templateid, ci.expires,
-                       t.name, ci.courseid, ci.archived, $userfields,
+                       COALESCE(ci.name, t.name) AS name, ci.courseid, ci.archived, $userfields,
                   CASE WHEN ci.expires > 0  AND ci.expires < :now THEN 0
                   ELSE 1
                   END AS status
@@ -317,7 +317,7 @@ public static function get_issues_for_user($userid, $limitfrom, $limitnum, $sort
         }
 
         $sql = "SELECT ci.id, ci.expires, ci.code, ci.timecreated, ci.userid, ci.courseid,
-                       t.id as templateid, t.contextid, t.name
+                       t.id as templateid, t.contextid, COALESCE(ci.name, t.name) AS name
                   FROM {tool_certificate_templates} t
             INNER JOIN {tool_certificate_issues} ci
                     ON t.id = ci.templateid
@@ -388,7 +388,8 @@ public static function verify($code) {
         $sql = "SELECT ci.id, ci.templateid, ci.code, ci.emailed, ci.timecreated,
                        ci.expires, ci.data, ci.component, ci.courseid,
                        ci.userid, ci.archived,
-                       t.name as certificatename,
+                       t.name AS certificatename,
+                       ci.name,
                        t.contextid
                   FROM {tool_certificate_templates} t
                   JOIN {tool_certificate_issues} ci

classes/reportbuilder/local/entities/issue.php

@@ -118,6 +118,17 @@ protected function get_all_columns(): array {
             ->add_field("{$certificateissuealias}.code")
             ->add_callback([formatter::class, 'code_with_link']);
 
+        // Column certificate issue timecreated.
+        $columns[] = (new column(
+            'name',
+            new lang_string('issuename', 'tool_certificate'),
+            $this->get_entity_name()
+        ))
+            ->add_joins($this->get_joins())
+            ->set_type(column::TYPE_TEXT)
+            ->set_is_sortable(true)
+            ->add_field("{$certificateissuealias}.name");
+
         // Column certificate issue timecreated.
         $columns[] = (new column(
             'timecreated',

classes/template.php

@@ -264,13 +264,13 @@ public function generate_pdf($preview = false, $issue = null, $return = false) {
 
             $pdf->setPrintHeader(false);
             $pdf->setPrintFooter(false);
-            $pdf->SetTitle($this->get_formatted_name());
+            $pdf->SetTitle($this->get_formatted_name($issue));
             $pdf->setViewerPreferences([
                 'DisplayDocTitle' => true,
             ]);
             $pdf->SetAutoPageBreak(true, 0);
             // Remove full-stop at the end, if it exists, to avoid "..pdf" being created and being filtered by clean_filename.
-            $filename = rtrim($this->get_formatted_name(), '.');
+            $filename = rtrim($this->get_formatted_name($issue), '.');
             $filename = clean_filename($filename . '.pdf');
             // Loop through the pages and display their content.
             foreach ($pages as $page) {
@@ -446,9 +446,13 @@ public function get_shared() {
     /**
      * Returns the formatted name of the template.
      *
+     * @param \stdClass $issue The issued certificate we want to view
      * @return string the name of the template
      */
-    public function get_formatted_name() {
+    public function get_formatted_name(\stdClass $issue = null) {
+        if ($issue && $issue->name) {
+            return format_string($issue->name, true, ['escape' => false, 'context' => $this->get_context()]);
+        }
         return $this->persistent->get_formatted_name();
     }
 
@@ -688,11 +692,12 @@ public static function find_by_name($name) {
      * @param array $data Additional data that will json_encode'd and stored with the issue.
      * @param string $component The component the certificate was issued by.
      * @param int|null $courseid
+     * @param string $name Override the name for a certificate to display in the user's list
      * @param \core\lock\lock|null $lock optional lock to release after a record was inserted into the DB
      * @return int The ID of the issue
      */
     public function issue_certificate($userid, $expires = null, array $data = [], $component = 'tool_certificate',
-            $courseid = null, ?\core\lock\lock $lock = null) {
+            $courseid = null, $name = null, ?\core\lock\lock $lock = null) {
         global $DB;
 
         component_class_callback(\tool_tenant\config::class, 'push_for_user', [$userid]);
@@ -707,6 +712,7 @@ public function issue_certificate($userid, $expires = null, array $data = [], $c
         $issue->component = $component;
         $issue->courseid = $courseid;
         $issue->archived = 0;
+        $issue->name = $name;
 
         // Store user fullname.
         $data['userfullname'] = fullname($DB->get_record('user', ['id' => $userid]));

db/install.xml

@@ -23,6 +23,7 @@
         <FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="true"/>
         <FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" DEFAULT="0" SEQUENCE="false"/>
         <FIELD NAME="templateid" TYPE="int" LENGTH="10" NOTNULL="true" DEFAULT="0" SEQUENCE="false"/>
+        <FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="false" SEQUENCE="false"/>
         <FIELD NAME="code" TYPE="char" LENGTH="40" NOTNULL="false" SEQUENCE="false"/>
         <FIELD NAME="emailed" TYPE="int" LENGTH="1" NOTNULL="true" DEFAULT="0" SEQUENCE="false"/>
         <FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" DEFAULT="0" SEQUENCE="false"/>

db/upgrade.php

@@ -247,5 +247,18 @@ function xmldb_tool_certificate_upgrade($oldversion) {
         upgrade_plugin_savepoint(true, 2023071300, 'tool', 'certificate');
     }
 
+    if ($oldversion < 2024061000) {
+        $table = new xmldb_table('tool_certificate_issues');
+        $field = new xmldb_field('name', XMLDB_TYPE_CHAR, '255');
+
+        // Conditionally add field name to tool_certificate_issues
+        if (!$dbman->field_exists($table, $field)) {
+            $dbman->add_field($table, $field);
+        }
+
+        // Certificate savepoint reached.
+        upgrade_plugin_savepoint(true, 2024061000, 'tool', 'certificate');
+    }
+
     return true;
 }

lang/en/tool_certificate.php

@@ -121,6 +121,7 @@
 $string['issueddate'] = 'Date issued';
 $string['issuelang'] = 'Issue certificates in user language';
 $string['issuelangdesc'] = 'On multi-lingual sites when user language is different from the site language the certificates will be generated in the user\'s language, otherwise all certificates will be generated in the site default language.';
+$string['issuename'] = 'Name (issued)';
 $string['issuenotallowed'] = 'You are not allowed to issue certificates from this template.';
 $string['issueormangenotallowed'] = 'You are not allowed to issue certificates from or manage this template.';
 $string['leftmargin'] = 'Left margin';

tests/certificate_test.php

@@ -356,6 +356,23 @@ public function test_verify(): void {
         $this->assertEquals($result->issue->id, $issueid1);
     }
 
+    /**
+     * Verify a certificate issued with a custom name uses that custom name
+     */
+    public function test_can_set_certificate_name(): void {
+        $testname = 'Test Certificate 1';
+
+        $this->setAdminUser();
+        $certificate1 = $this->get_generator()->create_template((object)['name' => 'Certificate 1']);
+        $user1 = $this->getDataGenerator()->create_user();
+        $certificate1->issue_certificate($user1->id, null, [], 'tool_certificate', null, $testname);
+
+        $issues = certificate::get_issues_for_template($certificate1->get_id(), 0, 100);
+        $this->assertCount(1, $issues);
+        $issue = reset($issues);
+        $this->assertEquals($testname, $issue->name);
+    }
+
     /**
      * Test generate code.
      */

version.php

@@ -26,7 +26,7 @@
 
 $plugin->component    = 'tool_certificate';
 $plugin->release      = '4.4';
-$plugin->version      = 2024052100;
+$plugin->version      = 2024061000;
 $plugin->requires     = 2022041900.00;
 $plugin->maturity     = MATURITY_STABLE;
 $plugin->supported    = [400, 404];