README-AR.md

جي بي دي اف : مولد ملفات بي دي اف لتطبيقات بي اتش بي و لارافيل يدعم جميع اللغات واللغة العربية بشكل كامل

GPDF هي حزمة PHP/Laravel لإنشاء ملفات PDF متعددة اللغات مع دعم اللغة العربية والكتابة من اليمين إلى اليسار (RTL). تتضمن الحزمة دعمًا أصليًا لـ 17 خط عربي، وتخزين سحابي على S3، وميزات متقدمة تناسب احتياجات المؤسسات. تم تصميمها كامتداد لـ DomPDF لحل مشاكل عرض اللغة العربية مع إضافة إمكانيات حديثة لإنشاء الوثائق والفواتير والتقارير.

---

الفهرس

• المتطلبات
• التثبيت
• نشر الموارد
• الاستخدام مع Laravel
  • استخدام Facade الخاص بـ Gpdf
  • استخدام الحقن الاعتمادي
  • عرض ملفات PDF مباشرة
  • تخزين ملفات PDF
• الاستخدام مع تطبيقات PHP التقليدية
  • الاستخدام الأساسي
  • عرض ملفات PDF مباشرة
  • تخزين الملفات محلياً
  • تخزين الملفات على S3
• الخطوط المدعومة
  • الدعم للغة العربية
  • تثبيت خطوط جديدة
• تثبيت الخطوط المخصصة
• الميزات
• الشكر
• الاختبارات
• سجل التغييرات
• المساهمون
• الأمان
• الاعتمادات
• الترخيص

---

المتطلبات

• إصدار PHP 8.1 أو أعلى
• امتداد DOM
• امتداد MBString
• php-font-lib
• php-svg-lib

التثبيت

composer require omaralalwi/gpdf

نشر الموارد

بعد التثبيت، قم بنشر ملفات الإعدادات والخطوط بتنفيذ الأوامر التالية في جذر المشروع:

php vendor/omaralalwi/gpdf/scripts/publish_fonts.php

php vendor/omaralalwi/gpdf/scripts/publish_config.php

ملاحظة بخصوص مشاكل النشر: إذا واجهت أي مشاكل أثناء النشر، انسخ يدويًا مجلد vendor/omaralalwi/gpdf/assets/fonts إلى public/vendor/gpdf وتأكد من وجود الخطوط في public/vendor/gpdf/fonts. كما يجب نسخ vendor/omaralalwi/gpdf/config/gpdf.php إلى مجلد /config في جذر المشروع.

---

الاستخدام مع Laravel

استخدام Facade الخاص بـ Gpdf

use Omaralalwi\Gpdf\Facade\Gpdf as GpdfFacade;

public function generatePdf()
{
    $html = view('pdf.example-1')->render();
    $pdfContent = GpdfFacade::generate($html);
    return response($pdfContent, 200, ['Content-Type' => 'application/pdf']);
}

استخدام الحقن الاعتمادي

use Omaralalwi\Gpdf\Gpdf;

public function generateSecondWayPdf(Gpdf $gpdf)
{
    $html = view('pdf.example-2')->render();
    $pdfFile = $gpdf->generate($html);
    return response($pdfFile, 200, ['Content-Type' => 'application/pdf']);
}

عرض ملفات PDF مباشرة

لعرض ملف PDF مباشرة في المتصفح باستخدام generateWithStream:

// بشكل افتراضي، يتم تخزين الملفات محلياً (يجب أن يكون المسار ضمن public).
public function generateAndStream()
{
    $html = view('pdf.example-2')->render();
    $gpdf = app(Gpdf::class);
    $gpdf->generateWithStream($html, 'test-streamed-pdf', true);
    return response(null, 200, ['Content-Type' => 'application/pdf']);
}

تخزين ملفات PDF

تخزين الملفات محلياً

لحفظ ملف PDF على التخزين باستخدام generateWithStore:

ملاحظة: بشكل افتراضي، يتم تخزين الملفات محلياً (تأكد من أن مسار التخزين متاح للقراءة والكتابة).

يرجى مراجعة معايير generateWithStore.

public function generateAndStore()
{
    $html = view('pdf.example-2')->render();
    $gpdf = app(Gpdf::class);
    $storePath = storage_path('app/downloads/users/');
    $gpdf->generateWithStore($html, $storePath, 'test-stored-pdf-file', true, false); // يجب تفعيل sslVerify في بيئة الإنتاج.
    return $file['ObjectURL']; // يعيد عنوان URL للملف كسلسلة نصية لتخزينه أو استخدامه.
}
// قد تواجه مشاكل مع stream في البيئة المحلية، لذا يمكنك تعطيل sslVerify محليًا، مع ضرورة تفعيله في الإنتاج.

تخزين الملفات على S3

