PDF Email Manager

OpenCart 3.0.3.x+ PHP 7.4 – 8.2 Verzió 1.0.0 MySQL 5.6+ / MariaDB 10.x

Szabályalapú PDF díjbekérő generátor és email küldő OpenCart 3.x adminisztrációhoz. Rendelés státuszváltásra automatikusan generál PDF-et, elmenti a szerverre, és elküldi a vásárlónak emailben – minden konfiguráció az admin felületen belül.

1 Funkciók

📋

Szabályalapú PDF generálás

Meghatározható, hogy melyik státusz + fizetési mód kombinációra fusson le a generálás.

🔢

Verziókezelt PDF tárolás

Minden újragenerálás új verziót hoz létre (PF-1001.pdf, PF-1001-v2.pdf), a régi fájlok megmaradnak.

📧

Automatikus email küldés

A generált PDF automatikusan csatolódik és kiküldésre kerül a vásárló email címére.

🌐

Többnyelvű sablonok

Szabályonként és nyelvenkénti (hu/en) email tárgy, email törzs és PDF sablon állítható be.

📊

Saját Log fül

Minden esemény (siker, figyelmeztetés, hiba) nyomon követhető az admin felületen.

🔔

Admin hibakövető email

Hiba esetén az admin email értesítést kap a probléma részleteivel.

🏪

Multistore kompatibilis

A webáruház neve rendelésenként az order táblából töltődik be automatikusan.

⚡

Post-delivery automatizálás

Email küldés után opcionálisan automatikusan átvált a rendelés egy másik státuszra.

🔌

Bővíthető architektúra

ActionInterface alapú; jövőbeli akciók (SMS, webhook) könnyen hozzáadhatók.

🛡️

Versenyhelyzet-védelett

InnoDB tranzakcióval védett verziókezelés; párhuzamos kéréseknél sem keletkezhet dupla verzió.

🚀

Nem lassítja a vásárlást

Csak az admin státuszváltásakor fut; a checkout folyamattól teljesen független.

🔒

Biztonsági védelmek

Path traversal védelem a logón; GTM/OCM JavaScript automatikusan eltávolításra kerül a PDF-ből.

2 Hogyan működik

Admin: rendelés státuszának megváltoztatása

▼

OC Event: catalog/model/checkout/order/addOrderHistory/after

▼

Illeszkedő szabályok keresése
(státusz ID + fizetési mód kód alapján)

▼

NEM

Vége

IGEN

Sablon renderelése
(változók behelyettesítése)

▼

PDF generálása (TCPDF)
Mentés: image/order_pdf/YYYY/MM/

▼

Email összeállítása + PDF csatolása
Küldés az OC SMTP beállításaival

▼

Log bejegyzés (oc_pe_log)

▼

Post-delivery státusz beállítása
(ha be van állítva)

3 Rendszerkövetelmények

Komponens	Minimális verzió	Megjegyzés
OpenCart	3.0.3.x	OpenCart 4.x nem támogatott
PHP	7.4	Tesztelt: 7.4, 8.0, 8.1, 8.2
MySQL / MariaDB	5.6 / 10.x	InnoDB tárolómotor szükséges
TCPDF	6.x	Manuálisan telepítendő (ld. 4.1)

Szükséges PHP kiterjesztések

Kiterjesztés	Mire kell
`mbstring`	Többbájtos karakterkezelés – ékezetes karakterek helyes kezelése
`gd`	Képek PDF-be ágyazásához (céglogó renderelés)
`fileinfo`	Logó MIME típus validálásához

ℹ️

OpenCart SMTP: A bővítmény az OpenCart saját mail osztályát használja email küldéshez. Az SMTP-t be kell állítani: Admin → System → Settings → Mail fül.

4 Telepítés

4.1 TCPDF könyvtár telepítése

A TCPDF nem része a csomagnak (~15–20 MB). Külön kell letölteni és telepíteni.

Nyissa meg a TCPDF kiadások oldalát:
https://github.com/tecnickcom/TCPDF/releases
Töltse le a legújabb stabil release ZIP fájlját (pl. tcpdf-6.x.x.zip)
Csomagolja ki a letöltött archívumot
A kicsomagolt mappa teljes tartalmát másolja ide:

