Skip to content

Commit df41537

Browse files
imalhasarangaimalhasaranga
committed
updating documentation
1 parent 413d214 commit df41537

3 files changed

Lines changed: 105 additions & 43 deletions

File tree

‎.phpunit.result.cache‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{"version":2,"defects":{"PDFLibAdvancedTest::testMetadata":8,"PDFLibAdvancedTest::testRotate":8,"PDFLibAdvancedTest::testSplit":8,"PDFLibAdvancedTest::testSplitRange":8,"PDFLibAdvancedTest::testEncrypt":8,"PDFLibAdvancedTest::testThumbnail":8,"PDFLibAdvancedTest::testWatermark":8,"PDFLibAdvancedTest::testFlatten":8,"PDFLibAdvancedTest::testPDFA":2,"PDFLibTest::testPageCount":8,"PDFLibTest::testConvert":8,"PDFLibTest::testConvertWithChaining":8,"PDFLibTest::testMerge":8},"times":{"PDFLibAdvancedTest::testSplit":0.167,"PDFLibAdvancedTest::testSplitRange":0.128,"PDFLibAdvancedTest::testEncrypt":0.286,"PDFLibAdvancedTest::testThumbnail":0.061,"PDFLibAdvancedTest::testWatermark":0.277,"PDFLibAdvancedTest::testMetadata":0.272,"PDFLibAdvancedTest::testRotate":0.265,"PDFLibAdvancedTest::testFlatten":0.273,"PDFLibAdvancedTest::testPDFA":0.009,"PDFLibTest::testPageCount":0.043,"PDFLibTest::testConvert":0.358,"PDFLibTest::testConvertWithChaining":1.382,"PDFLibTest::testMerge":0.49,"ChromeDriverTest::testConvertFromHtml":1.338,"ChromeDriverTest::testFacadeIntegration":1.062,"OpenSslDriverTest::testSignPdfDirectly":0.047,"OpenSslDriverTest::testFacadeIntegration":0.005}}
1+
{"version":2,"defects":{"PDFLibAdvancedTest::testMetadata":8,"PDFLibAdvancedTest::testRotate":8,"PDFLibAdvancedTest::testSplit":8,"PDFLibAdvancedTest::testSplitRange":8,"PDFLibAdvancedTest::testEncrypt":8,"PDFLibAdvancedTest::testThumbnail":8,"PDFLibAdvancedTest::testWatermark":8,"PDFLibAdvancedTest::testFlatten":8,"PDFLibAdvancedTest::testPDFA":2,"PDFLibTest::testPageCount":8,"PDFLibTest::testConvert":8,"PDFLibTest::testConvertWithChaining":8,"PDFLibTest::testMerge":8,"Tests\\ValidationDriverTest::test_validate_valid_signature":1,"Tests\\ValidationDriverTest::test_validate_unsigned_pdf":1,"Tests\\ValidationDriverTest::test_throws_exception_if_pdfsig_missing":1,"Tests\\OCRTest::test_ocr_extraction":7,"Tests\\OCRTest::test_throws_exception_if_tesseract_missing":1,"Tests\\RedactionTest::test_redaction_applies_if_text_found":1,"Tests\\MetadataExtractionTest::test_ghostscript_metadata_extraction":1,"Tests\\MetadataExtractionTest::test_pdftk_metadata_extraction":1,"Tests\\LaravelWrapperTest::test_service_provider_instantiatable_if_laravel_present":1},"times":{"PDFLibAdvancedTest::testSplit":0.186,"PDFLibAdvancedTest::testSplitRange":0.203,"PDFLibAdvancedTest::testEncrypt":0.344,"PDFLibAdvancedTest::testThumbnail":0.097,"PDFLibAdvancedTest::testWatermark":0.405,"PDFLibAdvancedTest::testMetadata":0.346,"PDFLibAdvancedTest::testRotate":0.392,"PDFLibAdvancedTest::testFlatten":0.279,"PDFLibAdvancedTest::testPDFA":0.009,"PDFLibTest::testPageCount":0.074,"PDFLibTest::testConvert":0.486,"PDFLibTest::testConvertWithChaining":1.701,"PDFLibTest::testMerge":0.592,"ChromeDriverTest::testConvertFromHtml":1.399,"ChromeDriverTest::testFacadeIntegration":0.86,"OpenSslDriverTest::testSignPdfDirectly":0.006,"OpenSslDriverTest::testFacadeIntegration":0.005,"Tests\\StatefulChainingTest::test_stateful_chaining_execution":0.372,"Tests\\StatefulChainingTest::test_legacy_execution_still_works":0.15,"Tests\\ValidationDriverTest::test_validate_valid_signature":0,"Tests\\ValidationDriverTest::test_validate_unsigned_pdf":0,"Tests\\ValidationDriverTest::test_throws_exception_if_pdfsig_missing":0,"Tests\\OCRTest::test_ocr_extraction":1.529,"Tests\\OCRTest::test_throws_exception_if_tesseract_missing":0,"Tests\\RedactionTest::test_redaction_applies_if_text_found":0,"Tests\\RedactionTest::test_throws_exception_if_pdftotext_missing":0.005,"Tests\\MetadataExtractionTest::test_ghostscript_metadata_extraction":0.001,"Tests\\MetadataExtractionTest::test_pdftk_metadata_extraction":0,"Tests\\LaravelWrapperTest::test_files_exist":0,"Tests\\LaravelWrapperTest::test_service_provider_instantiatable_if_laravel_present":0.002}}

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ The v3.1 architecture introduces a strict separation between the API (Facade) an
4242
* **Google Chrome** or **Chromium** (for HTML to PDF)
4343
* **pdftk** (PDF Toolkit) (for Form Filling)
4444

