abdal/phpian-render

Abdal Phpian Render is a comprehensive PHP package for fixing and improving the display of Persian texts in graphical environments. This package solves common text display issues in libraries such as GD Library, FPDF, and TCPDF, providing full Right-to-Left (RTL) support.

1.4.3 2026-01-03 07:05 UTC

Requires

• php: ^8.1
• symfony/polyfill-mbstring: ^1.28

Requires (Dev)

• phpunit/phpunit: ^10.0

GPL-2.0-or-later

• Ebrahim Shafiei

• TCPDF
• gd
• arabic
• fpdf
• persian
• rtl
• bidi
• text-rendering

README

English | فارسی

📖 درباره پروژه

پروژه Abdal Phpian Render یک پکیج جامع PHP برای اصلاح و بهبود نمایش متون فارسی در محیط‌های گرافیکی است. این پکیج مشکلات رایج نمایش متن در کتابخانه‌هایی مانند GD Library، FPDF و TCPDF را حل می‌کند و پشتیبانی کامل از راست‌به‌چپ (RTL) را فراهم می‌آورد.

🎯 چرا این نرم‌افزار ساخته شد؟

هنگام کار با متون فارسی در محیط‌های گرافیکی PHP، مشکلات متعددی وجود دارد:

• مشکل نمایش حروف: حروف فارسی به صورت جداگانه و بدون اتصال نمایش داده می‌شوند
• مشکل ترتیب نمایش: در متون ترکیبی (فارسی + انگلیسی) ترتیب کلمات به درستی نمایش داده نمی‌شود
• مشکل اعداد: اعداد انگلیسی در متن فارسی ظاهر می‌شوند
• مشکل علائم نگارشی: پرانتز، براکت و سایر علائم در جهت اشتباه نمایش داده می‌شوند
• از دست رفتن اعراب: اعراب فارسی در فرآیند پردازش از بین می‌روند

این پکیج تمام این مشکلات را حل می‌کند و یک راه‌حل کامل و استاندارد برای رندر متون RTL ارائه می‌دهد.

✨ ویژگی‌ها و قابلیت‌ها

🔤 الگوریتم Reshaping

• ✅ تبدیل حروف به اشکال چهارگانه (isolated, final, initial, medial)
• ✅ پشتیبانی کامل از حروف اختصاصی فارسی (پ، چ، گ، ژ)
• ✅ پشتیبانی از ترکیبات Lam-Alef فارسی (لا، لآ)
• ✅ حفظ اعراب در فرآیند reshaping

🔄 الگوریتم BiDi (Bidirectional)

• ✅ تشخیص خودکار ترتیب نمایش در متون ترکیبی (فارسی + انگلیسی)
• ✅ آینه‌سازی خودکار علائم نگارشی (پرانتز، براکت، آکولاد و...)
• ✅ مدیریت هوشمند علائم خنثی بر اساس context

🔢 تبدیل اعداد (Number Converter)

• ✅ تبدیل اعداد انگلیسی به فارسی
• ✅ تبدیل خودکار اعداد فارسی به انگلیسی (برای محاسبات)

🔣 مدیریت اعراب (Diacritics Handler)

• ✅ استخراج و حفظ اعراب (فَتحه، ضَمّه، کَسره، تنوین و...)
• ✅ اعمال مجدد اعراب پس از reshaping
• ✅ جلوگیری از از دست رفتن اعراب در فرآیند پردازش

🛠️ توابع کمکی (Helper Functions)

• ✅ wordWrap(): شکستن خط مخصوص متون RTL (جلوگیری از شکسته شدن ناقص کلمات)
• ✅ isRTL(): تشخیص خودکار زبان متن ورودی
• ✅ reverse(): معکوس کردن متن
• ✅ clean(): پاکسازی از کاراکترهای نامرئی و ناخواسته

📋 استانداردهای رعایت شده

• ✅ PSR-12: رعایت کامل استانداردهای کدنویسی PHP
• ✅ Type Hinting: استفاده کامل از type hints برای امنیت نوع داده
• ✅ PHP 8.1+: سازگاری کامل با نسخه‌های جدید PHP
• ✅ Lightweight: وابستگی سبک (فقط symfony/polyfill-mbstring)
• ✅ Unit Tests: تست‌های کامل با PHPUnit
• ✅ Clean Code: کد تمیز و قابل نگهداری

