|
Getting started
In this tutorial we will explain how to use the PDFen SDK for PHP. As a starting point, please download the SDK. If you've chosen the PHAR version of the SDK, don't forget to load the SDK using:
require_once "path/to/pdfen-sdk-php.phar";
All code on this page is interactive and can be run. If you are questioning what the value is of a specific value, you can hover over this value. This page presents three examples:
- Example 1 - Creating a PDF using a simple text file;
- Example 2 - Uploading multiple files and converting them to PDFs in a ZIP;
- Example 3 - Converting multiple webpages to a single PDF.
- Example 4 - How to set covnert options like PDF/A, Compress, OCR, etc.
Example 1 - Creating a PDF using a simple text file
The first step in using the PDFen SDK is either loading an existing session or using our credentials to login and create a new session. In this case we will login using the code described below.
//Create an SDK object:$sdk = new PDFen\SDK;//Use it to login:$session = $sdk->login($username, $password);
The next step is to create a file. In this example we use newFileFromBlob
which allows us to create a file using a string
as content.
After creating a file, you have to call create
, which is not done automatically. This function will send the file to the server.
(For performance reasons we require you to call create
explicitly).
Please provide the $content
and $name
variables for the snippit below, by clicking on show.
//Create a local file object$file = $session->newFileFromBlob($content, $name, "txt");//Upload it to PDFen$file->create();
At this moment, we have provided enough information to generate a PDF. To start the PDFen process we use the convert
function.
//Start the conversion$result = $session->convert();
The last step is to download the PDF. Using download(true)
, we directly echo the generated file to the output.
//Download the result and write it to the output$result->download(false);
Example 2 - Uploading multiple files and converting them to pdfs in a ZIP
The first step in using the PDFen SDK is either loading an existing session or using our credentials to login and create a new session. In this case we will login using the code described below.
//Create an SDK object:$sdk = new PDFen\SDK;//Use it to login:$session = $sdk->login($username, $password);
The next step is to create files. In this example we use newFile
which allows us to create a file using the content of a local file. A local file can be specified by a path (string
) or a SplFileInfo
as content.
After creating a file, you have to call create
, which is not done automatically. This function will send the file to the server.
(For performance reasons we require you to call create
explicitly).
//Create the first local file using//the uploaded file as an \SplFileInfo object$file_1 = $session->newFile($input_file_1);//Upload it to PDFen$file_1->create();//Create the second local file using//the uploaded file as an \SplFileInfo object$file_2 = $session->newFile($input_file_2);//Upload it to PDFen$file_2->create();
An ordering can be defined using setOrdering
. The ordering parameter can be a list of PDFen\Session\File
s, indicating in which order the files must be merged.
The ordering parameter can also have a chapter structure. An example of a chapter structure is given in the next code snippit.
$session->setOrdering([["title" => "Upload folder 1","children" => [[ "title" => "subfolder","children" => [$file_1]]]],[ "title" => "Upload folder 2","children" => [$file_2]]]);$session->update();
At this moment, we have provided enough information to generate a PDF. To start the PDFen process we use the batch
function.
The batch
function allows you to provide a callback that processes the progress information provided by the API.
In our case we save the messages to an array which can be used later on.
Difference between convert
, batch
and merge
:
-
batch
: Force convert files as separate files (results in ZIP file). -
merge
: Force merging (after convert) all files into one PDF. convert
: Let the setting in the selected template (or default) decide what to domerge
orbatch
.
// Make a new array to store the progress messages in$messages = array();//Start as batch to retrieve a ZIP file with the files$result = $session->batch(function($progress_lines, $previous_line) use (&$progress){global $messages;if($previous_line !== null) {//Overwrite the last line in case the last line has been updated$messages[] = "\r$previous_line";}//output all new progress information});
What remains is to download the file.
//Download the result and write it to the output$result->download(false);
Example 3 - Converting multiple webpages to a single PDF
The first step in using the PDFen SDK is either loading an existing session or using our credentials to login and create a new session. In this case we will login using the code described below.
//Create an SDK object:$sdk = new PDFen\SDK;//Use it to login:$session = $sdk->login($username, $password);
The next step is to create files. In this example we use newFile
to convert a webpages.
The url of a webpage can be specified using setURL
.
After creating a file, you have to call create
, which is not done automatically. This function will send the file to the server.
(For performance reasons we require you to call create
explicitly).
Please note, that it is your responsibility to provide legal urls. Invalid URLs will only be detected while the PDF is being created.
//Create the first file$file_1 = $session->newFile();//Set the url$file_1->setURL($url_1);//Set the title$file_1->setTitle($title_2);//Set the file type$file_1->setExtension('html');//Upload it to PDFen$file_1->create();//Create the second file.$file_2 = $session->newFile();$file_2->setURL($url_2);$file_2->setTitle($title_2);$file_2->setExtension('html');//Upload it to PDFen$file_2->create();
An ordering can be defined using setOrdering
. The ordering parameter can be a list of PDFen\Session\File
s, indicating in which order the files must be merged.
The ordering parameter can also have a chapter structure. In case merge is used, it describes the bookmarks, contents (in case such a template is selected) and other structural pages.
$session->setOrdering([["title" => "Upload folder 1","children" =>[[ "title" => "subfolder","children" => [$file_1]]]],[ "title" => "Upload folder 2","children" => [$file_2]]]);$session->update();
At this moment, we have provided enough information to generate a PDF. To start the PDFen process we use the merge
function.
The merge
function allows you to provide a callback that processes the progress information provided by the API.
In our case we save the messages to an array which can be used later on.
// Make a new array to store the progress messages in$messages = array();//Start as batch to retrieve a ZIP file with the files$result = $session->merge(function($progress_lines, $previous_line) use (&$progress){global $messages;if($previous_line !== null) {//Overwrite the last line in case the last line has been updated$messages[] = "\r$previous_line";}//output all new progress information});
The last step is download the file.
//Download the result and write it to the output$result->download(false);
Example 4 - Set convert options
The example below show how to set options (as a logged in or paid user) like PDF/A type, Compression and OCR (text recognition).
$options = $session->getOptions();$options->setOption('pdftype', '2B');$options->update();