README

A library that allows you to generate PDF reports from an XML template describing the document, with placeholders for data.

For general information about this project, visit: https://alienproject.org

Introduction

How the PDFReport library works

The library uses an XML template that describes the structure of the PDF document (for example, page size and orientation, objects to display: text, lines, rectangles, barcodes, graphics, etc.) and the data to print (via placeholders that are automatically replaced with the data).

PHP Code Example

For very simple reports, you can create a PHP report with just 5 lines of code, as the following example:

<?php
use AlienProject\PDFReport\PDFReport;
$report = new PDFReport();
$report->LoadTemplate('demo.xml');
$report->SetVar('MESSAGE', 'Current date ' . date('Y-m-d'));
$report->BuildReport();
?>

Code explanation:

Use the "use" statement to automatically load the PDFReport class
Create a new library instance
Pass the XML template to the instance (using LoadTemplate or SetTemplate method)
Define the data sources (external, such as data connectors linked to databases/files, or via variables using SetVar method)
Generate the report using the "BuildReport" method

Installation

Requirements

PHP 8.1 or later
Composer
PHP extensions: dom and libxml (XML templates and DataProviderXML), mbstring (recommended, used by TCPDF and DataProviderCSV for the encoding conversion), mysqli or pdo only for the database data providers

Use "composer" to install the library. If Composer isn't installed in your development environment, this free tool can be downloaded from the official website.

Installing in a new project

Create a new folder that will contain all the files for your new PHP project. Open a command shell in this folder (the root of your PHP project) and run the command below.

A "vendor" folder will be created with all the project's dependencies/libraries. This folder will also contain the "autoload.php" file to include in your PHP project. (This is an autoloader that will allow you to use the PDFReport library without having to write any include lines. The classes will be loaded automatically before they are used.)

Two more files (composer.json, composer.lock) will also be created automatically in the root folder. The composer.json file will contain the configuration for the library loaded in the project. To upgrade to the latest version in the future, use the "composer install" command.

composer require alienproject/pdfreport

Installing into an existing project

In the root folder of your existing PHP project, check if the composer.json file exists. If so, open it with a text editor or your development environment (e.g., Visual Studio Code or PHPStorm). If the file doesn't exist, you can use the command described above (the one used for new projects). Make sure the file contains the following configuration lines:

{
    "require": {
        "alienproject/pdfreport": "*"
    }
}

Open a command shell and run the following command in the root of your PHP project, where the composer.json file is located. This command opens the composer.json file and installs or updates all libraries/packages/dependencies as specified in its configuration. In the case of the PDFReport library, the latest one published on https://packagist.org/ will be installed.

composer install

Test Installation

To verify that the library is working, you can create a test page with the following PHP code that will display a simple message. This code is a standard index.php page. If you use a framework like Laravel or Symfony you must add the test code in a controller and set the route that call it. Also add the XML template file (see below).

File: index.php

<?php
/*
 * Test url:
 * https://<your_path>/index.php
 *
 */
require_once('./vendor/autoload.php');
use AlienProject\PDFReport\PDFReport;

$label = "Hello WORLD";
$templateFileName = getcwd() . DIRECTORY_SEPARATOR . 'hello.xml';

$report = new PDFReport();
$report->LoadTemplate($templateFileName);
$report->SetVar('HELLO_MESSAGE', $label);
$report->BuildReport();
?>

Create an XML file in the root folder with the following code:

File: hello.xml

