Skip to content

Commit 4db7a91

Browse files
DaanDeSmedtDaanDeSmedt
committed
Initial commit
Initial commit
1 parent 7533127 commit 4db7a91

33 files changed

+1729
-0
lines changed

‎README.md

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
PHPGhostscript
2+
===============
3+
4+
A PHP wrapper for [Ghostscript](https://www.ghostscript.com) ; an interpreter for PostScript™ and Portable Document Format (PDF) files.
5+
6+
Use `PHPGhostscript` for rendering PDF / PostScript™ files to various image types (jpeg / png) or export to PDF with page range (single page / multipage).
7+
Easy to use and OOP interfaced.
8+
9+
10+
## Installation
11+
12+
Install the package through [composer](http://getcomposer.org):
13+
14+
```
15+
composer require daandesmedt/phpghostscript
16+
```
17+
18+
Make sure, that you include the composer [autoloader](https://getcomposer.org/doc/01-basic-usage.md#autoloading) somewhere in your codebase.
19+
20+
21+
## Usage
22+
23+
Use `PHPGhostscript` for rendering PDF / PostScript™ files to various image types (jpeg / png) or export to PDF with page range (single page / multipage).
24+
25+
26+
## Working examples
27+
28+
Working examples can be found in the `examples` folder.
29+
30+
31+
## Supported devices
32+
33+
`PHPGhostscript` output devices implement `DeviceInterface`.
34+
35+
`PHPGhostscript` supports common output devices:
36+
37+
* **JPEG file format**
38+
* JPEG
39+
* JPEG Grey
40+
* **PNG file format**
41+
* PNG
42+
* PNG 16
43+
* PNG 256
44+
* PNG 16M
45+
* PNG Alpha
46+
* PNG Grey
47+
* PNG Mono
48+
* PNG MonoD
49+
* **PDF file format**
50+
51+
52+
53+
54+
## Specify a output device
55+
56+
Set output decive through `DeviceTypes` constant.
57+
58+
```php
59+
use daandesmedt\PHPGhostscript\Devices\DeviceTypes;
60+
use daandesmedt\PHPGhostscript\Devices\JPEG;
61+
62+
63+
$ghostscript = new Ghostscript();
64+
// JPEG
65+
$ghostscript->setDevice(DeviceTypes::JPEG);
66+
$ghostscript->setDevice(DeviceTypes::JPEG_GREY);
67+
// PNG
68+
$ghostscript->setDevice(DeviceTypes::PNG4);
69+
$ghostscript->setDevice(DeviceTypes::PNG_256);
70+
$ghostscript->setDevice(DeviceTypes::PNG_16M);
71+
$ghostscript->setDevice(DeviceTypes::PNG_ALPHA);
72+
$ghostscript->setDevice(DeviceTypes::PNG_GREY);
73+
$ghostscript->setDevice(DeviceTypes::PNG_MONO);
74+
$ghostscript->setDevice(DeviceTypes::PNG_MONO_D);
75+
// PDF
76+
$ghostscript->setDevice(DeviceTypes::PDF);
77+
```
78+
79+
OR set with instanceof `DeviceInterface`
80+
81+
```php
82+
// or create device
83+
$device = new JPEG();
84+
85+
// set device
86+
$ghostscript->setDevice($device);
87+
```
88+
89+
## Device specific parameters
90+
91+
92+
| Device output type | Function |
93+
| --- | --- |
94+
| JPEG / JPEG GREY | `setQuality(int $quality)` |
95+
| PNG ALPHA | `setBackgroundColor(string $color)` |
96+
| | `setDownScaleFactor(int $factor)` |
97+
| PNG MONO D | `setMinFeatureSize(int $size)` |
98+
| PNG 16M | `setDownScaleFactor(int $factor)` |
99+
100+
101+
Example :
102+
103+
```php
104+
// Create JPEG device
105+
$device = new JPEG();
106+
// set JPEG device specific quality
107+
$device->setQuality(100);
108+
```
109+
110+
## PDF (single page) / PostScript™ to Image
111+
112+
```php
113+
require __DIR__ . '/../vendor/autoload.php';
114+
115+
use daandesmedt\PHPGhostscript\Ghostscript;
116+
use daandesmedt\PHPGhostscript\Devices\JPEG;
117+
use daandesmedt\PHPGhostscript\Devices\DeviceTypes;
118+
use daandesmedt\PHPGhostscript\Devices\JPEGGrey;
119+
use daandesmedt\PHPGhostscript\Devices\PNG;
120+
121+
$ghostscript = new Ghostscript();
122+
$ghostscript
123+
// set Ghostscript binary path
124+
->setBinaryPath('C:\Program Files\gs\gs9.27\bin\gswin64.exe')
125+
126+
// set output device
127+
->setDevice(DeviceTypes::JPEG)
128+
129+
// set input & output file
130+
->setInputFile(__DIR__ . DIRECTORY_SEPARATOR . 'assets' . DIRECTORY_SEPARATOR . 'SinglePageHorizontal.pdf')
131+
->setOutputFile(__DIR__ . DIRECTORY_SEPARATOR . 'output' . DIRECTORY_SEPARATOR . 'SinglePageHorizontal.jpg');
132+
133+
// render
134+
if (true === $ghostscript->render()) {
135+
echo 'success';
136+
} else {
137+
echo 'error';
138+
}
139+
```
140+
141+
## Single output file per page
142+
143+
Export multi-page PDF files to seperate image files using the ``
144+
Specifying a single output file works fine for printing and rasterizing figures, but sometimes you want images of each page of a multi-page document. You can tell `PHPGhostscript` to put each page of the input file in a series of similarly named files. To do this place a template `%d` in the `setOutputFile` setter (`%d` will be replaced by the matching page number).
145+
146+
```php
147+
// file produce output files as : 'export-1.jpg', ... 'export-10.jpg', ...
148+
$ghostscript->setOutputFile(__DIR__ . DIRECTORY_SEPARATOR . 'output' . DIRECTORY_SEPARATOR . 'export-%01d.jpg');
149+
150+
// file produce output files as : 'export-001.jpg', ... 'export-010.jpg', ...
151+
$ghostscript->setOutputFile(__DIR__ . DIRECTORY_SEPARATOR . 'output' . DIRECTORY_SEPARATOR . 'export-%03d.jpg');
152+
```
153+
154+
155+
## Specify page range
156+
157+
```php
158+
$ghostscript->setPages(int $startPage, int $endPage);
159+
```
160+
161+
or set start and end explicitly
162+
163+
164+
```php
165+
$ghostscript->setPageStart(int $page);
166+
$ghostscript->setPageEnd(int $page);
167+
```
168+
169+
170+
## Subsample antialiasing
171+
172+
These options control the use of subsample antialiasing. Their use is highly recommended for producing high quality rasterizations of the input files.
173+
Use `Ghostscript::ANTIALIASING_HIGH` for optimum output, user `Ghostscript::ANTIALIASING_LOW` or `Ghostscript::ANTIALIASING_NONE` for faster rendering. Antialiasing can be set separately for text and graphics content, but only for image type output devices.
174+
175+
```php
176+
$ghostscript->setAntiAliasing(
177+
Ghostscript::ANTIALIASING_HIGH ||
178+
Ghostscript::ANTIALIASING_LOW ||
179+
Ghostscript::ANTIALIASING_NONE
180+
);
181+
```
182+
183+
or set text and graphics antialiasing explicitly
184+
185+
```php
186+
$ghostscript->setTextAntiAliasing(
187+
Ghostscript::ANTIALIASING_HIGH ||
188+
Ghostscript::ANTIALIASING_LOW ||
189+
Ghostscript::ANTIALIASING_NONE
190+
);
191+
192+
$ghostscript->setGraphicsAntiAliasing(
193+
Ghostscript::ANTIALIASING_HIGH ||
194+
Ghostscript::ANTIALIASING_LOW ||
195+
Ghostscript::ANTIALIASING_NONE
196+
);
197+
```
198+
199+
200+
## Output resolution
201+
202+
This option sets the resolution of the output file in dots per inch. The default value if you don't specify this options is 72 dpi. Support for specifying horizontal and vertical resolution.
203+
204+
```php
205+
$ghostscript->setResolution(int $hdpi, int $vdpi = null);
206+
```
207+
208+
209+
## Setting CIE Color
210+
211+
Set UseCIEColor in the page device dictionary, remapping device-dependent color values through a Postscript defined CIE color space. Document DeviceGray, DeviceRGB and DeviceCMYK source colors will be substituted respectively by Postscript CIEA, CIEABC and CIEDEFG color spaces. Only for image type output devices.
212+
213+
```php
214+
$ghostscript->setUseCie(bool $useCie);
215+
```
216+
217+
218+
## Setting page content region
219+
220+
Sets the page size to one of the following :
221+
222+
* **BleedBox** (``Ghostscript::BOX_BLEED``) : defines the region to which the contents of the page should be clipped when output in a production environment. This may include any extra bleed area needed to accommodate the physical limitations of cutting, folding, and trimming equipment. The actual printed page may include printing marks that fall outside the bleed box.
223+
* **TrimBox** (``Ghostscript::BOX_TRIM``) : defines the intended dimensions of the finished page after trimming. Some files have a TrimBox that is smaller than the MediaBox and may include white space, registration or cutting marks outside the CropBox. Using this option simulates appearance of the finished printed page.
224+
* **ArtBox** (``Ghostscript::BOX_ART``) : defines the extent of the page's meaningful content (including potential white space) as intended by the page's creator. The art box is likely to be the smallest box. It can be useful when one wants to crop the page as much as possible without losing the content.
225+
* **CropBox** (``Ghostscript::BOX_CROP``) : Unlike the other "page boundary" boxes, CropBox does not have a defined meaning, it simply provides a rectangle to which the page contents will be clipped (cropped). By convention, it is often, but not exclusively, used to aid the positioning of content on the (usually larger, in these cases) media.
226+
* **NONE** (``Ghostscript::BOX_NONE``)
227+
228+
```php
229+
$ghostscript->setBox(
230+
Ghostscript::BOX_BLEED,
231+
Ghostscript::BOX_TRIM,
232+
Ghostscript::BOX_ART,
233+
Ghostscript::BOX_CROP,
234+
Ghostscript::BOX_NONE
235+
);
236+
```
237+
238+
239+
## Handling exceptions
240+
241+
`PHPGhostscript` will throw following exceptions :
242+
243+
* `InvalidArgumentException` : thrown if an argument is not of the expected type.
244+
* `GhostscriptException` : thrown if Ghostscript was unable to transcode.
245+
246+
247+
```php
248+
$ghostscript = new Ghostscript();
249+
try {
250+
$ghostscript
251+
->setBinaryPath('C:\Program Files\gs\gs9.27\bin\gswin64.exe')
252+
->setDevice(DeviceTypes::JPEG)
253+
// Force excetion - invalid file ; supports only for PDF & PS
254+
->setInputFile(__DIR__ . DIRECTORY_SEPARATOR . 'assets' . DIRECTORY_SEPARATOR . 'invalidfile.docx')
255+
->setOutputFile(__DIR__ . DIRECTORY_SEPARATOR . 'output' . DIRECTORY_SEPARATOR . 'export.jpg');
256+
if (true === $ghostscript->render()) {
257+
echo 'success';
258+
} else {
259+
echo 'error';
260+
}
261+
} catch (InvalidArgumentException $e) {
262+
var_dump($e->getMessage());
263+
} catch (GhostscriptException $e) {
264+
var_dump($e->getMessage());
265+
}
266+
```

‎composer.json

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "daandesmedt/phpghostscript",
3+
"description": "A PHP wrapper for Ghostscript (An interpreter for the PostScript language and for PDF). Export PDF / PS to PDF or various image types (jpeg / png). Easy to use and OOP interfaced.",
4+
"type": "library",
5+
"license": "MIT",
6+
"keywords": ["HTML","ghostscript","wrapper","pdf","php","jpg","png","postscript"],
7+
"authors": [
8+
{
9+
"name": "Daan De Smedt",
10+
"email": "[email protected]"
11+
}
12+
],
13+
"minimum-stability": "stable",
14+
"autoload": {
15+
"psr-4": {
16+
"daandesmedt\\PHPGhostscript\\": "src/PHPGhostscript"
17+
}
18+
},
19+
"autoload-dev": {
20+
"psr-4": {
21+
"daandesmedt\\Tests\\PHPGhostscript\\": "tests/PHPGhostscript"
22+
}
23+
},
24+
"require-dev": {
25+
"phpunit/phpunit": "^8.3"
26+
},
27+
"require": {
28+
"php": ">= 7.0.0",
29+
"mikehaertl/php-shellcommand": "^1.2"
30+
}
31+
}

‎examples/ExceptionHandling.php

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<?php
2+
3+
require __DIR__ . '/../vendor/autoload.php';
4+
5+
use daandesmedt\PHPGhostscript\Ghostscript;
6+
use daandesmedt\PHPGhostscript\Devices\JPEG;
7+
use daandesmedt\PHPGhostscript\Devices\DeviceTypes;
8+
use daandesmedt\PHPGhostscript\Devices\JPEGGrey;
9+
use daandesmedt\PHPGhostscript\Devices\PNG;
10+
use daandesmedt\PHPGhostscript\GhostscriptException;
11+
12+
13+
$ghostscript = new Ghostscript();
14+
try {
15+
$ghostscript
16+
->setBinaryPath('C:\Program Files\gs\gs9.27\bin\gswin64.exe')
17+
->setDevice(DeviceTypes::JPEG)
18+
// Force excetion - invalid file ; supports only for PDF & PS
19+
->setInputFile(__DIR__ . DIRECTORY_SEPARATOR . 'assets' . DIRECTORY_SEPARATOR . 'invalidfile.docx')
20+
->setOutputFile(__DIR__ . DIRECTORY_SEPARATOR . 'output' . DIRECTORY_SEPARATOR . 'export.jpg');
21+
// render
22+
if (true === $ghostscript->render()) {
23+
echo 'success';
24+
} else {
25+
echo 'error';
26+
}
27+
} catch (InvalidArgumentException $e) {
28+
var_dump($e->getMessage());
29+
} catch (GhostscriptException $e) {
30+
var_dump($e->getMessage());
31+
}

0 commit comments

Comments
 (0)