آموزش فارسی سازی whmcs pdf
فارسیسازی PDF در WHMCS یک کار دو بخشی است: اول باید فونتی در دسترس WHMCS باشد که گلیف حروف فارسی را داشته باشد و همان فونت در تنظیمات فاکتور انتخاب شود، بعد قالب PDF راستچین شود. اگر فقط فایل فونت را کپی کنید و آن را به WHMCS معرفی نکنید، هیچ تغییری در خروجی نمیبینید؛ و اگر قالب فاکتور راستچین نشود، حروف فارسی جدا از هم و وارونه چاپ میشوند.
یک نکته را از ابتدا بدانید تا وقت هدر ندهید: ویرایش قالب PDF فقط روی نصبهای self-hosted ممکن است. مستندات رسمی WHMCS تصریح کرده که WHMCS Cloud در حال حاضر این روش سفارشیسازی قالب را پشتیبانی نمیکند.
نشانههای مشکل را دقیق تشخیص دهید
سه خرابی متفاوت وجود دارد که اغلب با هم اشتباه گرفته میشوند و راهحل هرکدام فرق میکند:
- مربع خالی یا فضای سفید بهجای متن فارسی: فونت انتخابشده اصلاً گلیف حروف فارسی را ندارد. مشکل از فونت است.
- علامت سؤال بهجای حروف: مستندات خود WHMCS این نشانه را هم به فونت نسبت میدهد، یعنی فونت فعلی آن کاراکترها را پوشش نمیدهد. پس اول فونت را عوض کنید و تنها اگر با فونت یونیکد هم برطرف نشد، سراغ کدگذاری دیتابیس یا فایل زبان بروید.
- حروف درست ولی جدا از هم مثل «س ل ا م» و چیدمان از چپ به راست: فونت سالم است اما حالت راستبهچپ و شکلدهی حروف در قالب PDF فعال نشده است.
قبل از هر کاری مشخص کنید با کدام حالت روبهرو هستید؛ وگرنه ساعتها فونت عوض میکنید بدون آنکه چیزی بهتر شود.
اول سادهترین راه را امتحان کنید
خیلیها بدون نیاز، مستقیم سراغ تبدیل فونت میروند. WHMCS از نسخه 7.7 به بعد فایلهای فونتهای جایگزین را بهصورت کامل همراه خودش میفرستد و مستندات رسمی، dejavusans را برای زبانهایی که کاراکتر خاص دارند (از جمله فارسی و عربی) و freesans را برای حالت علامت سؤال معرفی میکند. پس ابتدا به بخش Configuration و سپس System Settings و General Settings بروید، زبانه Invoices را باز کنید، مقدار PDF Font Family را یکییکی روی این دو بگذارید و هر بار یک فاکتور آزمایشی بگیرید.
اگر خروجی قابل قبول شد، کار تمام است و لازم نیست هیچ فایلی به سرور اضافه کنید. تنها دلیل رفتن به مرحله بعد این است که ظاهر این فونتها را برای فاکتور رسمی نمیپسندید؛ چون طراحی آنها فارسی نیست و فقط پوشش عربی دارند. اگر هنوز نسخه رسمی سامانه صورتحساب را تهیه نکردهاید، پیش از سفارشیسازی قالب تکلیف لایسنس WHMCS را روشن کنید؛ در جدول همان صفحه، نسخهها از نظر نمایش لینک و برند سازنده و مدت دریافت بهروزرسانی با هم فرق دارند و بهتر است پیش از سفارش همین دو سطر را برای نسخه موردنظرتان بخوانید.
چرا موتور PDF پیشفرض فارسی را خراب میکند
WHMCS برای ساخت فاکتور PDF از کتابخانه TCPDF استفاده میکند و خود مستندات رسمی هم همین را میگوید. فونتهای پایه این کتابخانه مثل helvetica و times فونتهای تکبایتی لاتین هستند و حرفی از الفبای فارسی در آنها وجود ندارد؛ به همین دلیل خروجی مربع خالی میشود.
نکته دوم شکلدهی حروف است. در خط فارسی هر حرف بسته به جایگاهش شکل متفاوتی دارد و ترتیب نمایش هم راستبهچپ است. TCPDF این پردازش را زمانی درست انجام میدهد که فونت بهصورت TrueTypeUnicode اضافه شده باشد و حالت RTL هم روشن باشد. اگر یکی از این دو نباشد، متن بهشکل حروف منفصل چاپ میشود.
فونت فارسی مناسب را انتخاب کنید
برای ظاهر حرفهای، یک فونت فارسی آزاد و مجاز برای جاسازی انتخاب کنید؛ خانواده Vazirmatn که با پروانه SIL OFL منتشر میشود نمونه رایج و بیدردسری است. یک هشدار حقوقی مهم هم هست: فونت داخل فایل PDF جاسازی میشود، پس پروانه آن باید اجازه embedding بدهد. فونتهای تجاری فارسی که بدون خرید پروانه در اینترنت پخش میشوند این اجازه را ندارند و استفاده از آنها روی فاکتور مشتری ریسک حقوقی دارد.
فونت را به قالب TCPDF تبدیل کنید
TCPDF فایل .ttf را مستقیم نمیخواند و به چند فایل جانبی نیاز دارد. اول مسیر پوشه فونتها را روی نصب خودتان پیدا کنید. در نسخههای امروزی WHMCS کتابخانه از طریق Composer نصب میشود و مسیر درست vendor/tecnickcom/tcpdf/fonts/ است؛ مسیر قدیمی includes/classes/TCPDF/fonts/ که در راهنماهای سالها پیش تکرار شده، روی نصبهای جدید معمولاً اصلاً وجود ندارد:
ls -d ~/public_html/vendor/tecnickcom/tcpdf/fonts ~/public_html/includes/classes/TCPDF/fonts 2>/dev/null
سپس یک اسکریپت کوتاه با نام addfont.php کنار فایل init.php بسازید:
<?php require __DIR__ . '/vendor/autoload.php'; echo TCPDF_FONTS::addTTFfont('/home/user/Vazirmatn-Regular.ttf', 'TrueTypeUnicode') . PHP_EOL;
اگر به خط فرمان دسترسی دارید با php addfont.php اجرایش کنید، وگرنه یک بار آدرس همان فایل را در مرورگر باز کنید. خروجی، نام کلید فونت را چاپ میکند و فایلهای .php و .z و .ctg.z در پوشه فونتها ساخته میشوند. همان رشتهای که چاپ شد را یادداشت کنید؛ در گام بعد دقیقاً به آن نیاز دارید. بلافاصله بعد از اتمام کار، اسکریپت را حذف کنید؛ رها کردن یک فایل PHP دلخواه در ریشه سایت خودش یک ضعف امنیتی است.
اگر خطای دسترسی گرفتید، پوشه فونت اجازه نوشتن ندارد. روی سرویسهای اشتراکی مثل هاست لینوکس ایران که با کنترلپنل cPanel ارائه میشود، میتوانید از فایلمنیجر کنترلپنل سطح دسترسی پوشه و فایلهای ساختهشده را تنظیم کنید؛ برای فایلهای فونت مقدار 644 کافی است. تغییر مالکیت فایلها از فایلمنیجر انجام نمیشود و روی هاست اشتراکی هم لازم نیست، چون همه فایلها با کاربر خود اکانت ساخته میشوند.
فونت را به WHMCS معرفی کنید
دوباره به Configuration و سپس System Settings و General Settings و زبانه Invoices بروید و مقدار PDF Font Family را روی همان کلیدی بگذارید که اسکریپت چاپ کرد. این کلید همیشه با حروف کوچک و بدون فاصله ساخته میشود و باید دقیقاً با نام فایل .php ساختهشده در پوشه فونتها یکی باشد. طبق مستندات، همین یک تنظیم فونت فاکتور و پیشفاکتور را با هم عوض میکند؛ پس لازم نیست نام فونت را جای دیگری تکرار کنید. اگر نام فونت جدید پذیرفته نشد یا خروجی تغییری نکرد، برگردید و مطمئن شوید هر سه فایل .php و .z و .ctg.z در پوشه فونتها ساخته شدهاند و برای وبسرور قابل خواندن هستند.
اگر روی یک سرویس نمایندگی هاست چند سامانه صورتحساب جدا برای برندهای مختلف اجرا میکنید، توجه کنید که این تنظیم و فایلهای فونت برای هر نصب مستقل است و باید روی هر کدام جداگانه انجام شود.
راستچین کردن خروجی
معرفی فونت فقط مشکل گلیف را حل میکند. برای چیدمان درست باید قالب invoicepdf.tpl را ویرایش کنید. این فایل داخل پوشه قالب سیستمی فعال قرار دارد، نه مستقیماً در ریشه templates/؛ اول محل واقعی آن را پیدا کنید:
ls ~/public_html/templates/*/invoicepdf.tpl
پیش از ویرایش، پوشه قالب سیستمی را با نام دیگری کپی کنید و همان نسخه کپی را در تنظیمات قالب فعال کنید؛ اینطور بهروزرسانی بعدی WHMCS تغییرات شما را بازنویسی نمیکند. حالا در ابتدای فایل و پیش از نوشتن محتوا، حالت راستبهچپ را روشن کنید:
$pdf->setRTL(true);
$pdf->setLanguageArray(array('a_meta_charset' => 'UTF-8', 'a_meta_dir' => 'rtl', 'a_meta_language' => 'fa'));
یک تصور غلط رایج را همینجا کنار بگذارید: قالب پیشفرض WHMCS نام فونت را هیچجا مستقیم ننوشته و همه فراخوانیهای SetFont در این فایل از متغیر $pdfFont استفاده میکنند که مقدارش از همان تنظیم PDF Font Family میآید. پس اگر قالب را دستنخورده تحویل گرفتهاید، لازم نیست این خطوط را لمس کنید؛ فقط وقتی باید نام فونت را جایگزین کنید که یک قالب سفارشی یا افزونه جانبی، نام فونت را بهصورت ثابت داخل کد نوشته باشد. اگر سرصفحه یا پاصفحه سفارشی هم دارید، فایلهای invoicepdfheader.tpl و invoicepdffooter.tpl کنار همین قالب را فراموش نکنید.
یک فایل دیگر هم در همان پوشه هست که تقریباً همیشه جا میماند: quotepdf.tpl که خروجی PDF پیشفاکتور را میسازد. تنظیم فونت روی این فایل هم اثر میگذارد، اما همان دو خط راستچینسازی را باید جداگانه در آن هم اضافه کنید؛ وگرنه پیشفاکتورهای شما همچنان خراب چاپ میشوند. سرصفحه و پاصفحه اختصاصی پیشفاکتور هم فایلهای جدای خودشان یعنی quotepdfheader.tpl و quotepdffooter.tpl را دارند. برای متن ثابت فاکتور هم با ls lang/ بررسی کنید فایل زبان فارسی روی نصب شما موجود و کامل باشد.
تست انتها به انتها
یک مشتری آزمایشی با نام و نشانی فارسی بسازید، برایش فاکتور صادر کنید و خروجی PDF را هم از ناحیه مدیریت و هم از ناحیه کاربری دانلود کنید. این دو مسیر همیشه یک نتیجه نمیدهند. مسیر سومی هم هست که اغلب از قلم میافتد: فایل PDF که بهصورت پیوست ایمیل فاکتور برای مشتری فرستاده میشود. این پیوست را هم یک بار در یک صندوق ایمیل واقعی باز کنید و اگر پیشفاکتور هم صادر میکنید، یک نمونه از آن را جداگانه تست کنید. سپس روی فایل دانلودشده اجرا کنید:
pdffonts invoice.pdf
این ابزار که همراه بسته poppler-utils نصب میشود، فهرست فونتهای بهکاررفته را نشان میدهد. نام فونت فارسی باید در فهرست باشد و ستون emb برای آن yes نشان دهد. اگر فونت جاسازی نشده باشد، فاکتور روی رایانه شما درست دیده میشود ولی روی دستگاه مشتری خراب است؛ همین یک بررسی ساده جلوی بیشتر شکایتها را میگیرد.
یک تست تکمیلی هم ارزش دارد: متن فارسی فاکتور را در یک نمایشگر PDF انتخاب و کپی کنید. اگر حروف درست دربیایند، یعنی نگاشت کاراکترها سالم است و فاکتور شما برای بایگانی و جستجو هم قابل استفاده است.
پیشگیری از برگشت مشکل
پوشه فونتهای TCPDF زیر vendor/ است و در مسیر بهروزرسانی WHMCS قرار دارد. پیش از هر ارتقا از فونتها و قالب سفارشی خود نسخه پشتیبان بگیرید و بعد از ارتقا یک فاکتور آزمایشی بگیرید. تغییرات را هم جایی مستند کنید تا نفر بعدی از صفر شروع نکند. اگر پروانههای دیگری مثل لایسنس cPanel را هم در کنار WHMCS تمدید میکنید، بررسی سلامت فاکتور فارسی را به همان چکلیست دورهای اضافه کنید.
در پایان: راهکار سالهای دور که فقط یک فایل فونت آماده را در مسیر قدیمی includes/classes/TCPDF/fonts/ میریخت، امروز نه لازم است و نه قابل اتکا. اول فونتهای خود WHMCS را امتحان کنید و اگر ظاهرشان کافی نبود، فونت دلخواه را روی همان سروری که WHMCS اجرا میشود تبدیل کنید؛ اینطور هم نسخه فونت را خودتان کنترل میکنید و هم بعد از هر ارتقا میدانید دقیقاً چه چیزی را باید دوباره جای خود بگذارید.