{opencart_gyökér}/system/library/pdf_email/vendor/tcpdf/ tcpdf.php ← ezt keresi a bővítmény tcpdf_autoconfig.php config/ fonts/ include/ ...

⚠️

A vendor/tcpdf/tcpdf.php fájlnak léteznie kell. Ha hiányzik, a Beállítások fülön piros jelzés jelenik meg és PDF nem generálódik.

4.2 Bővítmény fájljainak feltöltése

A lehetőség – FTP (ajánlott):

Shell – FTP feltöltés

upload/admin/    → {opencart_gyökér}/admin/
upload/catalog/  → {opencart_gyökér}/catalog/
upload/system/   → {opencart_gyökér}/system/
upload/image/    → {opencart_gyökér}/image/

B lehetőség – Extension Installer:
Admin → Extensions → Installer → töltse fel a pdf_email_manager_v1.0.0.zip fájlt, majd kövesse a varázsló lépéseit.

4.3 Mappa jogosultság beállítása

Az image/order_pdf/ mappának írhatónak kell lennie. Ha a bővítmény nem tudja automatikusan létrehozni:

Shell – Jogosultság beállítása

mkdir -p {opencart_gyökér}/image/order_pdf/
chmod 755 {opencart_gyökér}/image/order_pdf/
# Ha 755 nem elég, próbálja 775-tel

4.4 Bővítmény aktiválása az OpenCart adminban

Lépjen az Admin → Extensions → Modules menübe
Keresse meg: PDF Email Manager
Kattintson az Install (zöld +) gombra

Ez automatikusan létrehozza az 5 adatbázis táblát (oc_pe_* prefix) és regisztrálja az OpenCart event hook-ot.
Kattintson az Edit (ceruza ikon) gombra a konfiguráláshoz

✅

Telepítés ellenőrzése: a Beállítások fülön a TCPDF státusz legyen zöld (könyvtár megtalálható, verzió olvasható), és az image/order_pdf/ mappa legyen írható.

5 Beállítás

5.1 Globális beállítások

Elérési út: Extensions → Modules → PDF Email Manager → Edit → Beállítások fül

Általános

Mező	Leírás	Megjegyzés
Bővítmény aktív	Főkapcsoló – kikapcsolt állapotban semmilyen PDF nem generálódik	Mindig ellenőrizze, hogy be van-e kapcsolva
Díjbekérő előtag	A fájlnév és a sorszám előtagja	`PF` → `PF-1001.pdf`; csak betű és kötőjel ajánlott
Admin értesítő email	Hiba esetén erre az email-re megy az értesítő	Hagyja üresen, ha nem kell értesítés

Cégadatok (PDF fejléc és sablon változók)

Mező	Változó	Leírás
Cég neve	{company_name}	Megjelenik a PDF fejlécében
Cég székhelye	{company_address}	Többsoros szöveg; `<br>` sortörésként jelenik meg a PDF-ben
Adószám	{company_tax_number}	Cégadat a PDF-ben
Bankszámlaszám	{company_bank_account}	Megjelenik a PDF-ben és az email szövegben
Telefon	{company_phone}	Cégadat
Email	{company_email}	Cégadat
Logó	{company_logo}	Relatív útvonal az `image/` mappán belül (pl. `catalog/logo.png`); JPG/PNG/GIF/WebP; max. 80px magas; base64 `<img>` tagként helyettesítődik be

ℹ️

Multistore: a {store_name} változó nem innen, hanem a rendelés adataiból töltődik be; több store esetén is automatikusan a megfelelő store nevét tartalmazza.

Vásárló egyedi mezők

Mező	Leírás
Cég egyedi mező azonosítója	Ha a vásárló cégnevét egy custom field tárolja, adja meg annak ID-ját. A {billing_name} változó ezt fogja tartalmazni. Az ID megnézése: Admin → Customers → Custom Fields → első oszlop
Adószám egyedi mező azonosítója	A vásárló adószámát tároló custom field ID-ja; a {billing_tax_number} változóba kerül.

ÁFA kulcsok