45+
👉 **[See Installation Guide](docs/installation.md)** for detailed setup instructions on macOS, Ubuntu, and Windows.
46+
4547
## 🔧 Installation
4648

4749
```bash

‎docs/installation.md‎

Lines changed: 102 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,132 @@
1-
# Installation
1+
# Comprehensive Installation Guide
22

3-
## Requirements
3+
This guide details how to install the necessary system dependencies for PDFLib v3.1 on **macOS**, **Ubuntu/Debian**, and **Windows**.
44

5-
* **PHP**: 8.1 or higher
6-
* **Composer**
5+
## 1. PHP & Extensions
76

8-
### Driver Dependencies
9-
PDFLib acts as a bridge to powerful system binaries. You only need to install the tools for the features you intend to use.
7+
**Requirement**: PHP >= 8.1
108

11-
| feature | Driver | Requirement |
12-
| :--- | :--- | :--- |
13-
| **Manipulation** (Merge, Split, Convert) | `GhostscriptDriver` | **Ghostscript** (v9.16+) |
14-
| **HTML to PDF** | `ChromeHeadlessDriver` | **Google Chrome** or **Chromium** |
15-
| **Digital Signatures** | `OpenSslDriver` | **PHP OpenSSL** & `tecnickcom/tcpdf` |
16-
| **Form Filling** | `PdftkDriver` | **pdftk** (PDF Toolkit) |
9+
### macOS (Homebrew)
10+
```bash
11+
brew install php
12+
```
13+
14+
### Ubuntu / Debian
15+
```bash
16+
sudo apt update
17+
sudo apt install php8.1 php8.1-cli php8.1-mbstring php8.1-xml php8.1-zip
18+
```
19+
20+
### Windows
21+
1. Download the **Non-Thread Safe (NTS)** version from [windows.php.net](https://windows.php.net/download/).
22+
2. Extract to `C:\php`.
23+
3. Add `C:\php` to your System PATH environment variable.
1724

1825
---
1926

20-
## 1. Install via Composer
27+
## 2. Driver Dependencies
2128

22-
```bash
23-
composer require imal-h/pdf-box
24-
```
29+
You only need to install the tools for the drivers you intend to use.
2530

26-
## 2. Install System Binaries
31+
| Feature | Driver | Requirement |
32+
| :--- | :--- | :--- |
33+
| **Manipulation** | `GhostscriptDriver` | [Ghostscript](#21-ghostscript) |
34+
| **HTML to PDF** | `ChromeHeadlessDriver` | [Google Chrome](#22-google-chrome--chromium) |
35+
| **Form Filling** | `PdftkDriver` | [PDFtk](#23-pdftk-server) |
36+
| **OCR** | `TesseractDriver` | [Tesseract](#24-tesseract-ocr) |
37+
| **Signatures** | `OpenSslDriver` | OpenSSL (Built-in to PHP) |
2738

28-
### macOS (Homebrew)
39+
### 2.1 Ghostscript
40+
*Required for: Merge, Split, Convert, Compress, Flatten, Redact.*
41+
42+
**Version**: 9.16 or higher
43+
44+
#### macOS
2945
```bash
30-
# Ghostscript
3146
brew install ghostscript
47+
```
48+
49+
#### Ubuntu / Debian
50+
```bash
51+
sudo apt install ghostscript
52+
```
53+
54+
#### Windows
55+
1. Download `Ghostscript AGPL Release` from [ghostscript.com](https://www.ghostscript.com/releases/gsdnld.html).
56+
2. Install the package.
57+
3. **Critical**: Add the `bin` and `lib` folders to your PATH (e.g., `C:\Program Files\gs\gs9.55.0\bin`).
58+
4. PDFLib looks for `gswin64c.exe` automatically.
59+
60+
---
61+
62+
### 2.2 Google Chrome / Chromium
63+
*Required for: HTML to PDF conversion.*
3264

33-
# Chrome (usually already installed, or install Chromium)
65+
#### macOS
66+
```bash
3467
brew install --cask google-chrome
68+
# OR
69+
brew install chromium
70+
```
71+
72+
#### Ubuntu / Debian
73+
```bash
74+
# Install stable Chrome
75+
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
76+
sudo apt install ./google-chrome-stable_current_amd64.deb
77+
```
3578

36-
# PDFtk
79+
#### Windows
80+
Standard installation of Google Chrome is sufficient. PDFLib will auto-detect it in standard `Program Files` locations.
81+
82+
---
83+
84+
### 2.3 PDFtk Server
85+
*Required for: Form Filling and Inspection.*
86+
87+
#### macOS
88+
```bash
3789
brew install pdftk-java
3890
```
3991

40-
### Ubuntu / Debian
92+
#### Ubuntu / Debian
4193
```bash
42-
# Ghostscript
43-
sudo apt-get update
44-
sudo apt-get install ghostscript
94+
sudo apt install pdftk
95+
```
4596

46-
# Chrome (install stable)
47-
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
48-
sudo apt install ./google-chrome-stable_current_amd64.deb
97+
#### Windows
98+
1. Download **PDFtk Server** from [pdflabs.com](https://www.pdflabs.com/tools/pdftk-server/).
99+
2. Run the installer.
100+
3. Ensure "Add application to your system path" is checked during installation.
101+
102+
---
103+
104+
### 2.4 Tesseract OCR
105+
*Required for: Text Extraction (OCR).*
49106

50-
# PDFtk
51-
sudo apt-get install pdftk
107+
#### macOS
108+
```bash
109+
brew install tesseract
52110
```
53111

54-
### Windows
55-
* **Ghostscript**: Download installer from [ghostscript.com](https://www.ghostscript.com/download.html). Add `gswin64c.exe` to your PATH.
56-
* **Chrome**: Standard installation.
57-
* **PDFtk**: Download from [pdflabs.com](https://www.pdflabs.com/tools/pdftk-server/).
112+
#### Ubuntu / Debian
113+
```bash
114+
sudo apt install tesseract-ocr
115+
```
116+
117+
#### Windows
118+
1. Download the installer from the [UB-Mannheim Tesseract Wiki](https://github.com/UB-Mannheim/tesseract/wiki).
119+
2. Install and add the install directory to your PATH.
58120

59121
---
60122

61-
## 3. Configuration
123+
## 3. Configuration (Optional)
62124

63-
By default, PDFLib attempts to autodetect binaries in common paths. If your environment uses custom paths, pass them to the Driver constructor.
125+
PDFLib tries to find these binaries automatically. If you have installed them in non-standard locations, you can explicitly configure paths in `config/pdflib.php` (for Laravel) or pass them to the Driver.
64126

65127
```php
66-
use ImalH\PDFLib\Drivers\GhostscriptDriver;
67-
use ImalH\PDFLib\PDF;
68-
69-
// Custom Path Example
70-
$driver = new GhostscriptDriver('/custom/path/to/gs');
71-
$pdf = new PDF($driver);
128+
// Manual Driver Configuration
129+
$driver = new \ImalH\PDFLib\Drivers\GhostscriptDriver(
130+
binaryPath: '/custom/path/to/gs'
131+
);
72132
```

0 commit comments

Comments
 (0)