README

MatoDocs is a PHP library used to edit and process .docx and .html files and optionally convert them to a .pdf format.

Installation and Configuration

Prerequisite:

PHP to use the package. Specific installations are left to the user.
Composer for downloading the latest version of the package along with its dependencies.
A Convertio API for converting documents to PDF format.

Include this package into your project via composer by using the console command in the project's root directory:

composer require matogen/processor dev-master

If you encounter an error along the lines of "The zip extension and unzip/7z commands are both missing, skipping", uncomment the `;extension=zipline in your php.ini file toextension=zip`. Link to stackoverflow post of error.

Furthermore, you can also install Puppeteer if you plan on downloading images from url paths or html syntax.

npm i puppeteer

Importing the package

Before you can import the package's classes, you will need to include the path to the autoload.php script generated by composer.

# General path to autoload script
include_once __DIR__ . '/vendor/autoload.php';

# .docx processor, derived class import
use \Matogen\Processor\DocxProcessor

# .HTML processor, derived class import 
use \Matogen\Processor\HTMLProcessor

General use cases

The examples below shows common use cases when using this package.

DocxProcessor

Before processing docx templates, you will first need to instantiate a new DocxProcessor class, and pass through your Convertio API key string along with the path to the docx template you would like to edit.

$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

Making text edits

You can use macros within your template file to indicate where your would like to make text edits. These macros take the form `${macro}`. These macros are then swapped out for the actual text you would like to insert, while the template file is being processed.

To do this, you will need to provide an array containing the macros and the associated text you would like to replace them with. Note that you only need the name of the macro when constructing the array and not the encapsulating `${}` values that are only used when defining the macro within the template file.

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of text edits
// 'Macro' => 'Text to be added'
$arrTextEdits = array(
    'TextEdit1' => 'First text edit.',
    'TextEdit2' => 'Second text edit.',
    'TextEdit3' => 'Third text edit.'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile($arrTextEdits);

Given a template containing:

Testing text edits, very exciting!
${TextEdit1} 
${TextEdit2}
${TextEdit3}

The example above will make the following edits:

Testing text edits, very exciting!
First text edit. 
Second text edit.
Third text edit.

Finally, the text that are replacing the macros will take on the initial attributes of the macro. For example, a macro that is italicized with a font of 12 will be replaced with text that is also italicized with a font of 12.

Making image edits

Similar to text edits, you can use macros within your template file to indicate where your would like to insert images. These macros are then swapped out for the actual images you would like to insert, while the template file is being processed.

To do this, you will need to provide an array containing the macros and the associated image paths you would like to replace them with. Note that you only need the name of the macro when constructing the array and not the encapsulating `${}` values that are only used when defining the macro within the template file.

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of image edits
// 'Macro' => 'Image path string'
$arrImageEdits = array(
    'ImageEdit1' => 'path/to/image1.png',
    'ImageEdit2' => 'path/to/image2.png'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], $arrImageEdits);

Given a template containing:

Testing image edits, very exciting!
${ImageEdit1} 
${ImageEdit2}

The example above will swap out the macro with the correct image if it exists at the path provided. Unlike text edits, the macros used then inserting images can take several forms:

${macro}
${macro:[width]:[height]:[ratio]}
${macro:[width]x[height]}
${macro:size=[width]x[height]}
${macro:width=[width]:height=[height]:ratio=false}

Where:

[width] and [height] can be just numbers or numbers with measure, which supported by Word (cm, mm, in, pt, pc, px, %, em, ex)
[ratio] uses only for false, - or f to turn off respect aspect ration of image. By default template image size uses as ‘container’ size.

This information can also be specified in the array that is processed. Using the example above, image1.png's width, height and ratio can be specified as shown below.

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of image edits
// 'Macro' => 'Image path string'
$arrImageEdits = array(
    'ImageEdit1' => array('path'=>'path/to/image1.png', 'width'=>100, 'height'=>100, 'ratio'=>false),
    'ImageEdit2' => 'path/to/image2.png'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], $arrImageEdits);

