DocumentGeneratorX API Reference

Overview

This package generates PDF documents from DOCX or HTML templates.

| Input Format | Output Format | |-------------|---------------| | DOCX (Word) | PDF | | HTML | PDF |

DocumentGenerator Class

Main class for generating documents.

Methods

template(string $source): self

Set the template file path or URL.

Parameters: - $source (string) - File path or URL to template (.docx or .html)

Returns: self for method chaining

Example:

// Local DOCX file
DocumentGenerator::template('/path/to/template.docx')

// Local HTML file
DocumentGenerator::template('/path/to/template.html')

// URL
DocumentGenerator::template('https://example.com/template.docx')

templateFromStorage(string $path, string $disk = 'local'): self

Load template from Laravel storage disk.

Parameters: - $path (string) - Path within storage disk - $disk (string) - Storage disk name (default: 'local')

Returns: self for method chaining

Example:

DocumentGenerator::templateFromStorage('templates/invoice.docx', 'public')

variables(array $variables): self

Set all variables at once.

Parameters: - $variables (array) - Associative array of variable names and values

Returns: self for method chaining

Example:

DocumentGenerator::variables([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'age' => 30,
    'photo' => '/path/to/image.jpg',
])

addVariable(string $key, mixed $value): self

Add a single variable.

Parameters: - $key (string) - Variable name - $value (mixed) - Variable value

Returns: self for method chaining

Example:

DocumentGenerator::addVariable('name', 'John Doe')
    ->addVariable('email', 'john@example.com')

generate(?string $outputPath = null): string

Generate the PDF document.

Parameters: - $outputPath (string|null) - Output file path (auto-generated if null)

Returns: string - Path to generated PDF file

Throws: DocumentGeneratorException on failure

Example:

$path = DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John'])
    ->generate('/output/document.pdf');

generateToStorage(string $path, string $disk = 'local'): string

Generate and save to storage disk.

Parameters: - $path (string) - Path within storage disk - $disk (string) - Storage disk name (default: 'local')

Returns: string - Full path to stored file

Example:

$path = DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John'])
    ->generateToStorage('documents/output.pdf', 'public');

download(?string $filename = null): BinaryFileResponse

Generate and return as download response.

Parameters: - $filename (string|null) - Download filename (auto-generated if null)

Returns: BinaryFileResponse - Laravel download response

Example:

return DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John'])
    ->download('document.pdf');

getVariables(): array

Get current variables.

Returns: array - Current variables

getTemplateFormat(): ?string

Get detected template format.

Returns: string|null - Template format ('docx' or 'html')

temporary(bool $temp = true): self

Set output as temporary (auto-deleted on script end).

Parameters: - $temp (bool) - Whether output should be temporary (default: true)

Returns: self for method chaining

Example:

// Force temporary output (overrides config)
DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John'])
    ->temporary()
    ->generate();

permanent(): self

Set output as permanent (not auto-deleted).

Returns: self for method chaining

Example:

// Keep the generated file permanently
DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John'])
    ->permanent()
    ->generate('/path/to/keep/document.pdf');

cleanup(): self

Manually delete the last generated file.

Returns: self for method chaining

Example:

$generator = DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John']);

$path = $generator->generate();

// Do something with the file...

// Then manually delete it
$generator->cleanup();

getLastGeneratedPath(): ?string

Get the path of the last generated file.

Returns: string|null - Path to last generated file

isTemporary(): bool

Check if output is set to temporary mode.

Returns: bool - True if temporary output is enabled

reset(): self

Reset generator state and cleanup files.

Returns: self for method chaining

Example:

$generator = DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John'])
    ->generate();

$generator->reset()
    ->template('another.docx')
    ->variables(['name' => 'Jane'])
    ->generate();

Generators

DocxToPdfGenerator

Converts DOCX templates to PDF.

use Ayoratoumvone\Documentgeneratorx\Generators\DocxToPdfGenerator;

$generator = new DocxToPdfGenerator();
$generator->generate('template.docx', $variables, 'output.pdf');

