Fix fatal error in PDF reports when PHP iconv extension is missing (#8126)

Adds convertToLatin1() helper in ChurchInfoReport with mb_convert_encoding fallback for servers missing the iconv PHP extension. Replaces 13 direct iconv() call sites across ChurchInfoReport, PdfDirectory, PdfLabel, and NameTags.

Fixes #8124

Note: This is a short-term fix. Issue #8136 tracks the long-term migration from FPDF to mPDF, which eliminates the encoding layer entirely.

Author: Copilot

cypress/e2e/ui/reports/pdf-report-iconv-issue.spec.js

@@ -0,0 +1,61 @@
+/// <reference types="cypress" />
+
+/**
+ * Tests for GitHub Issue: Report to PDF error - iconv extension missing
+ *
+ * When the PHP `iconv` extension is not installed, PDF report generation
+ * (Church Directory, Tax Statements, Name Tags) crashed with a fatal
+ * "Call to undefined function ChurchCRM\Reports\iconv()" error.
+ *
+ * The fix adds a convertToLatin1() helper in ChurchInfoReport that falls
+ * back to mb_convert_encoding() when iconv is unavailable.
+ *
+ * These tests verify that the affected report pages load and generate
+ * output without fatal PHP errors.
+ */
+describe("PDF Reports - iconv fallback fix", () => {
+    beforeEach(() => {
+        cy.setupAdminSession();
+    });
+
+    it("Church Directory report page loads without fatal error", () => {
+        cy.visit("DirectoryReports.php");
+        cy.contains("Directory reports");
+        cy.get("body").should("not.contain", "Fatal error");
+        cy.get("body").should("not.contain", "Call to undefined function");
+    });
+
+    it("Tax Statement (Giving Report) PDF generation does not return a server error", () => {
+        cy.visit("FinancialReports.php");
+        cy.contains("Financial Reports");
+
+        cy.get("#FinancialReportTypes").select("Giving Report");
+        cy.get("#FinancialReports").submit();
+        cy.contains("Financial Reports: Giving Report");
+
+        // Set a broad date range to include demo data
+        cy.get("#DateStart").clear().type("2005-01-01");
+        cy.get("#DateEnd").clear().type("2025-12-31");
+
+        cy.get('input[name="output"][value="pdf"]').check();
+
+        // Use the same intercept pattern as tax-report-pdf.spec.js which is known to work
+        cy.intercept("POST", "**/Reports/TaxReport.php").as("taxReport");
+        cy.get("#createReport").click();
+
+        cy.wait("@taxReport").then((interception) => {
+            expect(interception.response.statusCode).to.not.equal(500);
+
+            const body = interception.response.body || "";
+            expect(body).to.not.include("Call to undefined function");
+            expect(body).to.not.include("Fatal error");
+        });
+    });
+
+    it("Name Tags / Labels page loads without fatal error", () => {
+        cy.visit("LettersAndLabels.php");
+        cy.contains("Letters and Mailing Labels");
+        cy.get("body").should("not.contain", "Fatal error");
+        cy.get("body").should("not.contain", "Call to undefined function");
+    });
+});

src/ChurchCRM/Reports/ChurchInfoReport.php

@@ -21,9 +21,25 @@ class ChurchInfoReport extends FPDF
 
     public string $paperFormat = 'Letter';
 
+    /**
+     * Converts a UTF-8 string to ISO-8859-1 for FPDF compatibility.
+     * Uses iconv() if available, falls back to mb_convert_encoding().
+     */
+    public static function convertToLatin1(string $str): string
+    {
+        if (function_exists('iconv')) {
+            $result = iconv('UTF-8', 'ISO-8859-1//TRANSLIT//IGNORE', $str);
+            if ($result !== false) {
+                return $result;
+            }
+        }
+        $result = mb_convert_encoding($str, 'ISO-8859-1', 'UTF-8');
+        return is_string($result) ? $result : $str;
+    }
+
     public function printRightJustified($x, $y, $str): void
     {
-        $strconv = iconv('UTF-8', 'ISO-8859-1', $str);
+        $strconv = self::convertToLatin1($str);
         $iLen = strlen($strconv);
         $nMoveBy = 10 - 2 * $iLen;
         $this->SetXY($x + $nMoveBy, $y);
@@ -32,28 +48,28 @@ public function printRightJustified($x, $y, $str): void
 
     public function printRightJustifiedCell($x, $y, $wid, $str): void
     {
-        $strconv = iconv('UTF-8', 'ISO-8859-1', $str);
+        $strconv = self::convertToLatin1($str);
         $this->SetXY($x, $y);
         $this->Cell($wid, SystemConfig::getValue('incrementY'), $strconv, 1, 0, 'R');
     }
 
     public function printCenteredCell($x, $y, $wid, $str): void
     {
-        $strconv = iconv('UTF-8', 'ISO-8859-1', $str);
+        $strconv = self::convertToLatin1($str);
         $this->SetXY($x, $y);
         $this->Cell($wid, SystemConfig::getValue('incrementY'), $strconv, 1, 0, 'C');
     }
 
     public function writeAt($x, $y, $str): void
     {
-        $strconv = iconv('UTF-8', 'ISO-8859-1', $str);
+        $strconv = self::convertToLatin1($str);
         $this->SetXY($x, $y);
         $this->Write(SystemConfig::getValue('incrementY'), $strconv);
     }
 
     public function writeAtCell($x, $y, $wid, $str): void
     {
-        $strconv = iconv('UTF-8', 'ISO-8859-1', $str);
+        $strconv = self::convertToLatin1($str);
         $this->SetXY($x, $y);
         $this->MultiCell($wid, 4, $strconv, 1);
     }

src/ChurchCRM/Reports/PdfDirectory.php

@@ -43,10 +43,10 @@ public function __construct($nc = 1, $paper = 'letter', $fs = 10, $ls = 4)
         $this->_NCols = $nc;
         $this->_ColWidth = 190 / $nc - $this->_Gutter;
 
-        $this->sChurchNameEncoded = iconv('UTF-8', 'ISO-8859-1', SystemConfig::getValue('sChurchName'));
-        $this->sChurchAddressEncoded = iconv('UTF-8', 'ISO-8859-1', SystemConfig::getValue('sChurchAddress'));
-        $this->sChurchCityEncoded = iconv('UTF-8', 'ISO-8859-1', SystemConfig::getValue('sChurchCity'));
-        $this->sChurchStateEncoded = iconv('UTF-8', 'ISO-8859-1', SystemConfig::getValue('sChurchState'));
+        $this->sChurchNameEncoded = self::convertToLatin1(SystemConfig::getValue('sChurchName'));
+        $this->sChurchAddressEncoded = self::convertToLatin1(SystemConfig::getValue('sChurchAddress'));
+        $this->sChurchCityEncoded = self::convertToLatin1(SystemConfig::getValue('sChurchCity'));
+        $this->sChurchStateEncoded = self::convertToLatin1(SystemConfig::getValue('sChurchState'));
     }
 
     public function header(): void
@@ -125,7 +125,7 @@ public function titlePage(): void
         );
         $this->MultiCell(197, 10, $sContact, 0, 'C');
         $this->Cell(10);