Az OpenCart a szállítási költség, fizetési díj, kupon és egyéb tételek ÁFA tartalmát nem mindig tárolja tételesen. Ezek a beállítások határozzák meg, hogy a {products_table} és {totals_rows} változókban milyen ÁFA % szerepeljen.

Mező	Alapértelmezett	Vonatkozik
Szállítási ÁFA %	`27`	Szállítási sor
Fizetési díj ÁFA %	`27`	Fizetési díj sor
Kupon/utalvány ÁFA %	`0`	Kupon, ajándékutalvány sorok
Egyéb tételek ÁFA %	`27`	Minden egyéb `totals` sor

PDF oldalbeállítások

Mező	Alapértelmezett	Leírás
Papírméret	`A4`	Lehetséges: A3, A4, A5, LETTER, LEGAL
Felső margó (mm)	`20`	Oldalmargók milliméterben
Alsó margó (mm)	`20`
Bal margó (mm)	`15`
Jobb margó (mm)	`15`

5.2 Szabályok létrehozása

Elérési út: Extensions → Modules → PDF Email Manager → Edit → Szabályok fül → Új szabály

Mező	Leírás
Szabály neve	Belső azonosítás; nem jelenik meg a vásárló felé (pl. „Díjbekérő – Átutalás")
Trigger státusz	Ha a rendelés erre a státuszra vált, a szabály lefut
Post-delivery státusz	(opcionális) Email sikeres küldése után a bővítmény automatikusan erre a státuszra állítja a rendelést
Fizetési módok	Melyik fizetési módoknál fusson le. Ha egyik sem jelölt, az összes fizetési módra érvényes.
Fizetési mód megnevezése	(opcionális) Felülírja a {payment_method} változó értékét (pl. „Banki átutalás 15 napon belül")
Sorrend	Ha több szabály is illeszkedik, kisebb szám = korábban fut le
Aktív	Inaktív szabály nem fut le, de megmarad a konfigurációban

💡

Tipp: Az OpenCart 3 az order táblában nem tárolja a payment_code-ot külön oszlopban. Ha a fizetési mód szűrés nem a várt módon működik, hagyja üresen a listát (= minden fizetési módra érvényes) és ellenőrizze a Log fülön a bővítmény bejegyzéseit.

5.3 Sablonok szerkesztése

Elérési út: Szabályok listában → Sablon ikon (kék ceruza) az adott szabály sorában

Mező	Leírás
Email tárgy	Az email tárgysora; sablon változók itt is használhatók
Email szöveg	HTML formátumú email törzs
PDF sablon	Teljes HTML dokumentum, amelyet a TCPDF renderel PDF-fé

Az „Alap sablon betöltése" gomb egy kész, azonnal használható díjbekérő sablont tölt be az aktív nyelv fülre.

⚠️

TCPDF HTML/CSS korlátok: A TCPDF egyszerűsített HTML értelmezőt használ, nem teljes böngészőmotort. float, flexbox, grid nem támogatott – táblázat-alapú elrendezést ajánlott használni. A beépített DejaVu Sans betűtípus teljes UTF-8 (ékezetes) karakterkészletet támogat. A sablonban legyen: <meta charset="utf-8"> és font-family: DejaVu Sans.

6 Használat

Díjbekérő küldése egy rendeléshez

Lépjen az Admin → Sales → Orders menübe
Nyissa meg a kívánt rendelést
Az Order History szekcióban válassza ki azt a státuszt, amelyre szabályt hozott létre
(Opcionálisan) írjon megjegyzést, majd kattintson az Add History gombra

A bővítmény automatikusan elvégzi a következőket:

#	Lépés
1	Ellenőrzi, hogy a szabály feltételei teljesülnek-e (státusz + fizetési mód)
2	Meghatározza a megfelelő sablont és nyelvet
3	Behelyettesíti a változókat a rendelés adataival
4	Generálja a PDF-et és elmenti: `image/order_pdf/YYYY/MM/PF-{order_id}.pdf`
5	Elküldi a vásárlónak a PDF-et email csatolmányként
6	Rögzíti a műveletet a logban
7	(Ha be van állítva) automatikusan átváltja a rendelést a post-delivery státuszra

Újragenerálás (már létező PDF esetén)

Ha egy rendeléshez már van generált PDF és a szabály újra lefut:

Új verziószámmal generálódik (PF-1001-v2.pdf, PF-1001-v3.pdf stb.)
Az email az új verziót küldi el
A régi fájlok megmaradnak a szerveren

Generált fájlok böngészése

Extensions → Modules → PDF Email Manager → Edit → Fájlok fül

Listázza az összes generált PDF-et generálási idővel
Szűrhető rendelésszámra
Minden fájlhoz közvetlen letöltési link
Jelzi, ha a fájl fizikailag hiányzik a szerverről

Log megtekintése

Extensions → Modules → PDF Email Manager → Edit → Log fül

Szint	Mikor keletkezik
INFO	Sikeres műveletek (PDF generálva, email elküldve)
WARNING	Figyelmeztetések (pl. nem illeszkedett egyetlen szabály sem)
ERROR	Hibák (TCPDF nincs telepítve, email küldési hiba, fájlrendszer hiba stb.)

7 Sablon változók

Az alábbi változók használhatók az email tárgyban, email szövegben és a PDF sablonban egyaránt.

Rendelés adatok

Változó	Leírás	Példa
{order_id}	Rendelésszám	`1001`
{proforma_number}	Díjbekérő sorszám (prefixszel és verzióval)	`PF-1001` vagy `PF-1001-v2`
{order_date}	Rendelés létrehozásának dátuma	`2025-01-15`
{current_date}	A PDF generálásának dátuma (mai nap)	`2025-01-16`
{payment_deadline}	Fizetési határidő (mai nap + beállított napok száma)	`2025-01-24`
{order_status}	Rendelés státuszának neve	`Feldolgozás alatt`
{payment_method}	Fizetési mód neve (szabályban felülírható)	`Banki átutalás`
{shipping_method}	Szállítási mód neve	`GLS futárszolgálat`
{version}	PDF verziószám (első generálásnál `1`)	`1`

Vásárló adatok

Változó	Leírás
{customer_name}	Vásárló teljes neve
{customer_email}	Vásárló email címe
{customer_telephone}	Vásárló telefonszáma
{billing_name}	Számlázási név (cég neve, ha be van állítva az egyedi mező ID; egyébként a vásárló neve)
{billing_address}	Számlázási cím (HTML, `<br>` sortörésekkel)
{billing_tax_number}	Vásárló adószáma (custom field alapján, ha be van állítva)
{shipping_address}	Szállítási cím (HTML, `<br>` sortörésekkel)

Tételek és összegek

Változó	Leírás
{products_table}	Teljes terméktáblázat előrenderelt HTML-ként (mennyiség, nettó egységár, ÁFA%, nettó összeg, ÁFA összeg, bruttó)
{totals_rows}	A rendelés összesítő sorainak HTML táblázat-sorai (részösszeg, szállítás, ÁFA, végösszeg stb.)
{subtotal}	Részösszeg formázva
{shipping_cost}	Szállítási költség formázva (pl. `Szállítás: 1 490 Ft`)
{tax}	ÁFA összeg formázva
{total}	Végösszeg (tizedes ponttal)
{total_huf}	Végösszeg egész forintban, ezres elválasztóval (pl. `1 234 567`)
{total_words}	Végösszeg magyar szövegesen (pl. `egymillió-kettőszázharmincnégy-ezer-ötszázhatvanhet forint`)

Cégadatok

Változó	Forrás
{store_name}	Rendelés adatai – multistore esetén automatikusan a megfelelő store neve
{company_name}	Beállítások fül
{company_address}	Beállítások fül
{company_tax_number}	Beállítások fül
{company_bank_account}	Beállítások fül
{company_phone}	Beállítások fül
{company_email}	Beállítások fül
{company_logo}	Beállítások fül – base64-kódolt `<img>` tagként helyettesítődik be; a PDF önálló fájlként is tartalmazza a logót

8 Fájlstruktúra

{opencart_gyökér}/ ├── admin/ │ ├── controller/extension/module/ │ │ └── pdf_email.php – Admin vezérlő (install/uninstall, CRUD, event handler) │ ├── model/extension/module/ │ │ └── pdf_email.php – Adatbázis műveletek │ ├── view/template/extension/module/ │ │ ├── pdf_email.twig – Szabályok lista főoldal │ │ ├── pdf_email_rule.twig – Szabály létrehozás / szerkesztés │ │ ├── pdf_email_template.twig – Sablon szerkesztő (email + PDF) │ │ ├── pdf_email_settings.twig – Globális beállítások │ │ ├── pdf_email_files.twig – Generált fájlok listája │ │ └── pdf_email_log.twig – Log megjelenítő │ └── language/ │ ├── hu-hu/extension/module/pdf_email.php – Magyar admin felület │ └── en-gb/extension/module/pdf_email.php – Angol admin felület │ ├── catalog/ │ └── controller/extension/module/ │ └── pdf_email.php – Catalog oldali event handler (OC event bridge) │ ├── system/library/pdf_email/ │ ├── PdfEmailCore.php – Fő logika: rule engine, event belépési pont │ ├── ActionInterface.php – Bővíthetőség: minden akció ezt implementálja │ ├── Actions/ │ │ └── GenerateAndEmailPdf.php – PDF generálás + email küldés akció │ ├── PdfGenerator.php – TCPDF wrapper │ ├── TemplateRenderer.php – Sablon változók behelyettesítése │ ├── Logger.php – Saját adatbázis logger │ └── vendor/ │ └── tcpdf/ ← TCPDF könyvtár (manuálisan telepítendő!) │ └── tcpdf.php ← ezt keresi a bővítmény │ └── image/order_pdf/ – Generált PDF fájlok tárolója ├── .htaccess – Directory listing letiltása └── 2025/ └── 01/ ├── PF-1001.pdf ├── PF-1001-v2.pdf └── PF-1002.pdf

9 Adatbázis táblák

A bővítmény 5 táblát hoz létre telepítéskor (oc_ prefix az OpenCart globális beállítása alapján). Az Uninstall törli az összes oc_pe_* táblát és az event hook-ot.

oc_pe_config

Globális beállítások kulcs-érték párokban, store_id-vel tagolva.

oc_pe_rule

Szabályok: státusz trigger, fizetési mód szűrő (JSON), post-delivery státusz, sorrend, aktív jelző.

oc_pe_template

Email és PDF sablonok – minden szabályhoz és nyelvhez külön bejegyzés.

oc_pe_generated

Generált fájlok audit trail-je: fájlútvonal, verzió, rendelés ID, időpont.

oc_pe_log

Bővítmény saját logja: szint (info/warning/error), rendelésszám, üzenet, időpont. Indexelt szint és order_id alapján.

10 Hibaelhárítás

🔴 TCPDF nincs telepítve – piros jelzés a Beállítások fülön

Tünet: A Beállítások fülön piros „Nincs telepítve" felirat; PDF nem generálódik.

Megoldás:

Ellenőrizze, hogy a system/library/pdf_email/vendor/tcpdf/tcpdf.php fájl létezik-e
Ha nem, töltse le a TCPDF-et: github.com/tecnickcom/TCPDF/releases
Másolja a tcpdf/ mappa teljes tartalmát a vendor/tcpdf/ mappába

❓ PDF nem generálódik, nincs hibaüzenet

Bővítmény ki van kapcsolva? → Beállítások fül → Bővítmény aktív → bekapcsolás
Szabály inaktív? → Szabályok listában ellenőrizze az „Aktív" oszlopot
Feltételek nem teljesülnek? → A rendelés fizetési módja szerepel-e a szabályban? (Próbáljon üres szűrőt = minden fizetési módra)
Log fül: minden esemény itt van rögzítve – a hibaüzenet itt olvasható

📤 PDF generálódik, de email nem megy ki

Ellenőrizze az OpenCart SMTP beállításait: Admin → System → Settings → Mail fül
Nézze meg a Log fülön az esetleges hibaüzenetet (pl. „SMTP connection failed")
Ellenőrizze, hogy az admin értesítő email megkapja-e a hibajelzést
Próbálja meg az OpenCart beépített „Test Mail" funkcióját

📁 image/order_pdf/ mappa nem jön létre automatikusan

Hozza létre kézzel FTP-n vagy SSH-n:

Shell

mkdir -p {opencart_gyökér}/image/order_pdf/
chmod 755 {opencart_gyökér}/image/order_pdf/
# Ha 755 nem elegendő:
chmod 775 {opencart_gyökér}/image/order_pdf/

🔤 Hibás / kérdőjeles karakterek a PDF-ben (ékezetes betűk)

A PDF sablonban legyen jelen: <meta charset="utf-8">
A betűkészlet a sablonban legyen DejaVu Sans – ez a TCPDF beépített, UTF-8 kompatibilis betűtípusa:
CSS
```
body { font-family: 'DejaVu Sans', sans-serif; }
```
Ellenőrizze, hogy a sablon UTF-8 kódolásban van mentve (nem Latin-2 vagy Windows-1250)

🖼️ PDF-ben a logó nem jelenik meg

A logó útvonala az image/ mappán belüli relatív elérési út legyen (pl. catalog/mylogo.png)
Ellenőrizze, hogy a fájl ténylegesen létezik az image/ mappában
Támogatott formátumok: JPG, PNG, GIF, WebP
Ajánlott logó magasság: max. 80px

💳 Fizetési mód szűrő nem működik megfelelően

Az OpenCart 3 az order táblában nem tárolja a payment_code-ot önálló mezőként. A bővítmény a következő sorrendben próbálja feloldani:

Lekérdezi az elérhető fizetési bővítmények listáját és a megjelenített névvel egyezteti
Ha nem egyezik, a megjelenített nevet normalizálja (kisbetűs, szóközök → aláhúzásjel)

Ha ez sem működik: hagyja üresen a fizetési módok listát a szabályban (= minden fizetési módra érvényes), és ellenőrizze a Log fülön a bővítmény bejegyzéseit.

🔌 A bővítmény nem fut le / nem kerül be a logba

Ellenőrizze az event regisztrációt: Admin → System → Events – legyen egy pdf_email nevű bejegyzés
Ha hiányzik: hajtsa végre újra az Uninstall → Install műveletet
Törölje az OpenCart cache-t: Admin → System → Cache → Clear Cache

11 Ismert korlátok

⚠
PHP kompatibilitás PHP 8.3+ nem tesztelt (valószínűleg működik, de nem garantált).
⚠
OpenCart verzió OpenCart 4.x nem támogatott – eltérő event rendszer és könyvtárstruktúra miatt.
⚠
Fizetési kód feloldás Az OC3 architektúra korlátja miatt a payment_code nem mindig 100%-osan feloldható. Az üres szűrő (minden fizetési mód) megbízhatóbb alternatíva.
⚠
PDF CSS támogatás A TCPDF egyszerűsített HTML értelmezőt használ; flexbox, grid, float nem renderelődik helyesen. Táblázat-alapú elrendezés ajánlott.
⚠
Szinkron futás A bővítmény szinkron módon fut az admin státuszváltásakor; lassú SMTP vagy nagy rendelések esetén az admin felület is lassabban reagálhat.
⚠
Multistore cégadatok A cégadatok (logó, bankszámlaszám stb.) globálisak; store-onként eltérő cégadatot jelenleg nem támogat.

12 Verziónapló

v1.0.0 2025 – Első kiadás

Szabályalapú PDF díjbekérő generálás
Automatikus email küldés PDF csatolmánnyal
TCPDF integráció (vendor/tcpdf/)
Verziókezelt PDF tárolás (YYYY/MM/)
Többnyelvű sablonok (hu-hu / en-gb)
Saját log az admin felületen
Admin értesítő email hiba esetén
Multistore kompatibilitás
Post-delivery státusz automatizálás
Bővíthető ActionInterface architektúra
InnoDB tranzakciós verziókezelés
Path traversal védelem (logó)
GTM/OCM JavaScript eltávolítás PDF-ből
PHP 7.4 – 8.2 kompatibilitás

PDF Email Manager v1.0.0 · OpenCart 3.x · PHP 7.4–8.2