Added customisable filename options for certificates (#684)

Author: Raza403

classes/template.php

@@ -314,24 +314,83 @@ public function generate_pdf(bool $preview = false, ?int $userid = null, bool $r
                 $deliveryoption = $customcert->deliveryoption;
             }
 
-            // Remove full-stop at the end, if it exists, to avoid "..pdf" being created and being filtered by clean_filename.
-            $filename = rtrim(format_string($this->name, true, ['context' => $this->get_context()]), '.');
-
+            // Set up PDF document properties — no header/footer, auto page break.
             $pdf->setPrintHeader(false);
             $pdf->setPrintFooter(false);
-            $pdf->SetTitle($filename);
             $pdf->SetAutoPageBreak(true, 0);
 
+            // Get filename pattern from global settings.
+            if (!empty($customcert->usecustomfilename) && !empty($customcert->customfilenamepattern)) {
+                $filenamepattern = $customcert->customfilenamepattern;
+            } else {
+                $filenamepattern = '{DEFAULT}';
+            }
+
+            if (empty($filenamepattern) || $filenamepattern === '{DEFAULT}') {
+                // Use the custom cert name as the base filename (strip any trailing dot).
+                $filename = rtrim(format_string($this->name, true, ['context' => $this->get_context()]), '.');
+            } else {
+                // Build filename from pattern substitutions.
+
+                // Get issue record for date (if issued); fallback to current date if not found.
+                $issue = $DB->get_record('customcert_issues', [
+                    'userid' => $user->id,
+                    'customcertid' => $customcert->id,
+                ], '*', IGNORE_MISSING);
+
+                if ($issue && !empty($issue->timecreated)) {
+                    $issuedate = date('Y-m-d', $issue->timecreated);
+                } else {
+                    $issuedate = date('Y-m-d');
+                }
+
+                $course = $DB->get_record('course', ['id' => $customcert->course], '*', IGNORE_MISSING);
+
+                $values = [
+                    '{FIRST NAME}' => $user->firstname ?? '',
+                    '{LAST NAME}' => $user->lastname ?? '',
+                    '{COURSE SHORT NAME}' => $course ? $course->shortname : '',
+                    '{COURSE FULL NAME}' => $course ? $course->fullname : '',
+                    '{DATE}' => $issuedate,
+                ];
+
+                // Handle group if needed.
+                $groups = groups_get_all_groups($course->id, $user->id);
+                if (!empty($groups)) {
+                    $groupnames = array_map(function($g) {
+                        return $g->name;
+                    }, $groups);
+                    $values['{GROUP}'] = implode(', ', $groupnames);
+                } else {
+                    $values['{GROUP}'] = '';
+                }
+
+                // Replace placeholders with actual values.
+                $filename = strtr($filenamepattern, $values);
+
+                // Remove trailing dot to avoid "..pdf" issues.
+                $filename = rtrim($filename, '.');
+            }
+
             // This is the logic the TCPDF library uses when processing the name. This makes names
             // such as 'الشهادة' become empty, so set a default name in these cases.
             $filename = preg_replace('/[\s]+/', '_', $filename);
             $filename = preg_replace('/[^a-zA-Z0-9_\.-]/', '', $filename);
 
+            // If filename ends up empty (e.g. after removing unsupported characters), use default string.
             if (empty($filename)) {
                 $filename = get_string('certificate', 'customcert');
             }
 
+            // Remove existing ".pdf" extension if present to avoid duplication.
+            $filename = preg_replace('/\.pdf$/i', '', $filename);
+
+            // Clean the final filename and append ".pdf".
             $filename = clean_filename($filename . '.pdf');
+
+            // Set the PDF document title (for metadata, not the filename itself).
+            $pdf->SetTitle($filename);
+
             // Loop through the pages and display their content.
             foreach ($pages as $page) {
                 // Add the page to the PDF.

db/upgrade.php

@@ -316,5 +316,23 @@ function xmldb_customcert_upgrade($oldversion) {
         upgrade_plugin_savepoint(true, 2024042210, 'mod', 'customcert');
     }
 
+    if ($oldversion < 2025062100) {
+        $table = new xmldb_table('customcert');
+
+        // Add 'usecustomfilename' field.
+        $field = new xmldb_field('usecustomfilename', XMLDB_TYPE_INTEGER, '1', null, XMLDB_NOTNULL, null, '0', 'deliveryoption');
+        if (!$dbman->field_exists($table, $field)) {
+            $dbman->add_field($table, $field);
+        }
+
+        // Add 'customfilenamepattern' field.
+        $field = new xmldb_field('customfilenamepattern', XMLDB_TYPE_TEXT, null, null, null, null, null, 'usecustomfilename');
+        if (!$dbman->field_exists($table, $field)) {
+            $dbman->add_field($table, $field);
+        }
+
+        // Savepoint reached.
+        upgrade_mod_savepoint(true, 2025062100, 'customcert');
+    }
     return true;
 }

lang/en/customcert.php

@@ -22,6 +22,7 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+$string['Upper/lower/digits'] = '6aOdbLEuoC (Upper/lower/digits random string)';
 $string['activity'] = 'Activity';
 $string['addcertpage'] = 'Add page';
 $string['addelement'] = 'Add element';
@@ -63,6 +64,10 @@
 $string['customcert:viewallcertificates'] = 'View all certificates';
 $string['customcert:viewreport'] = 'View course report';
 $string['customcertsettings'] = 'Custom certificate settings';
+$string['customfilenamepattern'] = 'Custom file name pattern';
+$string['customfilenamepattern_help'] = 'Enter the pattern for naming certificate files. You can use placeholders such as {firstname}, {lastname}, {group}, {coursename}, {date}.';
+$string['custompattern'] = 'First name, Last name, Course short name, Issue date';
+$string['defaultpattern'] = 'Default (certificate name)';
 $string['deletecertpage'] = 'Delete page';
 $string['deleteconfirm'] = 'Delete confirmation';
 $string['deleteelement'] = 'Delete element';
@@ -71,10 +76,14 @@
 $string['deleteissuedcertificates'] = 'Delete issued certificates';
 $string['deletepageconfirm'] = 'Are you sure you want to delete this certificate page?';
 $string['deletetemplateconfirm'] = 'Are you sure you want to delete this certificate template?';
+$string['deliveryoption'] = 'Delivery option';
+$string['deliveryoption_help'] = 'Choose how the certificate should be delivered to users.';
 $string['deliveryoptiondownload'] = 'Send to the browser and force a file download';
 $string['deliveryoptioninline'] = 'Send the file inline to the browser';
 $string['deliveryoptions'] = 'Delivery options';
 $string['description'] = 'Description';
+$string['digits-with-hyphens'] = '0123-4567-8901 (Digits with hyphens)';
+$string['download'] = 'Force download';
 $string['downloadallissuedcertificates'] = 'Download all issued certificates';
 $string['downloadallsitecertificates'] = 'Download all site certificates';
 $string['downloadallsitecertificatesdesc'] = 'This will download all the certificates on the site in a zip file.';
@@ -123,6 +132,8 @@
 $string['eventtemplatedeleted'] = 'Custom certificate template deleted';
 $string['eventtemplateupdated'] = 'Custom certificate template updated';
 $string['exampledatawarning'] = 'Some of these values may just be an example to ensure positioning of the elements is possible.';
+$string['filenamepattern'] = 'File name pattern (legacy)';
+$string['filenamepattern_help'] = 'Choose the pattern for naming certificate files (legacy setting).';
 $string['font'] = 'Font';
 $string['font_help'] = 'The font used when generating this element.';
 $string['fontcolour'] = 'Colour';
@@ -135,6 +146,7 @@
 $string['height_help'] = 'This is the height of the certificate PDF in mm. For reference an A4 piece of paper is 297mm high and a letter is 279mm high.';
 $string['includeinnotvisiblecourses'] = 'Include certificates in hidden courses';
 $string['includeinnotvisiblecourses_desc'] = 'Certificates from hidden courses are not proccesed by default. If you want to include them, enable this setting.';
+$string['inline'] = 'Display inline';
 $string['invalidcode'] = 'Invalid code supplied.';
 $string['invalidcolour'] = 'Invalid colour chosen, please enter a valid HTML colour name, or a six-digit, or three-digit hexadecimal colour.';
 $string['invalidelementwidthorheightnotnumber'] = 'Please enter a valid number.';
@@ -235,6 +247,8 @@
 $string['useadhoc_desc'] = 'When enabled, emails related to certificates will be handled immediately through an ad-hoc task created for each issue. When disabled, emails will be managed by the regular scheduled task.
 
 Enabling this option may improve the performance of the scheduled task by offloading email processing to ad-hoc tasks.';
+$string['usecustomfilename'] = 'Use custom file name pattern';
+$string['usecustomfilename_help'] = 'If enabled, you can define a custom file name pattern for certificates using placeholders such as {FIRST NAME}, {LAST NAME}, {GROUP}, {COUSRE SHORT NAME}, {DATE}.';
 $string['userlanguage'] = 'Use user preferences';
 $string['userlanguage_help'] = 'You can force the language of the certificate to override the user\'s language preferences.';
 $string['verified'] = 'Verified';
@@ -249,4 +263,3 @@
 $string['verifycertificatedesc'] = 'This link will take you to a new screen where you will be able to verify certificates on the site';
 $string['width'] = 'Width';
 $string['width_help'] = 'This is the width of the certificate PDF in mm. For reference an A4 piece of paper is 210mm wide and a letter is 216mm wide.';
-

mod_form.php

@@ -66,6 +66,26 @@ public function definition() {
         $mform->addElement('select', 'deliveryoption', get_string('deliveryoptions', 'customcert'), $deliveryoptions);
         $mform->setDefault('deliveryoption', certificate::DELIVERY_OPTION_INLINE);
 
+        // Checkbox to enable custom file name pattern.
+        $mform->addElement('advcheckbox', 'usecustomfilename', get_string('usecustomfilename', 'customcert'));
+        $mform->addHelpButton('usecustomfilename', 'usecustomfilename', 'customcert');
+        $mform->setDefault('usecustomfilename', 0);
+
+        // Text field for custom file name pattern.
+        $mform->addElement('text', 'customfilenamepattern', get_string('customfilenamepattern', 'customcert'), ['size' => '50']);
+        $mform->setType('customfilenamepattern', PARAM_TEXT);
+        $mform->addHelpButton('customfilenamepattern', 'customfilenamepattern', 'customcert');
+        $mform->disabledIf('customfilenamepattern', 'usecustomfilename', 'notchecked');
+
+        if ($this->current) {
+            if (property_exists($this->current, 'usecustomfilename')) {
+                $mform->setDefault('usecustomfilename', $this->current->usecustomfilename);
+            }
+            if (property_exists($this->current, 'customfilenamepattern')) {
+                $mform->setDefault('customfilenamepattern', $this->current->customfilenamepattern);
+            }
+        }
+
         if (has_capability('mod/customcert:manageemailstudents', $this->get_context())) {
             $mform->addElement('selectyesno', 'emailstudents', get_string('emailstudents', 'customcert'));
             $mform->setDefault('emailstudents', get_config('customcert', 'emailstudents'));

version.php

@@ -24,7 +24,7 @@
 
 defined('MOODLE_INTERNAL') || die('Direct access to this script is forbidden.');
 
-$plugin->version   = 2024042212; // The current module version (Date: YYYYMMDDXX).
+$plugin->version   = 2025062100; // The current module version (Date: YYYYMMDDXX).
 $plugin->requires  = 2024042200; // Requires this Moodle version (4.4).
 $plugin->cron      = 0; // Period for cron to check this module (secs).
 $plugin->component = 'mod_customcert';