# bonlineco/module-arabic-invoice

> Arabic and RTL-ready invoices, credit memos, packing slips, order PDFs, and printable sales pages for Magento 2.

`composer require bonlineco/module-arabic-invoice`

Canonical URL: https://packagento.com/bonlineco/module-arabic-invoice

## At a glance

- **Vendor**: bonlineco (https://packagento.com/bonlineco.md)
- **Latest version**: v1.1.0 — released 2026-07-12
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/bonlineco/module-arabic-invoice and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require bonlineco/module-arabic-invoice:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Arabic and RTL-ready invoices, credit memos, packing slips, order PDFs, and printable sales pages for Magento 2.

## README

[![Latest release](https://img.shields.io/github/v/release/o0mohd0o/magento2-arabic-invoice)](https://github.com/o0mohd0o/magento2-arabic-invoice/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Magento 2](https://img.shields.io/badge/Magento-2.4.6%2B-f26322.svg)](https://github.com/magento/magento2)

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.

![Sanitized Arabic invoice preview using fictional sample data](docs/images/arabic-invoice-preview.png)

_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

| Component | Requirement |
| --- | --- |
| Magento Open Source | 2.4.6 or newer in the 2.4 line |
| PHP | 8.1–8.4, subject to the Magento version's own support matrix |
| TCPDF | 6.8 or newer in the 6.x line |
| Storefront print theme | Magento Luma or Blank |

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:

```bash
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:

```bash
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

_(README truncated for .md surface. Full README on https://packagento.com/bonlineco/module-arabic-invoice.)_

## 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.

[1.0.0]: https://github.com/o0mohd0o/magento2-arabic-invoice/releases/tag/v1.0.0
[1.1.0]: https://github.com/o0mohd0o/magento2-arabic-invoice/releases/tag/v1.1.0

## Recent Versions

| Version | Released |
|---|---|
| v1.1.0 | 2026-07-12 |
| v1.0.0 | 2026-07-12 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| ext-intl | * |
| magento/framework | >=103.0.6 <104.0.0 |
| magento/module-backend | >=102.0.6 <103.0.0 |
| magento/module-catalog | >=104.0.6 <105.0.0 |
| magento/module-payment | >=100.4.6 <101.0.0 |
| magento/module-sales | >=103.0.6 <104.0.0 |
| magento/module-shipping | >=100.4.6 <101.0.0 |
| magento/module-store | >=101.1.6 <102.0.0 |
| magento/module-ui | >=101.2.6 <102.0.0 |
| php | >=8.1 <8.5 |
| tecnickcom/tcpdf | ^6.8 |

## Quality

Latest release (v1.1.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | not tested |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 102 | 5 errors, 97 warnings (ruleset: Magento2), 23 auto-fixable with phpcbf |
| PHPMD | Warning | 30 | 30 rule violations (UnusedPrivateField:29, ExcessiveClassLength:1) |
| Cpd | Warning | 4 | 4 duplicated chunks spanning 119 total lines (min-lines=5, min-tokens=70) |
| Composer validate | Pass | 0 |  |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 11 | 11 | – | – |
| 2.4.8 | – | 11 | 11 | – |
| 2.4.9 | – | – | 11 | N/A |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["bonlineco/module-arabic-invoice"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

bonlineco is a Magento 2 vendor on Packagento. See https://packagento.com/bonlineco.md for their full catalogue.