Fixing the Magento 2 PDF Entity Glitch: A Deep Dive into Custom Option Rendering

At Shopping Mover, we specialize in navigating the intricate landscape of Magento 2, from seamless migrations to optimizing existing Adobe Commerce and Open Source installations. Our deep involvement in the Magento ecosystem means we're often at the forefront of understanding and addressing the subtle challenges that can impact an e-commerce business. One such challenge, recently highlighted in the community, involves a seemingly minor yet impactful rendering issue within Magento's PDF generation for sales documents.

Issue #41041 on GitHub, originating from a crucial pull request, meticulously details a bug where custom option values on order, invoice, credit memo, and shipment PDFs are displayed as raw HTML entities rather than their correctly decoded characters. This is a classic example of how a small technical oversight can lead to an unprofessional customer experience.

The Problem: '42" x 80"' Instead of '42" x 80"'

Imagine a customer places an order for a highly configurable product on your Magento store. They select a custom option, perhaps a 'Size' field, and input or choose a value like 42" x 80". On your storefront, in the customer's account, and even within order confirmation emails, this value appears perfectly. However, when you generate the official sales documents – the invoice, credit memo, or shipment PDF – the custom option value inexplicably renders as 42" x 80". The double quotes are replaced by their HTML entity equivalent, ".

While this might seem like a minor aesthetic glitch, it can significantly detract from the professionalism of your brand. Such anomalies can lead to customer confusion, necessitate support inquiries, and undermine the trust and polish you strive to convey through your e-commerce operations. For merchants running Adobe Commerce or Magento Open Source, maintaining a pristine brand image across all touchpoints, including transactional documents, is paramount.

The Technical Deep Dive: Unpacking the Asymmetry

The root of this issue lies in the nuanced way Magento 2 handles and renders custom option values across its various output channels. When a custom option value is saved, it undergoes HTML escaping. This happens via methods like Magento\\Catalog\\Model\\Product\\Option\\Type\\*::getFormattedOptionValue() or getPrintableOptionValue(), which store values like 42" as 42" in the sales_order_item.product_options database field.

For HTML-based interfaces – such as the Magento admin panel, customer account pages, or even order emails – modern web browsers automatically decode these HTML entities, presenting the correct 42" x 80" to the user. This is standard web behavior.

However, Magento's PDF generation process utilizes Zend_Pdf, a non-HTML canvas. The critical asymmetry identified by the community is that while the PDF renderers (specifically DefaultInvoice.php, DefaultCreditmemo.php, and DefaultShipment.php) already perform HTML entity decoding for item names and SKUs (using methods like DefaultInvoice::prepareText() which calls html_entity_decode, or direct calls in other renderers), they were drawing the custom option values raw, directly from their HTML-escaped stored format. This oversight meant the raw entity, ", was printed directly onto the PDF canvas.

// Example of how item names/SKUs were handled (simplified)
$text = html_entity_decode($item->getName(), ENT_QUOTES, 'UTF-8');
$this->drawText($text, ...);

// How custom option values were handled (before the fix)
$opti>getValue(); // Still HTML-escaped
$this->drawText($optionValue, ...);

The Solution: Decoding at the Draw Site

The elegant solution, proposed and implemented in the associated pull request, addresses this asymmetry by introducing HTML entity decoding specifically at the "draw site" within the PDF renderers. This ensures that custom option values receive the same treatment as item names and SKUs before being rendered onto the PDF canvas.

• Invoice/DefaultInvoice.php: The fix integrates the option value decoding into the existing prepareText() method, which already handles decoding and RTL (right-to-left) text reversal for item names and SKUs. This ensures consistent processing.
• Creditmemo/DefaultCreditmemo.php and Shipment/DefaultShipment.php: These renderers now explicitly call html_entity_decode() on the option values, mirroring their existing handling for names and SKUs.

Crucially, this fix is applied precisely where the rendering occurs, rather than altering the stored values or the shared AbstractItems::getItemOptions() method. This approach is robust because:

• It respects the @api contract of shared methods, preventing unintended side effects.
• It ensures that HTML surfaces (admin, emails, customer account) remain unaffected, as they correctly handle HTML entities already.
• The decoding occurs after any stripTags operations, meaning a stored value like <b> will safely render as literal glyph text on the PDF, without any risk of HTML or JavaScript interpretation.

This targeted fix, confirmed to be reproducible on Magento 2.4.x (including 2.4-develop), ensures that your sales documents will now display custom option values accurately, enhancing both clarity and professionalism.

Why This Matters for Your Magento 2 Store and Future Migrations

For any business leveraging Magento 2 (Adobe Commerce or Open Source), the quality and accuracy of transactional documents are non-negotiable. This fix, while seemingly minor, underscores several critical aspects of maintaining a healthy and professional e-commerce platform:

• Brand Professionalism: Accurate PDFs reinforce your brand's attention to detail and commitment to quality.
• Customer Experience: Clear and correct documents reduce confusion and improve customer satisfaction.
• Platform Stability: Addressing such bugs through community contributions and official updates ensures the platform remains robust and reliable.
• Development & Integrations: This issue highlights the complexities involved in integrating different rendering engines (HTML vs. PDF) and the need for meticulous development practices.

As e-commerce migration experts at Shopping Mover, we constantly emphasize the importance of keeping your Magento 2 installation updated. Bugs like this are routinely identified and fixed by the vibrant Magento community and Adobe, making regular upgrades a vital part of your long-term strategy. Whether you're planning a migration to the latest Magento 2 version, upgrading an existing installation, or require custom development and integration work, understanding these nuances is key to a successful operation.

Our team is equipped to handle complex Magento 2 development and integration challenges, ensuring that your store not only performs flawlessly but also presents a polished and professional image across all customer touchpoints. We help businesses like yours leverage the full power of Magento 2, ensuring that even the smallest details, like a correctly rendered custom option on a PDF, contribute to your overall success.

Conclusion

The resolution of Magento 2 Issue #41041 is a testament to the ongoing refinement of the platform and the power of its community. By ensuring that custom option values are correctly decoded in sales PDFs, Magento continues to improve the merchant and customer experience. For businesses seeking to maintain a cutting-edge, professional, and bug-free Magento 2 store, staying informed about such fixes and partnering with experienced development teams like Shopping Mover is essential. We're here to ensure your Magento journey is smooth, efficient, and always professional.