HtmlToPdfGenerator

Converts HTML templates to PDF.

use Ayoratoumvone\Documentgeneratorx\Generators\HtmlToPdfGenerator;

$generator = new HtmlToPdfGenerator();
$generator->generate('template.html', $variables, 'output.pdf');

Variable Types

Text

Syntax: {{variable:text}}

With Styles: {{variable:text,font-size:14,bold:true,color:red}}

Valid Values: - String - Number (converted to string)

Example:

['name' => 'John Doe']
['description' => 'Lorem ipsum dolor sit amet']

Styling Variables

Add inline styles to any text, number, or date variable.

Syntax

{{variable:type,style1:value1,style2:value2}}

Examples

{{title:text,font-size:24,bold:true,color:#2c3e50}}
{{price:number,color:green,font-weight:bold}}
{{warning:text,color:red,underline:true}}
{{header:text,font-size:18,italic:true,background-color:#f0f0f0}}

Supported Style Properties

| Property | Values | Example | |----------|--------|---------| | font-size | Number (with or without pt) | font-size:14, font-size:18pt | | font-weight | bold, normal | font-weight:bold | | font-style | italic, normal | font-style:italic | | font-family | Font name | font-family:Arial | | color | Hex or named color | color:#FF0000, color:red | | background-color | Hex or named color | background-color:#FFFF00 | | text-decoration | underline, line-through, none | text-decoration:underline |

Shortcut Properties

| Shortcut | Equivalent | |----------|------------| | bold:true | font-weight:bold | | italic:true | font-style:italic | | underline:true | text-decoration:underline |

Named Colors

Supported named colors: red, green, blue, black, white, yellow, orange, purple, pink, gray, grey, brown, navy, teal, maroon

Template Example

DOCX Template:

Invoice #{{invoice_number:text,font-weight:bold}}

Customer: {{customer_name:text,font-size:14,color:#333}}

Total: ${{total:number,font-size:18,bold:true,color:green}}

{{note:text,italic:true,color:gray}}

PHP Code:

$variables = [
    'invoice_number' => 'INV-2024-001',
    'customer_name' => 'John Doe',
    'total' => 1250.00,
    'note' => 'Thank you for your business!',
];

DocumentGenerator::template('invoice.docx')
    ->variables($variables)
    ->generate('invoice.pdf');

Number

Syntax: {{variable:number}} or {{variable:integer}}

Valid Values: - Integer - Float - Numeric string

Example:

['age' => 30]
['price' => 99.99]
['quantity' => '5']

Image

Syntax: - {{variable:image}} - {{variable:image,width:200}} - {{variable:image,height:150}} - {{variable:image,width:400,height:300}} - {{variable:image,ratio:16:9}} - {{variable:image,width:800,ratio:16:9}}

Valid Values: - Local file path - Public URL

Options: - width - Image width in pixels - height - Image height in pixels - ratio - Aspect ratio (e.g., 16:9, 4:3, 1:1)

Example:

['logo' => '/path/to/logo.png']
['avatar' => 'https://example.com/avatar.jpg']
['banner' => storage_path('images/banner.jpg')]

Template:

{{logo:image,width:200}}
{{avatar:image,width:150,ratio:1:1}}
{{banner:image,ratio:16:9}}

Date

Syntax: {{variable:date}}

Valid Values: - DateTime instance - Date string

Example:

['created_at' => now()]
['birth_date' => Carbon::parse('1990-01-01')]
['invoice_date' => '2024-02-05']

Boolean

Syntax: {{variable:boolean}} or {{variable:bool}}

Valid Values: - true / false

Output: "Yes" or "No"

Example:

['is_active' => true]  // Outputs: "Yes"
['has_discount' => false]  // Outputs: "No"

Array

_Since v2.0.7._

Syntax: {{variable:array}}

With Styles: {{variable:array,bold:true,color:red}}

Renders a list of values vertically ? one value per row in the same column. Designed for table columns: the row holding the placeholder is cloned once per value, and the table grows (or shrinks) to fit the data.

Valid Values: - Array of strings (numbers, booleans, and DateTimeInterface are stringified) - A single scalar is treated as a one-element list - An empty array removes the template row

Behavior:

| Layout | Result | |--------|--------| | Placeholder in a table row | Row is cloned once per value; blank rows below are filled first, then rows are auto-added | | Several arrays in one row | Row cloned to the longest list; shorter columns leave blank cells | | Placeholder outside a table | Values stacked on separate lines (joined with line breaks) | | Nested table (table-in-cell) | Not expanded |

Example:

Template (a table whose single data row contains the placeholders):

| {{nums:array}} | {{noms:array}} | {{qs:array}} |

DocumentGenerator::template('inventory.docx')
    ->variables([
        'nums' => ['1', '2', '3'],
        'noms' => ['Hammer', 'Saw', 'Nail'],
        'qs'   => [10, 5, 200],
    ])
    ->generate('inventory.pdf');
// -> three filled rows; values are XML-escaped automatically

Configuration

Config File: config/documentgenerator.php

return [
    // Default template storage path
    'template_path' => storage_path('app/document-templates'),
    
    // Default output path (used when temp_output is false)
    'output_path' => storage_path('app/generated-documents'),
    
    // Save to temp directory and auto-delete (prevents storage filling up)
    'temp_output' => true,
    
    // Delete file after download() is called
    'delete_after_download' => true,
    
    // Cleanup temp files when script ends
    'cleanup_on_shutdown' => true,
    
    // Storage disk for generateToStorage()
    'disk' => 'local',
];

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | template_path | string | storage_path('app/document-templates') | Where templates are stored | | output_path | string | storage_path('app/generated-documents') | Where permanent files are saved | | temp_output | bool | true | Use temp directory for generated files | | delete_after_download | bool | true | Auto-delete after download() | | cleanup_on_shutdown | bool | true | Cleanup when script ends | | disk | string | 'local' | Laravel storage disk |

Temporary Output Behavior

When temp_output is true (default): - Files are saved to system temp directory (sys_get_temp_dir()) - Files are automatically deleted when the PHP script ends - Prevents storage from filling up with generated documents

When temp_output is false: - Files are saved to output_path - Files are kept permanently until manually deleted

Override in code:

// Force temporary for this call
DocumentGenerator::template('template.docx')
    ->temporary()
    ->generate();

// Force permanent for this call
DocumentGenerator::template('template.docx')
    ->permanent()
    ->generate('/keep/this/file.pdf');

Exceptions

DocumentGeneratorException

Base exception for all document generation errors.

Common Cases: - Template file not found - Invalid template format - Invalid variable type - Image processing error - PDF generation error

Example:

use Ayoratoumvone\Documentgeneratorx\Exceptions\DocumentGeneratorException;

try {
    DocumentGenerator::template('template.docx')
        ->variables(['name' => 'John'])
        ->generate();
} catch (DocumentGeneratorException $e) {
    Log::error('Document generation failed: ' . $e->getMessage());
}

Facade

DocumentGenerator Facade

Namespace: Ayoratoumvone\Documentgeneratorx\Facades\DocumentGenerator

Usage:

use Ayoratoumvone\Documentgeneratorx\Facades\DocumentGenerator;

DocumentGenerator::template('template.docx')
    ->variables(['name' => 'John'])
    ->generate();

Best Practices

1. Always validate inputs before passing to generator
2. Use type hints in templates for better validation
3. Optimize images before processing (smaller images = faster generation)
4. Cache templates for repeated use
5. Use queues for bulk generation
6. Handle exceptions appropriately
7. Clean up generated files when no longer needed

Version Compatibility

| Package Version | Laravel Version | PHP Version | |----------------|-----------------|-------------| | 2.x | 9.x, 10.x, 11.x, 12.x | 8.1+ |

Support

• Documentation: GitHub
• Issues: GitHub Issues
• Email: 44085615+Ayoratou99@users.noreply.github.com