🚀 نصب و راه‌اندازی

نصب از طریق Composer

composer require abdal/phpian-render

یا اضافه کردن به composer.json:

{
    "require": {
        "abdal/phpian-render": "^1.4"
    }
}

📚 نحوه استفاده

استفاده پایه

<?php

require_once 'vendor/autoload.php';

use Abdal\PhpianRender\PhpianRender;

// ایجاد نمونه از کلاس اصلی
$renderer = new PhpianRender();

// پردازش ساده متن
$text = 'سلام دنیا';
$processed = $renderer->process($text);
echo $processed;

پردازش کامل با گزینه‌ها

<?php

use Abdal\PhpianRender\PhpianRender;

$renderer = new PhpianRender();

$text = 'عدد 123 در متن فارسی است';

// پردازش کامل با تمام ویژگی‌ها
$processed = $renderer->process($text, [
    'reshape' => true,              // فعال‌سازی reshaping
    'bidi' => true,                  // فعال‌سازی bidirectional
    'convertNumbers' => true,        // تبدیل اعداد
    'numberLocale' => 'persian',     // فقط 'persian' پشتیبانی می‌شود
    'preserveDiacritics' => true,    // حفظ اعراب
    'clean' => false,                // پاکسازی کاراکترهای نامرئی
]);

echo $processed; // خروجی: عدد ۱۲۳ در متن فارسی است

استفاده از Reshaping به تنهایی

<?php

use Abdal\PhpianRender\PhpianRender;

$renderer = new PhpianRender();

$text = 'سلام';
$reshaped = $renderer->reshape($text);
echo $reshaped; // حروف به صورت متصل نمایش داده می‌شوند

تبدیل اعداد

<?php

use Abdal\PhpianRender\PhpianRender;

$renderer = new PhpianRender();

// تبدیل به فارسی
$text = 'عدد 123 است';
$persian = $renderer->convertNumbers($text, 'persian');
echo $persian; // خروجی: عدد ۱۲۳ است

پردازش BiDi برای متون ترکیبی

<?php

use Abdal\PhpianRender\PhpianRender;

$renderer = new PhpianRender();

$text = 'سلام Hello World';
$bidi = $renderer->processBiDi($text);
echo $bidi; // ترتیب نمایش به درستی اصلاح می‌شود

شکستن خط (Word Wrap) برای RTL

<?php

use Abdal\PhpianRender\PhpianRender;

$renderer = new PhpianRender();

$text = 'این یک متن طولانی است که باید به چند خط تقسیم شود';
$wrapped = $renderer->wordWrap($text, 20); // حداکثر 20 کاراکتر در هر خط

echo $wrapped;
// خروجی:
// این یک متن طولانی است
// که باید به چند خط
// تقسیم شود

تشخیص RTL

<?php

use Abdal\PhpianRender\PhpianRender;

$renderer = new PhpianRender();

$text1 = 'سلام';
$text2 = 'Hello';

if ($renderer->isRTL($text1)) {
    echo 'متن RTL است';
}

if (!$renderer->isRTL($text2)) {
    echo 'متن LTR است';
}

استفاده از Static Methods (بدون نیاز به ایجاد نمونه)

<?php

use Abdal\PhpianRender\PhpianRender;

// استفاده از متدهای static بدون نیاز به ایجاد نمونه
$text = 'سلام دنیا';

// پردازش ساده
$processed = PhpianRender::processStatic($text);
echo $processed;

// پردازش کامل با تمام گزینه‌ها
$text = 'عدد 123 در متن فارسی است';
$processed = PhpianRender::processStatic($text, [
    'reshape' => true,              // فعال‌سازی reshaping
    'bidi' => true,                  // فعال‌سازی bidirectional
    'convertNumbers' => true,        // تبدیل اعداد
    'numberLocale' => 'persian',     // فقط 'persian' پشتیبانی می‌شود
    'preserveDiacritics' => true,    // حفظ اعراب
    'clean' => false,                // پاکسازی کاراکترهای نامرئی
    'reverse' => true,               // معکوس کردن متن برای نمایش RTL
]);
echo $processed; // خروجی: عدد ۱۲۳ در متن فارسی است