-        $sDirectoryDisclaimer = iconv('UTF-8', 'ISO-8859-1', $sDirectoryDisclaimer);
+        $sDirectoryDisclaimer = self::convertToLatin1($sDirectoryDisclaimer);
         $this->MultiCell(197, 10, $sDirectoryDisclaimer, 0, 'C');
         $this->addPage();
     }
@@ -489,7 +489,7 @@ public function addRecord($sName, $text, $numlines, $fid, $pid): void
         }
         $this->checkLines($numlines, $dirimg);
 
-        $this->printName(iconv('UTF-8', 'ISO-8859-1', $sName));
+        $this->printName(self::convertToLatin1($sName));
 
         $_PosX = ($this->_Column * ($this->_ColWidth + $this->_Gutter)) + $this->_Margin_Left;
         $_PosY = $this->GetY();
@@ -503,7 +503,7 @@ public function addRecord($sName, $text, $numlines, $fid, $pid): void
             $this->SetXY($_PosX, $_PosY + $h + 2);
         }
 
-        $this->MultiCell($this->_ColWidth, $this->_LS, iconv('UTF-8', 'ISO-8859-1', $text), 0, 'L');
+        $this->MultiCell($this->_ColWidth, $this->_LS, self::convertToLatin1($text), 0, 'L');
         $this->SetY($this->GetY() + $this->_LS);
     }
 }

src/ChurchCRM/Reports/PdfLabel.php

@@ -169,7 +169,7 @@ public function addPdfLabel($texte): void
         $_PosX = $this->_Margin_Left + ($this->_COUNTX * ($this->_Width + $this->_X_Space));
         $_PosY = $this->_Margin_Top + ($this->_COUNTY * ($this->_Height + $this->_Y_Space));
         $this->SetXY($_PosX + 3, $_PosY + 3);
-        $this->MultiCell($this->_Width, $this->_Line_Height, iconv('UTF-8', 'ISO-8859-1', $texte));
+        $this->MultiCell($this->_Width, $this->_Line_Height, self::convertToLatin1($texte));
         $this->_COUNTY++;
 
         if ($this->_COUNTY == $this->_Y_Number) {

src/Reports/NameTags.php

@@ -56,7 +56,7 @@
         }
 
         $pdf->SetXY($PosX + $pdf->_Width / 2, $PosY + 3);
-        $pdf->MultiCell($pdf->_Width / 2, $pdf->_Line_Height, iconv('UTF-8', 'ISO-8859-1', $labelStr));
+        $pdf->MultiCell($pdf->_Width / 2, $pdf->_Line_Height, $pdf->convertToLatin1($labelStr));
         $pdf->setCharSize($sFontSize);
         $pdf->addPdfLabel('');
     } else {