README

Other languages for this documentation: PORTUGUÊS

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.

# Summary

Installation
- Installing and Updating PhantomJs
How to use
Laravel
Other usage examples

Installation

The FireGuard Report can be installed through the composer.

In order for the package to be automatically added to your composer.json file, run the following command:

  composer require fireguard/report

Or if you prefer, add the following snippet manually:

{
  "require": {
    ...
    "fireguard/report": "^0.1"
  }
}

Installing and Updating PhantomJs

To generate the PDF files and Images, this package is used by PhantomJs. For installation and update, we suggest two options:

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.

  "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:

  "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

If you choose this option, you must run at least the first time for it to be installed.

How to use

Generating our first report

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.

Here is a simple example to generate a file:

    $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.

Header and Footer

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;

  $html   = file_get_contents('report.html');
  
  $header = '<div style="text-align: center;font-size: 20px; border-bottom: 1px #eeeeee solid; padding: 1px; ">';
  $header.= '    <strong>THE MANAGEMENT REPORT TITLE</strong>';
  $header.= '</div>';

  $footer = '<div style="text-align: right;font-size: 10px; border-top: 1px #eeeeee solid; padding: 2px;">';
  $footer.= '    Page <span>@{{ numPage }} of @{{ totalPages }}</span>';
  $footer.= '</div>';
  
  $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;

Exporters

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.

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.

Methods available in all Exports

getPath(): Returns the location where the generated file will be saved;

setPath($path, $mode = 0777): Sets the location where the file should be saved;

getFileName(): Returns the name of the file to save;

setFileName($fileName): Sets the name of the file to be saved;

getFullPath(): Returns the complete path with the name of the file to be generated;

compress($buffer): Returns a compressed string with no comments or line breaks;

configure(array $config): Sets the settings to apply to the current report;

generate(ReportInterface $report): Renders the report and returns a path to the generated file;

response(ReportInterface $report, $forceDownload): Renders the report and returns an instance of the Symfony\Component\HttpFoundation\Response;

Example of use with a fluent interface:

$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

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:

saveFile($content): Saves the HTML file and returns the full path to the generated file;

PdfExport

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:

getFormat(): Returns the defined paper size;

setFormat($format): Sets a paper size to be exported. (Valid Formats: 'A4', 'A3', 'Letter')

getOrientation(): Returns the orientation of the defined paper;

setOrientation($orientation): Sets the orientation of the paper to be exported. (Valid Orientations: 'landscape', 'portrait')

getMargin(): Returns the defined paper margin;

setMargin($margin): Sets the paper margin to be exported;

getBinaryPath(): Returns the path to the PhantomJS binary in the application;

setBinaryPath($binaryPath): Sets the path to the PhantomJS binary file in the application;

getCommandOptions(): Returns the parameters to be executed with the PhantomJS for export;

setCommandOptions(array $options): Sets the parameters to be executed with the PhantomJS for export;

addCommandOption($option, $value): Adds a new parameter to run with PhantomJS for export;

getHeaderHeight(): Returns the size of the header defined;

getFooterHeight(): Returns the size of the footer defined;

ImageExport

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:

getFormat(): Returns the defined paper size;

setFormat($format): Sets a paper size to be exported. (Valid Formats: 'A4', 'A3', 'Letter')

getOrientation(): Returns the orientation of the defined paper;

setOrientation($orientation): Sets the orientation of the paper to be exported. (Valid Orientations: 'landscape', 'portrait')

getMargin(): Returns the defined paper margin;

setMargin($margin): Sets the paper margin to be exported;

getBinaryPath(): Returns the path to the PhantomJS binary in the application;

setBinaryPath($binaryPath): Sets the path to the PhantomJS binary file in the application;

getCommandOptions(): Returns the parameters to be executed with the PhantomJS for export;

setCommandOptions(array $options): Sets the parameters to be executed with the PhantomJS for export;

addCommandOption($option, $value): Adds a new parameter to run with PhantomJS for export;

getHeaderHeight(): Returns the size of the header defined;

getFooterHeight(): Returns the size of the footer defined;

Laravel

The steps described below are optional and can only make it easier for those who want to use this package with Laravel 5.

Registering Service Provider

In the config\app.php configuration file, register above the providers of your application as follows:

'providers' => [
    Fireguard\Report\Laravel\ReportServiceProvider::class,
    ...
]

Publishing the configuration file

To publish the configuration file you must use the following command:

php artisan vendor:publish --provider="Fireguard\Report\Laravel\ReportServiceProvider"

Examples of use with Laravel (Dependency Injection)

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.

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.

Exporter Interface

    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

    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

    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

    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

fireguard / report

Maintainers

Details