بنفس طريقة التخزين المحلي، فقط استبدل مسار التخزين المحلي باسم الدلو (bucket name)، واستبدل generateWithStore بـ generateWithStoreToS3.

ملاحظة: تأكد من إعداد تكوينات S3 في ملف الإعدادات.

public function generateAndStoreToS3()
{
    $data = $this->getDynamicParams();
    $html = view('pdf.example-2', $data)->render();
    $gpdf = app(Gpdf::class);
    $bucketName = 'your_s3_bucket_name'; // يجب أن يكون الدلو قابلًا للقراءة والكتابة.
    $file = $gpdf->generateWithStoreToS3($html, $bucketName, 'test-store-pdf-file', true, true); // مع S3 يتم تفعيل sslVerify دائمًا للأمان.
    return $file['ObjectURL']; // يعيد عنوان URL للملف كسلسلة نصية.
}

مثال لتوليد PDF مع رأس ثابت

يرجى مراجعة هذا المثال إذا كنت بحاجة لإضافة رأس ثابت لجميع الصفحات.

تطبيق Laravel توضيحي

يحتوي هذا التطبيق التوضيحي على أمثلة وحالات استخدام مفصلة.

---

الاستخدام مع تطبيقات PHP التقليدية

بعد تثبيت الحزمة ونشر الموارد، قم بتضمين autoload.php واستخدم فئة Gpdf.

الاستخدام الأساسي

require_once __DIR__ . '/vendor/autoload.php';

use Omaralalwi\Gpdf\Gpdf;
use Omaralalwi\Gpdf\GpdfConfig;

$htmlFile = __DIR__ . '/contents/example-1.html';
$content = file_get_contents($htmlFile);
$gpdfConfigFile = require_once 'config/gpdf.php';

$config = new GpdfConfig($gpdfConfigFile);
$gpdf = new Gpdf($config);
$pdfContent = $gpdf->generate($content);

header('Content-Type: application/pdf');
echo $pdfContent;

ملاحظة: قم بتخصيص ملف الإعدادات حسب الحاجة.

عرض ملفات PDF مباشرة

لعرض ملف PDF مباشرة باستخدام generateWithStream:

require_once __DIR__ . '/vendor/autoload.php';

use Omaralalwi\Gpdf\Gpdf;
use Omaralalwi\Gpdf\GpdfConfig;

$htmlFile = __DIR__ . '/contents/example-1.html';
$content = file_get_contents($htmlFile);

$gpdfConfigFile = require_once 'config/gpdf.php';
$config = new GpdfConfig($gpdfConfigFile);

$gpdf = new Gpdf($config);
$pdfContent = $gpdf->generateWithStream($content, 'demo-file-name', true);

header('Content-Type: application/pdf');
echo $pdfContent;

تخزين الملفات محلياً

لحفظ ملفات PDF على التخزين المحلي باستخدام generateWithStore:

ملاحظة: يتم تخزين الملفات محلياً بشكل افتراضي.

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Omaralalwi\Gpdf\Gpdf;
use Omaralalwi\Gpdf\GpdfConfig;
use Omaralalwi\Gpdf\Enums\{GpdfDefaultSettings, GpdfSettingKeys, GpdfDefaultSupportedFonts};

$htmlFile = __DIR__ . '/contents/example-1.html';
$content = file_get_contents($htmlFile);

$gpdfConfigFile = require_once ('config/gpdf.php');
$config = new GpdfConfig($gpdfConfigFile);

$gpdf = new Gpdf($config);
$sslVerify = false;
$file = $gpdf->generateWithStore($content, null, null, false, $sslVerify); // يجب تفعيل sslVerify في الإنتاج.
$fileUrl = $file['ObjectURL'];

return $fileUrl;  // يعيد عنوان URL للملف كسلسلة نصية لتخزينه أو استخدامه.

معايير generateWithStore

المعامل	النوع	الوصف
html file	string	المحتوى HTML الذي سيتم تحويله وتخزينه.
مسار التخزين أو اسم الدلو لـ S3	string	المسار الذي سيتم تخزين الملف فيه، ومع S3 يجب أن يكون اسم الدلو (bucket name).
اسم الملف	string	اسم الملف المراد حفظه.
with stream	bool	إذا كنت ترغب في عرض الملف مباشرة بعد التخزين، قم بتعيين القيمة إلى true.
sslVerify	bool	إذا تم تعيين with stream إلى true، يجب تعيين هذا إلى true في الإنتاج للتحقق من SSL.

تخزين الملفات على S3

بنفس طريقة التخزين المحلي، فقط استبدل مسار التخزين المحلي باسم الدلو، واستبدل generateWithStore بـ generateWithStoreToS3.

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Omaralalwi\Gpdf\Gpdf;
use Omaralalwi\Gpdf\GpdfConfig;
use Omaralalwi\Gpdf\Enums\{GpdfDefaultSettings, GpdfSettingKeys, GpdfDefaultSupportedFonts};

