Skip to content

Commit 479d83d

Browse files
qroquesqroques
committed
doc: update readme
1 parent 1562bed commit 479d83d

1 file changed

Lines changed: 228 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 228 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,29 +14,251 @@
1414

1515
## About Snappy
1616

17-
Snappy is a PHP library that allows you to generate PDF files from HTML.
17+
Snappy is a PHP library that allows you to generate PDF files from HTML by leveraging different backends such as Dompdf, WkHtmlToPdf, or Chrome Headless.
1818

1919
## Table of contents
2020

2121
- [Installation](#installation)
22+
- [Quick Start](#quick-start)
2223
- [Usage](#usage)
23-
- [Examples of use](#examples-of-use)
24+
- [Frontends](#frontends)
25+
- [Options](#options)
26+
- [Symfony Bundle Configuration](#symfony-bundle-configuration)
27+
- [Creating Custom Adapters](#creating-custom-adapters)
28+
- [Chrome Headless Notes](#chrome-headless-notes)
2429
- [Bugs and Support](#bugs-and-support)
2530
- [License](#license)
2631
- [Contributing](#contributing)
2732
- [Contributors](#contributors)
2833

2934
## Installation
3035

31-
`TO BE DEFINED`
36+
Install the core library:
37+
38+
```bash
39+
composer require knplabs/snappy
40+
```
41+
42+
Then install the adapter for your preferred backend:
43+
44+
```bash
45+
# For Dompdf
46+
composer require dompdf/dompdf
47+
48+
# For WkHtmlToPdf (requires wkhtmltopdf binary)
49+
# No additional package needed, but binary must be installed on your system.
50+
51+
# For Chrome Headless (requires google-chrome binary)
52+
# No additional package needed, but binary must be installed on your system.
53+
```
54+
55+
## Quick Start
56+
57+
### Using Dompdf
58+
59+
```php
60+
use KNPLabs\Snappy\Backend\Dompdf\DompdfAdapter;
61+
use KNPLabs\Snappy\Backend\Dompdf\DompdfFactory;
62+
use KNPLabs\Snappy\Core\Backend\Options;
63+
use KNPLabs\Snappy\Core\Frontend\HtmlToPdf;
64+
65+
$factory = new DompdfFactory($streamFactory);
66+
$adapter = $factory->create(Options::create());
67+
$frontend = new HtmlToPdf($adapter, $streamFactory);
68+
69+
$pdf = $frontend->generateFromHtml('<h1>Hello World</h1>');
70+
```
71+
72+
### Using WkHtmlToPdf
73+
74+
```php
75+
use KNPLabs\Snappy\Backend\WkHtmlToPdf\WkHtmlToPdfFactory;
76+
use KNPLabs\Snappy\Core\Backend\Options;
77+
use KNPLabs\Snappy\Core\Frontend\HtmlToPdf;
78+
79+
$factory = new WkHtmlToPdfFactory('/usr/local/bin/wkhtmltopdf', 60, $streamFactory, $uriFactory);
80+
$adapter = $factory->create(Options::create());
81+
$frontend = new HtmlToPdf($adapter, $streamFactory);
82+
83+
$pdf = $frontend->generateFromHtml('<h1>Hello World</h1>');
84+
```
85+
86+
### Using Chrome Headless
87+
88+
```php
89+
use KNPLabs\Snappy\Backend\ChromeHeadless\ChromeHeadlessFactory;
90+
use KNPLabs\Snappy\Core\Backend\Options;
91+
use KNPLabs\Snappy\Core\Frontend\HtmlToPdf;
92+
93+
$factory = new ChromeHeadlessFactory('google-chrome', 60, $streamFactory, $uriFactory);
94+
$adapter = $factory->create(Options::create());
95+
$frontend = new HtmlToPdf($adapter, $streamFactory);
96+
97+
$pdf = $frontend->generateFromHtml('<h1>Hello World</h1>');
98+
```
3299

33100
## Usage
34101

35-
`TO BE DEFINED`
102+
Snappy provides multiple frontends to handle different input types. Each frontend acts as a smart conversion layer that delegates to the underlying adapter.
103+
104+
### HTML String
105+
106+
```php
107+
use KNPLabs\Snappy\Core\Frontend\HtmlToPdf;
108+
109+
$frontend = new HtmlToPdf($adapter, $streamFactory);
110+
$pdf = $frontend->generateFromHtml('<html>...</html>');
111+
```
112+
113+
### HTML File
114+
115+
```php
116+
use KNPLabs\Snappy\Core\Frontend\HtmlFileToPdf;
117+
118+
$frontend = new HtmlFileToPdf($adapter);
119+
$pdf = $frontend->generateFromHtmlFile(new \SplFileInfo('path/to/file.html'));
120+
```
121+
122+
### URI
123+
124+
```php
125+
use KNPLabs\Snappy\Core\Frontend\UriToPdf;
126+
127+
$frontend = new UriToPdf($adapter);
128+
$pdf = $frontend->generateFromUri($uriFactory->createUri('https://google.com'));
129+
```
130+
131+
### DOMDocument
132+
133+
```php
134+
use KNPLabs\Snappy\Core\Frontend\DOMDocumentToPdf;
135+
136+
$frontend = new DOMDocumentToPdf($adapter);
137+
$pdf = $frontend->generateFromDOMDocument($domDocument);
138+
```
139+
140+
### Stream
141+
142+
```php
143+
use KNPLabs\Snappy\Core\Frontend\StreamToPdf;
144+
145+
$frontend = new StreamToPdf($adapter);
146+
$pdf = $frontend->generateFromStream($htmlStream);
147+
```
148+
149+
## Frontends
150+
151+
Frontends are the public API of Snappy. They are responsible for normalizing the input and calling the correct method on the backend adapter.
152+
153+
If an adapter doesn't natively support a specific input (e.g., Dompdf doesn't support URIs), the frontend will attempt to convert the input to a format the adapter supports (e.g., fetching the URI content and passing it as HTML).
154+
155+
## Options
156+
157+
You can configure the PDF generation using the `Options` class.
158+
159+
### Page Orientation
160+
161+
```php
162+
use KNPLabs\Snappy\Core\Backend\Options;
163+
use KNPLabs\Snappy\Core\Backend\Options\PageOrientation;
164+
165+
$options = Options::create()
166+
->withPageOrientation(PageOrientation::Landscape);
167+
168+
$adapter = $adapter->withOptions($options);
169+
```
170+
171+
### Backend Specific Options
172+
173+
Each backend supports extra options.
174+
175+
#### Dompdf
176+
177+
```php
178+
$options = Options::create()
179+
->withExtraOptions([
180+
'construct' => ['isRemoteEnabled' => true],
181+
'output' => ['compress' => 0],
182+
]);
183+
```
184+
185+
#### Chrome Headless
186+
187+
```php
188+
use KNPLabs\Snappy\Backend\ChromeHeadless\ExtraOption\NoSandbox;
189+
use KNPLabs\Snappy\Backend\ChromeHeadless\ExtraOption\WindowSize;
190+
191+
$options = Options::create()
192+
->withExtraOptions([
193+
new NoSandbox(),
194+
new WindowSize('1920,1080'),
195+
]);
196+
```
197+
198+
## Symfony Bundle Configuration
199+
200+
If you use the Symfony bundle, you can configure your backends in `config/packages/snappy.yaml`.
201+
202+
### Dompdf
203+
204+
```yaml
205+
snappy:
206+
backends:
207+
default:
208+
dompdf:
209+
options:
210+
pageOrientation: portrait
211+
extraOptions:
212+
construct:
213+
isRemoteEnabled: true
214+
output:
215+
compress: 1
216+
```
217+
218+
### WkHtmlToPdf
219+
220+
```yaml
221+
snappy:
222+
backends:
223+
default:
224+
wkhtmltopdf:
225+
binary: /usr/local/bin/wkhtmltopdf
226+
timeout: 60
227+
options:
228+
pageOrientation: landscape
229+
```
230+
231+
### Chrome Headless
232+
233+
```yaml
234+
snappy:
235+
backends:
236+
default:
237+
chrome_headless:
238+
binary: google-chrome
239+
timeout: 120
240+
options:
241+
extraOptions:
242+
- KNPLabs\Snappy\Backend\ChromeHeadless\ExtraOption\NoSandbox
243+
```
244+
245+
## Creating Custom Adapters
246+
247+
To create a custom adapter, you must implement the `KNPLabs\Snappy\Core\Backend\Adapter` interface or one of its specialized versions:
248+
249+
- `KNPLabs\Snappy\Core\Backend\Adapter\HtmlToPdf`
250+
- `KNPLabs\Snappy\Core\Backend\Adapter\HtmlFileToPdf`
251+
- `KNPLabs\Snappy\Core\Backend\Adapter\UriToPdf`
252+
- `KNPLabs\Snappy\Core\Backend\Adapter\DOMDocumentToPdf`
253+
- `KNPLabs\Snappy\Core\Backend\Adapter\StreamToPdf`
254+
255+
You should also implement a `KNPLabs\Snappy\Core\Backend\Factory` to instantiate your adapter.
36256

37-
## Examples of use
257+
## Chrome Headless Notes
38258

39-
`TO BE DEFINED`
259+
- **Orientation**: Chrome Headless ignores the orientation flag for PDF generation in some versions. It is recommended to use CSS `@page { size: landscape; }` in your HTML for reliable results.
260+
- **Docker/CI**: When running Chrome in a container, you often need the `--no-sandbox` and `--disable-dev-shm-usage` flags.
261+
- **Stderr**: Chrome might output DevTools listening messages to stderr. This is normal and does not necessarily indicate a failure.
40262

41263
## Bugs and Support
42264

0 commit comments

Comments
 (0)