On line guide/help

You are on page 42 of the online help. Navigate sequentially through the guide pages or search for a topic of interest to you.

Index Prev. Next

Data

Data providers

Read the report data from a database

A data provider executes a query and returns the data rows to the report. It is linked to a section, with the SetSection method, or to a chart datalist, with the SetDatalist method, using the id of the section or of the datalist.

The library includes four data providers:

DataProviderMySQLi for a mysqli connection
DataProviderPDO for a PDO connection (MySQL, PostgreSQL, SQLite, ..)
DataProviderEloquent for the Laravel framework
DataProviderDoctrine for the Symfony framework

Constructor and query parameters

All the data providers have the same arguments: the database connection, the SQL query and an optional array of query parameters, that replace the ? placeholders of the query in the same order.

DataProviderMySQLi(mysqli $connection, string $query, array $args = [])
DataProviderPDO(PDO $connection, string $query, array $args = [])
DataProviderEloquent(?ConnectionInterface $connection, string $query, array $args = []) : Laravel connection, eg. DB::connection() (if null, the default connection is used)
DataProviderDoctrine($connectionOrEntityManager, string $query, array $args = []) : Doctrine Connection or EntityManager

DataProviderMySQLi requires the mysqlnd driver (included in the standard PHP distributions). DataProviderPDO, DataProviderEloquent and DataProviderDoctrine count the rows with a COUNT(*) query that contains the report query: write the query without the final semicolon.

Data providers linked to sections and to a datalist

Placeholders in the queries

The query of a section can contain the placeholders of the other sections and the variables, eg. {inv.invoiceNumber}: they are replaced with their current values each time the section starts, before the query is executed. This is how a detail section reads the rows of the current master row.

Warning: the placeholders are replaced as text, they are not query parameters. Use them only with values that cannot contain SQL code (eg. numeric keys read from the database), and use the ? parameters for the values received from the users.

The placeholders are not replaced in the queries of the datalists.

Custom data providers

A custom data provider (eg. for a REST API, a CSV file or a PHP array) is a class that implements the DataProviderInterface interface:

execute() Reads the data
fetchNext() Returns the next row as an associative array (field name => value), or null at the end of the data
getCurrentRow() Returns the current row
hasMoreRecords() Returns true if the current row is not null
getRecordCount() Returns the number of rows
reset() Resets the data provider
getQuery() / setQuery() Query with the placeholders already replaced
getQueryRaw() / setQueryRaw() Original query, with the placeholders

use AlienProject\PDFReport\DataProviderInterface;

class DataProviderArray implements DataProviderInterface
{
    private int $index = -1;
    private ?array $currentRow = null;

public function __construct(private array $rows) {}

public function execute(): void { $this->reset(); }
    public function fetchNext(): ?array
    {
        $this->index++;
        $this->currentRow = $this->rows[$this->index] ?? null;
        return $this->currentRow;
    }
    public function getCurrentRow(): ?array { return $this->currentRow; }
    public function hasMoreRecords(): bool { return $this->currentRow !== null; }
    public function getRecordCount(): int { return count($this->rows); }
    public function reset(): void { $this->index = -1; $this->currentRow = null; }
    public function getQuery(): string { return ''; }
    public function setQuery(string $query): void {}
    public function getQueryRaw(): string { return ''; }
    public function setQueryRaw(string $queryRaw): void {}
}

$report->SetSection('items', new DataProviderArray([
    [ 'code' => 'A01', 'description' => 'First item' ],
    [ 'code' => 'A02', 'description' => 'Second item' ],
]));