<pdf>
    <!-- *** Document info. *** -->
    <doc_info>
        <creator>Alien Project</creator>
        <author>#MBR</author>
        <title>Hello World</title>
    </doc_info>
    <section id="main">
        <!-- Create a new page with the following settings when this section starts -->
        <page format="A5" orientation="L"/>

        <!-- Print content -->
        <print_content>hello</print_content>

        <!-- Send the PDF inline to the browser (use F to save it to a server file, S to get it as a string from BuildReport) -->
        <output>
            <dest>I</dest>
            <name>page_sample_01.pdf</name>
            <isUTF8>true</isUTF8>
        </output>
    </section>
    <content id="hello">
        <!-- *** Print a single box : start *** -->
        <box x1="10" y1="60" x2="200" y2="85">
            <text>{HELLO_MESSAGE}</text>
            <textvertalign>Center</textvertalign>
            <texthorizalign>Center</texthorizalign>
            <border>0</border>
            <fill type="S" color="2874a6"/>
            <font>
                <fontfamily>Helvetica</fontfamily>
                <fontsize>32</fontsize>
                <fontstyle>B</fontstyle>
                <fontcolor>FFFFFF</fontcolor>
            </font>
        </box>
        <!-- *** Print box : end *** -->
    </content>
</pdf>

Version History

Last version: 1.0.12 - 05 Oct. 2026

Ver. 1.0.12 - 05 Oct. 2026

Requirements: PHP 8.1 or later (the library already used PHP 8.1 functions)
New data providers that read the data without a database: DataProviderArray (PHP array), DataProviderCSV, DataProviderJSON and DataProviderXML (files). The data files can be changed without touching the code; all of them support master / detail sections
2D barcodes: <barcode type="QRCODE,M"> (also DATAMATRIX, PDF417), new color and backcolor attributes
Sections with columns (columns, column_width): sheets of labels or badges with a single section
Charts: new axisformat (format mask of the axis labels; by default the labels use the number format variables) and showaxis attributes; auto scale rounded to a "round" step and shared by all the measures; single bar chart axislinestyle, tickscount and title with the vertical orientation; gauge <axisfont>; pie chart <totalfont>, total printed inside the ring; legend boxsize, labelheight, titleheight, itemmargin, padding, showvalues and format attributes
Charts: an empty value in a data element is a missing value (no point in the line chart); the value 0 is now drawn
Fixed the bar chart X axis labels drifting from the bars (barmargin without barsize) and the bars ignoring minvalue; fixed the chart titles printed too far from the chart
Fixed the line chart with the Composer autoloader: error Class "ChartStyleType" not found (the enum is now in its own file)
Fixed textfit Auto / Resize: a word wider than the box (eg. a single character in a very narrow box) was not printed; the font is now reduced
Fixed placeholders with value 0 printed as an empty string (and printif conditions on them)
Fixed printif conditions with an empty side, eg. {row.flag}=1 when the field is empty ({row.note}= now tests an empty field)
Fixed {PAGECOUNT}: it is now the total number of pages of the document (eg. "Page {PAGEINDEX} of {PAGECOUNT}"). Templates that use it are built in two passes
Fixed a nested section inside a section without data provider: the rows that did not fit in the first page were lost; they now continue on the following pages, with the contents of the outer section printed again on each page

Ver. 1.0.11 - 29 Sep. 2026

Breaking change: the <output> element is now honored (it was ignored and the PDF was always sent inline to the browser). Templates with <dest>F</dest> that expect to see the PDF in the browser must use <dest>I</dest> (or <dest>FI</dest>)
Behavior change: a section whose data query returns no rows is no longer printed
BuildReport() returns the PDF document when the destination is S (string) or E (base64 email attachment)
Fixed the limit of 500 data rows per report
Fixed elements and settings being ignored: <opacity>, <textfit>, custom page size in <page>, gauge chart legend
Fixed rectangle corner radius, barcode settings inherited by the following barcodes, default fill style color, KPI chart errors and border, line/area chart without <symbolstyle>, chart legend colors
Charts: placeholders supported in values, segments and titles; new format attribute for gauge and KPI charts; new showtotal, totallabel and format attributes for the pie chart total
An invalid XML template raises an exception with the line, column and reason of the error
Known issue: {PAGECOUNT} returns the current page number (fixed in 1.0.12)

Ver. 1.0.10 - 13 Aug. 2026

Fixed "textfit" attribute (and "TextFit" default element) being ignored: every box always used the default "Auto" mode (the attribute had never taken effect since it was introduced in 1.0.5)

