Bonlineco Arabic Invoice for Magento 2

Arabic and mixed-direction sales-document PDFs for Magento 2, with neutral
native Luma/Blank browser-print styling. The module uses TCPDF's Unicode
support for invoices, credit memos, packing slips, order summaries, and mixed
"Print All" batches. It switches PDF layout to RTL for Arabic store locales
while keeping Latin SKUs, prices, tracking numbers, and pagination readable.

Why this module exists

Sales documents often mix Arabic customer details with Latin SKUs, currency
codes, phone numbers, tracking numbers, and product options. A font change alone
does not solve column order, alignment, pagination, or mixed-direction text.
This module adds one shared renderer for Magento's printable sales documents
while leaving Magento's core PDF model contracts unchanged.

Preview generated by the included development fixture; all names, addresses,
order numbers, and SKUs are fictional.

Features

• Arabic and English invoices, credit memos, packing slips, and order PDFs.
• Automatic RTL mode for every store locale beginning with ar.
• Egyptian Arabic (ar_EG) translations included.
• Single and mass invoice PDF downloads from invoice and order screens.
• Single and mass credit memo PDF downloads from credit memo and order screens.
• Single and mass packing-slip downloads, including tracking and quantities.
• Dedicated Print Order PDF button and Print Orders (PDF) grid action.
• ACL-aware Print All PDF containing invoices, packing slips, and credit
  memos on one valid TCPDF canvas.
• Multi-store locale emulation and per-store PDF logo support.
• Simple, configurable, virtual, grouped, and fixed/dynamic bundle handling.
• Product options, actual configurable SKUs, child bundle selections, partial
  document quantities, taxes, discounts, and mixed-direction identifiers.
• Customer-visible invoice, shipment, and credit memo comments with an explicit
  customer-notified label; internal Admin notes are excluded.
• Repeating item headers, continuation headings, and page footers.
• Magento's merged pdf.xml totals for invoices, credit memos, and order
  summaries, including compatible extension-provided totals.
• Native Magento Sales templates for browser printing; no copied theme templates.
• Scoped Luma/Blank RTL, responsive, and print CSS.
• Invalid IDs, empty selections, unauthorized Print All document types, corrupt
  logos, and removed payment modules fail safely.

Requirements

Verified on Magento Open Source 2.4.8 with TCPDF 6.10.1. Adobe Commerce uses
the same Sales foundations but has not been independently tested for v1.1.0.

Installation

Composer from GitHub

Until the package is registered on Packagist, add the GitHub repository as a
VCS source:

composer config repositories.bonlineco-arabic-invoice vcs \
  https://github.com/o0mohd0o/magento2-arabic-invoice.git
composer require bonlineco/module-arabic-invoice:^1.1

bin/magento module:enable Bonlineco_ArabicInvoice
bin/magento setup:upgrade
bin/magento cache:flush

In production mode, follow with the compilation and static-content deployment
commands used by your deployment process.

Release ZIP under app/code

The installable release asset already contains the
app/code/Bonlineco/ArabicInvoice directory structure. Extract it at the
Magento project root, then install TCPDF and enable the module:

composer require tecnickcom/tcpdf:^6.8
bin/magento module:enable Bonlineco_ArabicInvoice
bin/magento setup:upgrade
bin/magento cache:flush

Configuration

No module-specific configuration is required.

1. Set the store locale under Stores → Configuration → General → Locale
   Options. ar_EG enables both RTL output and the included translations.
2. Set the PDF logo under Stores → Configuration → Sales → Sales → Invoice
   and Packing Slip Design → Logo for PDF Print-outs.
3. Set the store name under Stores → Configuration → General → Store
   Information. It is used in the PDF footer when available.

For ar_SA, ar_AE, or another ar_* locale, RTL activates automatically,
but install the matching Magento language pack or add a locale CSV if you need
localized phrases beyond the included ar_EG catalog.

Usage

• Sales → Invoices → View → Print downloads one localized PDF.
• Sales → Invoices → Actions → PDF Invoices downloads selected invoices.
• Sales → Orders → Actions → Print Invoices downloads every invoice linked
  to the selected orders.
• Sales → Credit Memos → View → Print and PDF Credit Memos cover single
  and selected refunds; the order grid action covers refunds for selected orders.
• Sales → Shipments → View → Print and PDF Shipments cover single and
  selected packing slips; the order grid action covers selected orders.
• Sales → Orders → View → Print Order PDF downloads one order summary.
• Sales → Orders → Actions → Print Orders (PDF) downloads selected order
  summaries without changing Magento's native document actions.
• Sales → Orders → Actions → Print All creates one PDF in Magento's native
  document order: invoices, packing slips, then credit memos. Document types the
  current Admin user cannot access are excluded.
• Customer and guest order/invoice print routes continue using Magento's native
  templates with scoped RTL and print refinements.

How it works

