omaralalwi / gpdf
Custom PDF wrapper supporting Arabic language
Installs: 778
Dependents: 0
Suggesters: 0
Security: 0
Stars: 106
Watchers: 1
Forks: 8
Open Issues: 1
Requires
- php: ^8.1|^8.2|^8.3
- aws/aws-sdk-php: ^3.308
- dompdf/dompdf: ^3.0
- khaled.alshamaa/ar-php: ^6.3
Requires (Dev)
- phpunit/phpunit: ^9.3
This package is auto-updated.
Last update: 2025-03-16 02:50:52 UTC
README
GPDF is a PHP/Laravel package for generating Arabic, RTL, and multilingual PDFs with native support for 17 built-in Arabic fonts, S3 cloud storage, and enterprise-ready features. Built as a DomPDF extension, it solves Arabic rendering issues while adding modern capabilities for documents, invoices, and reports.
Table of Contents
- Requirements
- Installation
- Important Note
- Publish Resources
- Publish Config
- Usage with Laravel
- Usage with Native PHP Apps
- Supported Fonts
- Install Custom Fonts
- Features
- Thanks
- Testing
- Changelog
- Contributors
- Security
- Credits
- License
Requirements
- PHP version 8.1 or higher
- DOM extension
- MBString extension
- php-font-lib
- php-svg-lib
Installation
composer require omaralalwi/gpdf
IMPORTANT NOTE:
if you have old version with some issues, please Do following :-
- delete old config file.
- delete package from composer file.
- re-install package.
- publish config file again.
- then delete config cache.
Publish Resources
After installation, publish the config and fonts resources by running the following commands in the root project path:
php vendor/omaralalwi/gpdf/scripts/publish_fonts.php
Publish Config File
php vendor/omaralalwi/gpdf/scripts/publish_config.php
Note for Publish Issues: If you encounter any issues while publishing, manually copy the vendor/omaralalwi/gpdf/assets/fonts
folder to public/vendor/gpdf
and ensure the fonts are in public/vendor/gpdf/fonts
. Also, copy vendor/omaralalwi/gpdf/config/gpdf.php
to the /config
folder in the root path.
Usage with Laravel
Using the Gpdf Facade
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']); }
Using Dependency Injection
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']); }
Stream Generated PDF Files
Stream a PDF directly to the browser using generateWithStream
:
// by default it store files to local driver (path should in public path). 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']); }
Storing Generated PDF Files
Store Files To local
Save a PDF to storage using generateWithStore
:
Note By default it store files to local driver (ensure that: the store path is access able for read and write).
please see generateWithStore params .
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); // ssl verify should be true in production . return $file['ObjectURL']; // return file url as string , to store in db or do any action } // may be you will face problems with stream in local, so you can disable ssl verify in local, but should enable it in production.
Store Files To S3
same to store in local, just replace local path with bucket name, and replace generateWithStore
with generateWithStoreToS3
.
Note Ensure you setup s3 configs in config file.
public function generateAndStoreToS3() { $data = $this->getDynamicParams(); $html = view('pdf.example-2',$data)->render(); $gpdf = app(Gpdf::class); $bucketName = 'your_s3_bucket_name'; // should be read abel and write able . $file = $gpdf->generateWithStoreToS3($html, $bucketName, 'test-store-pdf-fle', true, true); // with s36 the ssl verify will work in local or production (always secure). return $file['ObjectURL']; // return file url as string , to store in db or do any action }
Generate Advance With Fixed Header
please see this example if you need to add fixed header to all pages
Demo Laravel App
this Demo Laravel app contain more detailed examples and cases.
Usage with Native PHP Apps
After installing the package and publishing resources, include autoload.php
and use the Gpdf
class.
Basic Usage
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;
Note: Customize the settings file as needed.
Stream Generated PDF Files
Stream a PDF directly to the browser using 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;
Store Files To Local
Save a PDF files to local storage using generateWithStore
:
Note By default it store files to local driver.
<?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 must be true in production $fileUrl = $file['ObjectURL']; return $fileUrl; // get file url as string to store it in db or do any action
generateWithStore params
Parameter | Type | Description |
---|---|---|
html file |
string | The HTML content to be stored. |
store path or bucket name with s3 |
string | The path where the file will be stored, with S3 store this should bucket name. |
file name |
string | The name of the file. |
with stream |
bool | If you need to stream the file to the browser after storing, set this to true . |
sslVerify |
bool | If with stream is set to true , you should set this to true in production to verify SSL. |
Store Files To S3
same to store in local, just replace local path with bucket name, and replace generateWithStore
with 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'];
Demo Native PHP App
please see this Demo Native PHP app contain more detailed examples and cases like pass dynamic parameters for html file & pass inline configs , .. and another cases.
Supported Fonts
Gpdf supports the following installed fonts (ready to use without any additional configurations):
Support for Arabic
Gpdf supports Arabic content out-of-the-box. Simply pass Arabic text within your HTML content. Make sure to use Arabic fonts, which are included by default.
Supported Arabic Fonts
The following built-in fonts support Arabic:
DejaVu Sans Mono
, Tajawal
, Almarai
, Cairo
, Noto Naskh Arabic
, Markazi Text
.
We Recommended to Use font name from Omaralalwi\Gpdf\Enums\GpdfDefaultSupportedFonts
Enum class , like default font name
in config file .
Examples
Installing Custom Fonts
To install custom font, follow these steps:
- Ensure the default fonts are published to
public/vendor/gpdf/fonts
. - Prepare at least one font (Normal) for each family
(Normal, Bold, Italic, BoldItalic)
. - Copy the fonts to any path (not the default fonts path).
- The font family name must be enclosed in double quotes and written in lowercase.
- fonts names must be in kebab case with capitalize.
- Run install font script with the following command:
php vendor/omaralalwi/gpdf/scripts/install_font.php "family name" ./path_to_font/Font-Normal.ttf ./path_to_font/Font-Bold.ttf ./resources/fonts/Tajawal-Italic.ttf ./path_to_font/Font-BoldItalic.ttf
For example, to install the Tajawal
font family:
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
Features
- Compatibility with any Standard PHP application, Or framework.
- store pdf files to S3 or local storage directly.
- stream pdf files from urls (local or s3).
- Supports 17 fonts by default, including 7 that support Arabic.
- Allows for the installation of custom fonts.
- Provides easy integration with Laravel applications.
- Offers customizable options for PDF generation.
- Includes detailed documentation.
- provide demo applications for quick start-up Demo Native PHP App , Demo Laravel App .
- Unit Tests Includes unit tests.
Thanks
Testing
composer test
or
php run-tests.php
Changelog
See CHANGELOG for recent changes.
Contributors ✨
Thanks to these wonderful people for contributing to this project! 💖
Omar Al Alwi 🏆 Owner |
Abesse Smahi 💻 Contributor |
Want to contribute? Check out the contributing guidelines and submit a pull request! 🚀
Security
If you discover any security-related issues, please email omaralwi2010@gmail.com
.
Credits
License
The MIT License (MIT). See LICENSE for more information.
✨ GPDF Community ✨
Click the button bellow or join here to be part of our growing community!
📚 Helpful Open Source Packages & Projects
Packages
-
Lexi Translate simplify managing translations for multilingual Eloquent models with power of morph relationships and caching .
-
Gpdf Open Source HTML to PDF converter for PHP & Laravel Applications, supports Arabic content out-of-the-box and other languages.
-
laravel Taxify Laravel Taxify provides a set of helper functions and classes to simplify tax (VAT) calculations within Laravel applications.
-
laravel Deployer Streamlined Deployment for Laravel and Node.js apps, with Zero-Downtime and various environments and branches.
-
laravel Trash Cleaner clean logs and debug files for debugging packages.
-
laravel Time Craft simple trait and helper functions that allow you, Effortlessly manage date and time queries in Laravel apps.
-
PHP builders sample php traits to add ability to use builder design patterns with easy in PHP applications.
-
PhpPy - PHP Python Interact with python in PHP applications.
-
Laravel Py - Laravel Python interact with python in Laravel applications.
-
deepseek PHP client robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities .
-
deepseek laravel Laravel wrapper for Deepseek PHP client to seamless deepseek AI API integration with Laravel applications.
-
Qwen PHP client robust and community-driven PHP client library for seamless integration with the Qwen API .
-
Laravel qwen wrapper for qwen PHP client to seamless Alibaba qwen AI API integration with Laravel applications..
Dashboards
-
Laravel Startkit Laravel Admin Dashboard, Admin Template with Frontend Template, for scalable Laravel projects.
-
Kunafa Dashboard Vue A feature-rich Vue.js 3 dashboard template with multi-language support and full RTL/LTR bidirectional layout capabilities.
References
-
Clean Code Summary summarize and notes for books and practices about clean code.
-
SOLID Principles Summary summarize and notes for books about SOLID Principles.