Ver. 1.0.9 - 13 Jul. 2026

Fixed a bug where the barcode element did not handle the border attribute (a black border was always displayed)

Ver. 1.0.8 - 01 Jul. 2026

Fixed a problem in the installer package related to the TextFit.php file (a missing enum that the autoloader was unable to load)

Ver. 1.0.7 - 01 Jul. 2026

Added new attribute "printif" for conditional printing of the following elements:
- line
- box / text
- rectangle / rect
- circle
- image
- barcode
- piechart
- singlebarchart
- barchart
- linechart
- gaugechart
- kpichart
- page

Ver. 1.0.6 - 26 Jun. 2026

Bug fix for image tag not supporting dynamic image set via variable
Fixed automatic image processing (previously limited to PNG format only)
Minor fix and updates

Ver. 1.0.5 - 27 Nov. 2025

Added new attribute "textfit" to box element. Possible values:
- None : Use text as it is (no truncate, no resize)
- Auto (default) : Truncate text if too large. If text truncate fails, resize text (scales down font if text is too large)
- Truncate : Truncate text if too large
- Resize : Scales down font if text is too large
Added new attribute "format" to box element (custom text format)
Added new elements:
- TextFit (sets the default text fitting mode, used when the "textfit" attribute is not set on the box element)
- Measure (define chart measures)
Fix for Box element (handled UTF8 multibyte text)
Added a new attribute "showvalues" (yes/no) to barchart element
Added a new attribute "format" to measure element (float, integer, currency, %, ..)
Added new method SetFormatCallback to call a custom callback function for values formatting
Minor fix for bar chart and line/area chart
Added more flexibility in defining the print area, using the (x1,y1)+(x2,y2) or (x,y)+(width,height) attributes, on the following elements:
- Box
- Line
- Rectangle
- Barcode
- Image
- PieChart
- GaugeChart
- KpiChart
- SingleBarChart
- BarChart
- LineChart (AreaChart)
- Legend
Added support for multiple measures in a bar chart (side-by-side bars)
The linear gradient fill style can now have either horizontal (default) or vertical direction

Ver. 1.0.4 - 15 Nov. 2025

Added rotateangle (0° - 360°) attribute to box element to rotate box around angle x1,y1
Added new graphic elements
- Bar chart (vertical/horizontal)
- Line/area chart

Ver. 1.0.3 - 08 Oct. 2025

Updated/fix Doctrine data provider class (for Symfony framework)
Updated/fix Eloquent data provider class (for Laravel framework)
The TCPDF library is set in the global namespace (fix for Symfony framework)

Ver. 1.0.2 - 04 Oct. 2025

Renamed all application classes to make them 100% compatible with the PSR-4 autoloader standard in Linux environment in addition to the Windows environment (already supported)

Ver. 1.0.1 - Sep. 2025

Minor fix and updates

Ver. 1.0.0 - Aug. 2025

First release
Standard items included:
- Page
- Line
- Box/text
- Rectangle
- Circle
- Barcode
- Image
Formatting elements included:
- Page settings
- Line style
- Font
- Fill style
- Color opacity level
Graphic elements included:
- Single bar chart
- Pie/Donut chart
- Gauge chart
- KPI chart
- Charts sub-components:
  - Legend
  - Segment list
Data providers included:
- PDO
- MySqli
- Eloquent ORM (Laravel framework)
- Doctrine ORM (Symfony framework)
Other items
- Comments
- Section
- Content
- Output

Documentation and Interactive Testing

The complete online guide is available at: https://alienproject.org/help

Interactive Testing

By accessing the reserved area, you can interactively run the example reports presented on the home page. You can modify the XML template code to test various functionalities.

Access to the reserved area can be done quickly via:

Google Authentication (if you have a Google account)
Classic registration with email address (a confirmation email will be sent to the specified address with a link to confirm the subscription)

For more information and examples, visit the main project website: https://alienproject.org

Last document update: 05 Oct. 2026

alienproject / pdfreport

Package info

Security

Fund package maintenance!

Statistics