Fireguard Report
, (*1)
, (*2)
Other languages for this documentation: PORTUGUÊS, (*3)
The Fireguard Report is a report management package in PHP that aims to help you export information in a variety of
formats, such as HTML, PDF and IMAGE, using a unique, integrated and simple interface., (*4)
Summary
Installation, (*7)
The FireGuard Report can be installed through the composer., (*8)
In order for the package to be automatically added to your composer.json file, run the following command:, (*9)
composer require fireguard/report
Or if you prefer, add the following snippet manually:, (*10)
{
"require": {
...
"fireguard/report": "^0.1"
}
}
Installing and Updating PhantomJs, (*11)
To generate the PDF files and Images, this package is used by PhantomJs. For installation and update, we suggest two
options:, (*12)
1st Option: Add the lines below in the composer.json file, so the installation and update process will occur every
time you execute the "composer install" or "composer update" commands., (*13)
"scripts": {
"post-install-cmd": [
"PhantomInstaller\\Installer::installPhantomJS"
],
"post-update-cmd": [
"PhantomInstaller\\Installer::installPhantomJS"
]
}
2st Option: If you do not want to always keep the latest PhantomJS version, one possibility is to add a new script
in composer.json as shown below:, (*14)
"scripts": {
"update-phantomjs": [
"PhantomInstaller\\Installer::installPhantomJS"
]
}
And run whenever you want to update the version of the executable the following command composer run-script update-phantomjs, (*15)
If you choose this option, you must run at least the first time for it to be installed., (*16)
How to use, (*17)
Generating our first report, (*18)
The use of this package is very simple, we will need two objects to generate a final file, the first one is Report,
with it we define the effective content of the report, the second is the Exporter, which receives a Report and is
responsible for handling the information and export to a final file., (*19)
Here is a simple example to generate a file:, (*20)
$report = new \Fireguard\Report\Report('<h1>Report Title</h1>');
$exporter = new \Fireguard\Report\Exporters\PdfExporter();
$file = $exporter->generate($report);
So at the end of the execution, in the variable $file we will have the actual path to the generated file., (*21)
Header and Footer, (*22)
For header and footer HTML, two variables are available in exporters that use paging, such as PdfExporter, numPage,
and totalPages, which contains the current page and the total pages of the page respectively.
To access them, you must enclose them by "@{{ }}", so the contents of the content will be automatically updated.
Below is a simple example that will use the header and footer;, (*23)
$html = file_get_contents('report.html');
$header = '
';
$header.= ' THE MANAGEMENT REPORT TITLE';
$header.= '
';
$footer = '
';
$footer.= ' Page @{{ numPage }} of @{{ totalPages }}';
$footer.= '
';
$report = new \Fireguard\Report\Report($html, $header, $footer);
$exporter = new \Fireguard\Report\Exporters\PdfExporter('.', 'report1-to-pdf');
$file = $exporter->generate($report);
With this example above we will find in the variable $file the path to the generated PDF file;, (*24)
Exporters, (*25)
As we saw in the previous examples, the export of the report requires an Exporter class. An Exporter is a specialized
class that implements an ExporterInterface interface and is responsible for catching a Report object and transforming it
into a finalized file., (*26)
At this point we have included in the package three Exporters, one for HTML, one for PDF and one for Images, it is
possible that in future new Exporters will be available, we also encourage you to develop new Exporters and, if
possible, contribute to the project., (*27)
Methods available in all Exports, (*28)
getPath(): Returns the location where the generated file will be saved;, (*29)
setPath($path, $mode = 0777): Sets the location where the file should be saved;, (*30)
getFileName(): Returns the name of the file to save;, (*31)
setFileName($fileName): Sets the name of the file to be saved;, (*32)
getFullPath(): Returns the complete path with the name of the file to be generated;, (*33)
compress($buffer): Returns a compressed string with no comments or line breaks;, (*34)
configure(array $config): Sets the settings to apply to the current report;, (*35)
generate(ReportInterface $report): Renders the report and returns a path to the generated file;, (*36)
response(ReportInterface $report, $forceDownload): Renders the report and returns an instance of the Symfony\Component\HttpFoundation\Response;, (*37)
Example of use with a fluent interface:, (*38)
$report = new \Fireguard\Report\Report('<h1>Report Title</h1>');
$exporter = new \Fireguard\Report\Exporters\PdfExporter();
// Example returning an HTTP response
$exporterGenerates report
->setPath('.') // Sets the save to the local folder
->setFileName('report.pdf') // Define as 'report.pdf' the name of the file to be generated
->configure(['footer' => ['height' => '30px']) // Set the footer size to 30px
->response($report) // Create an HTTP response
->send(); // Returns the response to the user
// Example generating a local file
$file = $exporter
->setPath('.') // Sets the save to the local folder
->setFileName('report.pdf') // Define as 'report.pdf' the name of the file to be generated
->configure(['footer' => ['height' => '30px']) // Set the footer size to 30px
->generate($report); // Generates report
HtmlExport, (*39)
For exporting files in HTML format, in addition to the standard methods, some others are available, below all are
listed with a brief description of their function:, (*40)
saveFile($content): Saves the HTML file and returns the full path to the generated file;, (*41)
PdfExport, (*42)
For exporting files in PDF format, in addition to the standard methods, some others are available, below all are
listed with a brief description of their function:, (*43)
getFormat(): Returns the defined paper size;, (*44)
setFormat($format): Sets a paper size to be exported. (Valid Formats: 'A4', 'A3', 'Letter'), (*45)
getOrientation(): Returns the orientation of the defined paper;, (*46)
setOrientation($orientation): Sets the orientation of the paper to be exported. (Valid Orientations: 'landscape', 'portrait'), (*47)
getMargin(): Returns the defined paper margin;, (*48)
setMargin($margin): Sets the paper margin to be exported;, (*49)
getBinaryPath(): Returns the path to the PhantomJS binary in the application;, (*50)
setBinaryPath($binaryPath): Sets the path to the PhantomJS binary file in the application;, (*51)
getCommandOptions(): Returns the parameters to be executed with the PhantomJS for export;, (*52)
setCommandOptions(array $options): Sets the parameters to be executed with the PhantomJS for export;, (*53)
addCommandOption($option, $value): Adds a new parameter to run with PhantomJS for export;, (*54)
getHeaderHeight(): Returns the size of the header defined;, (*55)
getFooterHeight(): Returns the size of the footer defined;, (*56)
ImageExport, (*57)
For exporting files in IMAGE format, in addition to the standard methods, some others are available, below all are
listed with a brief description of their function:, (*58)
getFormat(): Returns the defined paper size;, (*59)
setFormat($format): Sets a paper size to be exported. (Valid Formats: 'A4', 'A3', 'Letter'), (*60)
getOrientation(): Returns the orientation of the defined paper;, (*61)
setOrientation($orientation): Sets the orientation of the paper to be exported. (Valid Orientations: 'landscape', 'portrait'), (*62)
getMargin(): Returns the defined paper margin;, (*63)
setMargin($margin): Sets the paper margin to be exported;, (*64)
getBinaryPath(): Returns the path to the PhantomJS binary in the application;, (*65)
setBinaryPath($binaryPath): Sets the path to the PhantomJS binary file in the application;, (*66)
getCommandOptions(): Returns the parameters to be executed with the PhantomJS for export;, (*67)
setCommandOptions(array $options): Sets the parameters to be executed with the PhantomJS for export;, (*68)
addCommandOption($option, $value): Adds a new parameter to run with PhantomJS for export;, (*69)
getHeaderHeight(): Returns the size of the header defined;, (*70)
getFooterHeight(): Returns the size of the footer defined;, (*71)
Laravel, (*72)
The steps described below are optional and can only make it easier for those who want to use this package with Laravel 5., (*73)
Registering Service Provider, (*74)
In the config\app.php configuration file, register above the providers of your application as follows:, (*75)
'providers' => [
Fireguard\Report\Laravel\ReportServiceProvider::class,
...
]
Publishing the configuration file, (*76)
To publish the configuration file you must use the following command:, (*77)
php artisan vendor:publish --provider="Fireguard\Report\Laravel\ReportServiceProvider"
Examples of use with Laravel (Dependency Injection), (*78)
With the registration of the service provider, you can now use the dependency injection of Laravel to solve the
exporters, already bringing them ready and configured with the application configuration file., (*79)
For dependency injection four classes are available, one interface and three concrete, the default interface is solved
for the concrete PdfExporter class, which can be changed in the default-exporter parameter of the configuration
file report.php generated in the integration. See below some examples of use., (*80)
Exporter Interface, (*81)
public function index (\Fireguard\Report\Exporters\ExporterInterface $exporter)
{
$html = view()->make('welcome')->render();
// Option 1
return $exporter
->response(new Report($html))
->send();
// Option 2
$file = $exporter->generate(new Report($html));
$headers = [
'Content-type' => mime_content_type($file),
'Content-Transfer-Encoding' => 'binary',
'Content-Length' => filesize($file),
'Accept-Ranges' => 'bytes'
];
// If you want to directly display the file
return response()->make(file_get_contents($file), 200, $headers);
// If you want to force download
// return response()->download($file, 'report.pdf', $headers);
}
HtmlExporter Class, (*82)
public function index (\Fireguard\Report\Exporters\HtmlExporter $exporter)
{
$html = view()->make('welcome')->render();
// Option 1
return $exporter
->response(new Report($html))
->send();
// Option 2
$file = $exporter->generate(new Report($html));
// If you want to directly display the file
// return response()->make(file_get_contents($file), 200);
// If you want to force download
return response()->download($file, 'report.html', []);
}
PdfExporter Class, (*83)
public function index (\Fireguard\Report\Exporters\PdfExporter $exporter)
{
$html = view()->make('welcome')->render();
// Option 1
return $exporter
->response(new Report($html))
->send();
// Option 2
$file = $exporter->generate(new Report($html));
$headers = [
'Content-type' => 'application/pdf',
'Content-Transfer-Encoding' => 'binary',
'Content-Length' => filesize($file),
'Accept-Ranges' => 'bytes'
];
// If you want to directly display the file
return response()->make(file_get_contents($file), 200, $headers);
// If you want to force download
// return response()->download($file, 'report.pdf', $headers);
}
ImageExporter Class, (*84)
public function index (\Fireguard\Report\Exporters\ImageExporter $exporter)
{
$html = view()->make('welcome')->render();
// Option 1
return $exporter
->response(new Report($html))
->send();
// Option 2
$file = $exporter->generate(new Report($html));
$headers = [
'Content-type' => 'image/jpg',
'Content-Length' => filesize($file),
];
// If you want to directly display the file
return response()->make(file_get_contents($file), 200, $headers);
// If you want to force download
// return response()->download($file, 'report.jpg', $headers);
}
Other usage examples
Generating an HTML report
Generating an PDF report
Generating an IMAGE report
Sample ticket generated with this package
Created by Fireguard Sistemas http://fireguard.com.br, (*85)
Wallogit.com