The Admin integration uses scoped plugins around Magento's existing invoice,
credit memo, shipment, and Print All actions. Routing, HTTP methods, ACL checks,
and grid selection remain owned by Magento; the plugins validate document IDs
and repository results before rendering. The dedicated
order routes use the module's own bonlineco_arabicinvoice Admin front name, so
they do not shadow Magento or another module's sales controllers. Each
download receives a fresh, single-use TCPDF renderer instance.

For totals, the renderer reads Magento's merged PDF configuration and invokes
configured total models in sort order. Invoices and credit memos use their
native sources. Order summaries use an order-source adapter, with a standard
subtotal/shipping/discount/tax/grand-total fallback if an extension total only
supports invoice or credit memo entities.

The browser-print layer does not override PHTML files. It adds one body class
and one stylesheet to Magento's logged-in and guest order/invoice print handles,
preserving native renderer lists, gift messages, totals, and theme fallback.

Testing

From a Magento installation containing this package:

vendor/bin/phpunit -c vendor/bonlineco/module-arabic-invoice/phpunit.xml.dist
find vendor/bonlineco/module-arabic-invoice -name '*.php' -print0 \
  | xargs -0 -n1 php -l
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f en_US ar_EG

The fictional development fixture can render every supported document type:

MAGENTO_ROOT=/path/to/magento SAMPLE_DOCUMENT=invoice php dev/render-sample.php /tmp/invoice.pdf
MAGENTO_ROOT=/path/to/magento SAMPLE_DOCUMENT=creditmemo php dev/render-sample.php /tmp/creditmemo.pdf
MAGENTO_ROOT=/path/to/magento SAMPLE_DOCUMENT=shipment php dev/render-sample.php /tmp/packing-slip.pdf
MAGENTO_ROOT=/path/to/magento SAMPLE_DOCUMENT=order php dev/render-sample.php /tmp/order.pdf
MAGENTO_ROOT=/path/to/magento SAMPLE_DOCUMENT=all php dev/render-sample.php /tmp/print-all.pdf

Use SAMPLE_ITEM_COUNT=80 for pagination testing and SAMPLE_LOCALE=en_US
or ar_EG for direction testing. SAMPLE_STORE_CODE must identify a store
whose configured locale matches the intended language when Magento environment
emulation is active.

For PDF QA, validate both structure and rendering:

pdfinfo invoice.pdf
pdffonts invoice.pdf
pdftotext -layout invoice.pdf -
pdftoppm -png -r 150 invoice.pdf invoice-preview

Never commit a production invoice or screenshot. Test artifacts must use
fictional customers, addresses, order numbers, and SKUs.

Compatibility notes

• The module targets Magento's core Admin sales-document actions with around
  plugins. Another PDF extension targeting the same actions can still conflict
  depending on plugin order and whether it calls the next plugin.
• Browser print styling is tested with Luma/Blank. Hyvä is intentionally outside
  the v1.1.0 support claim.
• Invoice, shipment, credit memo, and order emails are not modified.
• Shipping-label PDFs are not modified; packing slips are supported.
• Customer-visible invoice, shipment, and credit memo comments are printed with
  their notification state. Internal Admin comments are deliberately excluded.
• Print All deliberately retains Magento's document semantics. Order summaries
  are available through the separate Print Orders action.
• The renderer is not an electronic-invoicing, ZATCA, QR-code, signing, or tax
  compliance solution. Merchants remain responsible for legal invoice fields.
• A single exceptionally large item description may need a merchant-specific
  renderer or truncation policy.

Contributing and security

See CONTRIBUTING.md before opening a pull request. Report
security issues privately as described in SECURITY.md.

License

Released under the MIT License. TCPDF is installed separately and is
covered by its own LGPL-3.0-or-later license; see
THIRD_PARTY_NOTICES.md.

Changelog

All notable changes to this project are documented here.

1.1.0 - 2026-07-12

• Added Arabic/RTL credit memo PDFs for single, grid-mass, and order-mass actions.
• Added Arabic/RTL packing slips with tracking, ordered/shipped quantities, and comments.
• Added dedicated single and mass order-summary PDF actions under an owned Admin route.
• Added ACL-aware mixed-document rendering for Magento's native Print All action.
• Generalized the TCPDF renderer, totals, pagination, item options, bundles, and multi-store handling.
• Added secure payment PDF text with removed-extension fallback.
• Added customer-visible document comments with notification labels while excluding internal notes.
• Expanded Egyptian Arabic translations and translation-coverage validation.
• Added controller, plugin, ACL, failure-path, and document-renderer tests.
• Preserved Magento's Print All semantics instead of replacing it with order summaries.

1.0.0 - 2026-07-12

• Added Arabic and mixed-direction invoice PDFs powered by TCPDF.
• Added automatic RTL layout for store locales beginning with ar.
• Added Admin single-invoice, invoice-grid mass, and order-grid mass downloads.
• Added multi-store locale emulation and store-configured PDF logos.
• Added Magento pdf.xml total-model support for core and extension totals.
• Added neutral, Luma-compatible order and invoice print styling.
• Added Egyptian Arabic translations and long-invoice pagination.
• Added malformed-logo fallback and bidi-control sanitization.