README

此文档的其他语言版本：葡萄牙语

Fireguard Report 是一个PHP报告管理包，旨在帮助您使用独特、集成和简单的界面以多种格式（如HTML、PDF和图像）导出信息。

# 摘要

安装
- 安装和更新PhantomJs
如何使用
Laravel
其他使用示例

安装

FireGuard Report 可以通过composer安装。

为了将软件包自动添加到您的composer.json文件中，请运行以下命令

  composer require fireguard/report

或者，如果您愿意，可以手动添加以下片段

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

安装和更新PhantomJs

为了生成PDF文件和图像，该软件包使用PhantomJs。对于安装和更新，我们建议以下两种方案

第一种方案： 在composer.json文件中添加以下行，这样每次执行"composer install"或"composer update"命令时，都会执行安装和更新过程。

  "scripts": {
    "post-install-cmd": [
      "PhantomInstaller\\Installer::installPhantomJS"
    ],
    "post-update-cmd": [
      "PhantomInstaller\\Installer::installPhantomJS"
    ]
  }

第二种方案： 如果您不想始终保留最新的PhantomJs版本，一个可能性是在composer.json中添加一个新的脚本，如下所示

  "scripts": {
    "update-phantomjs": [
      "PhantomInstaller\\Installer::installPhantomJS"
    ]
  }

每次您想要更新可执行文件的版本时，运行以下命令 composer run-script update-phantomjs

如果您选择此选项，至少需要运行一次才能进行安装。

如何使用

生成我们的第一个报告

使用此软件包非常简单，我们需要两个对象来生成一个最终文件，第一个是Report，用它定义报告的有效内容，第二个是Exporter，它接收一个Report并将负责处理信息和导出到最终文件。

以下是一个简单的示例来生成文件

    $report     = new \Fireguard\Report\Report('<h1>Report Title</h1>');
    $exporter   = new \Fireguard\Report\Exporters\PdfExporter();
    $file       = $exporter->generate($report);

因此，在执行结束时，在变量 $file 中，我们将有生成的文件的实际路径。

页眉和页脚

对于页眉和页脚HTML，在导出器中提供了两个变量，例如PdfExporter，numPage 和 totalPages 分别包含当前页和总页数。要访问它们，必须用 "@{{ }}" 包围，这样内容就会自动更新。以下是一个简单的示例，它将使用页眉和页脚

  $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);

以上示例中，我们将在变量 $file 中找到生成的 PDF 文件的路径；

导出器

正如我们在之前的示例中所见，导出报告需要导出器类。导出器是一个专门实现的导出器接口的类，它负责捕获报告对象并将其转换为最终文件。

到目前为止，我们已经在该包中包含了三个导出器，一个用于 HTML，一个用于 PDF，一个用于图像，未来可能会提供新的导出器，我们也鼓励您开发新的导出器，并在可能的情况下为项目做出贡献。

所有导出器中可用的方法

getPath()：返回要保存生成的文件的地址；

setPath($path, $mode = 0777)：设置文件应保存的地址；

getFileName()：返回要保存的文件名；

setFileName($fileName)：设置要保存的文件名；

getFullPath()：返回包含要生成的文件名的完整路径；

compress($buffer)：返回一个没有注释或换行符的压缩字符串；

configure(array $config)：设置应用于当前报告的设置；

generate(ReportInterface $report)：渲染报告并返回生成文件的路径；

response(ReportInterface $report, $forceDownload)：渲染报告并返回一个 Symfony\Component\HttpFoundation\Response 实例；

使用流畅接口的示例

$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

对于以 HTML 格式导出文件，除了标准方法外，还有一些其他方法，下面列出所有方法及其简要功能描述

saveFile($content)：保存 HTML 文件并返回生成文件的完整路径；

PdfExport

对于以 PDF 格式导出文件，除了标准方法外，还有一些其他方法，下面列出所有方法及其简要功能描述

getFormat()：返回定义的纸张大小；

setFormat($format)：设置要导出的纸张大小。（有效格式：'A4'，'A3'，'Letter'）

getOrientation()：返回定义的纸张方向；

setOrientation($orientation)：设置要导出的纸张方向。（有效方向：'landscape'，'portrait'）

getMargin()：返回定义的纸张边距；

setMargin($margin)：设置要导出的纸张边距；

getBinaryPath()：返回应用程序中 PhantomJS 二进制的路径；

setBinaryPath($binaryPath)：设置应用程序中 PhantomJS 二进制文件的路径；

getCommandOptions()：返回用于导出时与 PhantomJS 执行的参数；

setCommandOptions(array $options)：设置用于导出时与 PhantomJS 执行的参数；

addCommandOption($option, $value)：为运行 PhantomJS 导出添加新的参数；

getHeaderHeight()：返回定义的页眉大小；

getFooterHeight()：返回定义的页脚大小；

ImageExport

对于以 IMAGE 格式导出文件，除了标准方法外，还有一些其他方法，下面列出所有方法及其简要功能描述

getFormat()：返回定义的纸张大小；

setFormat($format)：设置要导出的纸张大小。（有效格式：'A4'，'A3'，'Letter'）

getOrientation()：返回定义的纸张方向；

setOrientation($orientation)：设置要导出的纸张方向。（有效方向：'landscape'，'portrait'）

getMargin()：返回定义的纸张边距；

setMargin($margin)：设置要导出的纸张边距；

getBinaryPath()：返回应用程序中 PhantomJS 二进制的路径；

setBinaryPath($binaryPath)：设置应用程序中 PhantomJS 二进制文件的路径；

getCommandOptions()：返回用于导出时与 PhantomJS 执行的参数；

setCommandOptions(array $options)：设置用于导出时与 PhantomJS 执行的参数；

addCommandOption($option, $value)：为运行 PhantomJS 导出添加新的参数；

getHeaderHeight()：返回定义的页眉大小；

getFooterHeight()：返回定义的页脚大小；

Laravel

以下描述的步骤是可选的，仅为了让想使用此包与Laravel 5配合的人更容易。

注册服务提供者

在 config\app.php 配置文件中，将以下内容注册到您应用程序的提供者之上：

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

发布配置文件

要发布配置文件，您必须使用以下命令：

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

与Laravel（依赖注入）的使用示例

注册服务提供者后，现在您可以使用Laravel的依赖注入来解决导出器，它们已经准备好并配置好，与应用程序配置文件一起。

对于依赖注入，有四个类可用：一个接口和三个具体实现。默认接口为PdfExporter类解决，可以在集成时生成的配置文件 report.php 的 default-exporter 参数中更改。以下是一些使用示例。

导出器接口

    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类

    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类

    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类

    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);
    }

其他使用示例

生成HTML报告
生成PDF报告
生成图像报告
使用此软件包生成的示例票据

由Fireguard Sistemas创建 http://fireguard.com.br

fireguard / report

维护者

详细信息