// Reshape
$reshaped = PhpianRender::reshapeStatic($text);

// تبدیل اعداد
$converted = PhpianRender::convertNumbersStatic('عدد 123', 'persian');

// تشخیص RTL
$isRTL = PhpianRender::isRTLStatic($text);

// Word Wrap
$wrapped = PhpianRender::wordWrapStatic('متن طولانی', 20);

// دریافت نسخه پکیج
$version = PhpianRender::getVersion();
echo "Version: $version";

استفاده از کلاس‌های مستقل

<?php

use Abdal\PhpianRender\Reshaper;
use Abdal\PhpianRender\BiDi;
use Abdal\PhpianRender\NumberConverter;
use Abdal\PhpianRender\Helper;

// استفاده مستقیم از Reshaper
$reshaper = new Reshaper();
$reshaped = $reshaper->reshape('سلام');

// استفاده مستقیم از BiDi
$bidi = new BiDi();
$processed = $bidi->process('سلام Hello');

// استفاده مستقیم از NumberConverter
$converter = new NumberConverter();
$persian = $converter->toPersian('123');

// استفاده مستقیم از Helper
$helper = new Helper();
$isRTL = $helper->isRTL('سلام');
$wrapped = $helper->wordWrap('متن طولانی', 10);

استفاده در GD Library

<?php

use Abdal\PhpianRender\PhpianRender;

$renderer = new PhpianRender();

// پردازش متن قبل از نمایش در تصویر
$text = 'سلام دنیا';
$processed = $renderer->process($text, [
    'reshape' => true,
    'bidi' => true,
    'convertNumbers' => true,
]);

// استفاده در GD
$image = imagecreate(400, 200);
$bg = imagecolorallocate($image, 255, 255, 255);
$textColor = imagecolorallocate($image, 0, 0, 0);

// استفاده از فونت فارسی
imagettftext($image, 20, 0, 10, 50, $textColor, 'font.ttf', $processed);

header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);

استفاده در FPDF/TCPDF

<?php

use Abdal\PhpianRender\PhpianRender;
require_once('fpdf.php'); // یا tcpdf.php

$renderer = new PhpianRender();
$pdf = new FPDF();

$pdf->AddPage();
$pdf->AddFont('DejaVu', '', 'DejaVuSans.ttf', true);

$text = 'سلام دنیا - عدد 123';
$processed = $renderer->process($text, [
    'reshape' => true,
    'bidi' => true,
    'convertNumbers' => true,
]);

$pdf->SetFont('DejaVu', '', 14);
$pdf->Cell(0, 10, $processed, 0, 1);

$pdf->Output();

🧪 تست‌ها

برای اجرای تست‌های واحد:

composer install
vendor/bin/phpunit

📦 وابستگی‌ها

• PHP >= 8.1
• symfony/polyfill-mbstring ^1.28

📄 مجوز

این پروژه تحت مجوز GPL-2.0-or-later منتشر شده است.

🐛 گزارش مشکلات

اگر با مشکلی مواجه شدید یا در پیکربندی مشکل دارید، لطفاً از طریق ایمیل [e-mail] با ما در تماس باشید. همچنین می‌توانید مشکلات را در GitLab یا GitHub گزارش دهید.

❤️ حمایت مالی

اگر این پروژه برای شما مفید بود و مایل به حمایت از توسعه بیشتر هستید، لطفاً در نظر داشته باشید که کمک مالی کنید:

• اینجا اهدا کنید

🤵 برنامه‌نویس

ساخته شده با عشق توسط ابراهیم شفیعی (EbraSha)

• ایمیل: [e-mail]
• تلگرام: @ProfShafiei
• GitHub: @ebrasha
• Twitter/X: @ProfShafiei
• LinkedIn: ProfShafiei

📜 مجوز

این پروژه تحت مجوز GPLv2 or later منتشر شده است.