Making table edits

Just like text edits, you can use macros within your template file to indicate where your would like to make text edits. These macros take the form `${macro}`. These macros are then swapped out for the actual tables you would like to insert, while the template file is being processed.

To do this, you will need to provide an array containing the macros and the associated table structure, and values you would like to replace them with. Note that you only need the name of the macro when constructing the array and not the encapsulating `${}` values that are only used when defining the macro within the template file.

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', 'Text_row2_column2', 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], [], $arrTableEdits);

For the example above, `$arrTableEdits` contains an array of macros. Each macro is associated with a 2D array of values, where each value corresponds to the value of a table cell. The location of the cell within the table is equal to its index within the 2D array.

Inserting an image into a cell follows the same procedure as normally inserting an image into the template file. The difference is, rather than adding the macro for the image to the template file, you write the macro into a specified cell using the table array. The example below, shows how a macro for an image is inserted into the cell in row 2 column 2 of a table using `$arrTableEdits`. After the macro is inserted, the path to the image is indicated using `$arrImageEdits` like you would normally do when making image edits.

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', '${ImageEdit1:150:150:f}', 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

$arrImageEdits = array(
    'ImageEdit1' => 'path/to/image1.png'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], $arrImageEdits, $arrTableEdits);

Additional styles can be added to the table by passing another array containing all the style data for the table as shown below:

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

$arrTableOptions = ['borderSize' => 12, 'borderColor' => 'green', 'width' => 100 * 50]

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', 'Text_row2_column2', 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], [], $arrTableEdits, $arrTableOptions);

By default, a table has the following style:

borderSize: 12,
borderColor: Black
width: 100 * 50
unit: percentage

Note that the table width will always be measured in fiftieths of a percent. If you would like to add additional style effects to the table cells, you can do so by replacing the value of a cell with another array indicating the value you would like to add to the cell and an array of style information for the specific cell as shown below:

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

$arrTableOptions = ['borderSize' => 12, 'borderColor' => 'green', 'width' => 100 * 50]

// Array of table edits
$arrTableEdits = array(
    'TableEdit1' => array(
        array('Text_row1_column1', 'Text_row1_column2', 'Text_row1_column3'),
        array('Text_row2_column1', ['value'=>'Text_row2_column2', 'style'=>['bgColor'=>'9966CC']], 'Text_row2_column3'),
        array('Text_row3_column1', 'Text_row3_column2', 'Text_row3_column3')
    )
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile([], [], $arrTableEdits);

This example shows how the cell in row 2 column 2 contains the value 'Text_row2_column2', but will also have a purple background. For more information regarding table and table cell style information, please go here.

Saving processed file

The simple example below shows how to save processed files as either a docx or pdf file. If the output directed doesn't exist, it will be created.

// Instantiate new processor class
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');

// Array of text edits
$arrTextEdits = array(
    'TextEdit1' => 'First text edit.',
    'TextEdit2' => 'Second text edit.',
    'TextEdit3' => 'Third text edit.'
);

// Process template file 
$updatedDocx = $docProcessor->processAndConvertFile($arrTextEdits);

// Save file as docx
$docProcessor->saveFile('path\to\chosen\directory', $updatedDocx, false);
// Save file as pdf
$docProcessor->saveFile('path\to\chosen\directory', $updatedDocx, true);

Converting docx files to pdf

As shown below, docx files can also be directly converted to pdf without having to be processed first. Just like when saving processed files, non-existent output directories will be created.

// Convert docx file to pdf
$docProcessor = new DocxProcessor('YOUR_CONVERTIO_API_KEY_STRING', 'path\to\template\file.docx');
$docProcessor->convertToPDF('path\to\chosen\directory', 'path\to\docx\file', false);

published by Matogen Corporate Software Development @2024

matogen / processor

Maintainers

Details