$htmlFile = __DIR__ . '/contents/example-1.html';
$content = file_get_contents($htmlFile);

$gpdfConfigFile = require_once ('config/gpdf.php');
$config = new GpdfConfig($gpdfConfigFile);

$gpdf = new Gpdf($config);
$fileName = "pdf-file-with-store-to-s3";
$sslVerify = true;
$file = $gpdf->generateWithStoreToS3($content, null, $fileName, true, $sslVerify);
$fileUrl = $file['ObjectURL'];

تطبيق PHP توضيحي

يمكنك مراجعة هذا التطبيق التوضيحي للحصول على أمثلة مفصلة حول تمرير المعاملات الديناميكية للملفات HTML وتمرير الإعدادات مدمجة وغيرها من الحالات.

---

الخطوط المدعومة

يدعم Gpdf الخطوط التالية المثبتة (جاهزة للاستخدام دون إعداد إضافي):

الخطوط المدعومة

الدعم للغة العربية

يدعم Gpdf المحتوى العربي بشكل افتراضي. قم بتمرير النصوص العربية ضمن محتوى HTML الخاص بك. تأكد من استخدام الخطوط العربية، حيث أنها مدمجة بشكل افتراضي.

الخطوط العربية المدعومة

تشمل الخطوط المدمجة التي تدعم اللغة العربية:

DejaVu Sans Mono، Tajawal، Almarai، Cairo، Noto Naskh Arabic، Markazi Text.

ننصح باستخدام اسم الخط من فئة Omaralalwi\Gpdf\Enums\GpdfDefaultSupportedFonts مثل "default font name" في ملف الإعدادات.

أمثلة

• مثال باستخدام PHP التقليدي
• مثال باستخدام Laravel

---

تثبيت الخطوط المخصصة

لتثبيت خط مخصص، اتبع الخطوات التالية:

1. تأكد من نشر الخطوط الافتراضية إلى public/vendor/gpdf/fonts.
2. جهز على الأقل خطًا (Normal) لكل نمط من الأنماط (Normal, Bold, Italic, BoldItalic).
3. انسخ الخطوط إلى أي مسار غير مسار الخطوط الافتراضي.
4. يجب أن يكون اسم عائلة الخط محاطًا بعلامات اقتباس مزدوجة ومكتوبًا بأحرف صغيرة.
5. يجب أن تكون أسماء الخطوط بصيغة kebab case مع كتابة أول حرف كبير.
6. شغّل سكربت تثبيت الخط باستخدام الأمر التالي:

php vendor/omaralalwi/gpdf/scripts/install_font.php "اسم العائلة" ./path_to_font/Font-Normal.ttf ./path_to_font/Font-Bold.ttf ./resources/fonts/Tajawal-Italic.ttf ./path_to_font/Font-BoldItalic.ttf

على سبيل المثال، لتثبيت عائلة خط Tajawal:

php vendor/omaralalwi/gpdf/scripts/install_font.php "tajawal" ./resources/fonts/Tajawal-Normal.ttf ./resources/fonts/Tajawal-Bold.ttf ./resources/fonts/Tajawal-Italic.ttf ./resources/fonts/Tajawal-BoldItalic.ttf

---

الميزات

• التوافق مع أي تطبيق PHP قياسي أو إطار عمل.
• إمكانية تخزين ملفات PDF على S3 أو على التخزين المحلي مباشرة.
• عرض ملفات PDF مباشرة من عناوين URL (محلي أو S3).
• دعم 17 خطاً بشكل افتراضي، بما في ذلك 7 خطوط تدعم اللغة العربية.
• إمكانية تثبيت الخطوط المخصصة.
• تكامل سهل مع تطبيقات Laravel.
• خيارات قابلة للتخصيص لتوليد ملفات PDF.
• وثائق مفصلة.
• تطبيقات توضيحية للبدء السريع: تطبيق PHP توضيحي و تطبيق Laravel توضيحي.
• يحتوي على اختبارات وحدية.

---

الشكر

• dompdf

• Ar-PHP

الاختبارات

composer test

أو

php run-tests.php

سجل التغييرات

راجع CHANGELOG لمعرفة التغييرات الأخيرة.

المساهمون ✨

شكر وتقدير لهؤلاء الرائعين الذين ساهموا في هذا المشروع! 💖

Omar Al Alwi 🏆 المالك

Abesse Smahi 💻 المساهم

هل ترغب في المساهمة؟ يرجى مراجعة إرشادات المساهمة وإرسال طلب سحب! 🚀

الأمان

إذا اكتشفت أي مشكلات تتعلق بالأمان، يرجى إرسال بريد إلكتروني إلى omaralwi2010@gmail.com.

الاعتمادات

• Omar Alalwi

الترخيص

رخصة MIT. راجع LICENSE لمزيد من المعلومات.

---