README

一个节省时间的PHP报告库。

注意：此包目前为alpha版本且不稳定。随着我们使用它并确定首次发布的最终功能集，我们将把1.0.0作为我们的第一个稳定标签。

安装

在常用位置或您的项目中安装composer

curl -s http://getcomposer.org/installer | php

创建composer.json文件如下

{
    "require": {
        "rootwork/php-report-generator": "0.1.0"
    }
}

运行composer安装器

php composer.phar install

概念

此库旨在为开发者提供一种封装报告的方法，只需一个类即可。

核心方法

您的报告类应扩展Rootwork\Report\ReportAbstract并实现Rootwork\Report\ReportInterface。这将为您在类中提供两个抽象公共方法来实现：define()和run()。

定义、列和变量

所有报告都有一个Definition对象，用于定义报告的功能。您添加Column实例来定义您的列，如果您想将变量参数传递给报告（例如，SQL WHERE子句），则可以添加可选的Variable实例。

Column($name, $display, $type, [$format = null, $total = false])

Variable($name, $display, $type, [$default = null, array $options = [], $format = null])

数据源

此库目前对数据源不可知。您可以传递并使用您喜欢的任何数据源，只要在run()方法的末尾设置一个rows数组即可。

您可以使用$options数组将数据源和其他依赖项传递给构造函数，并在initialize()方法中使用它们。构造函数将使用$options数组调用initialize()。不建议重写__construct。

用法

示例报告类

<?php
use Rootwork\Report\ReportAbstract;
use Rootwork\Report\ReportInterface;
use Rootwork\Report\Column;
use Rootwork\Report\Variable;

class MyReport extends ReportAbstract implements ReportInterface
{
    
    /**
     * @var PDO $pdo
     */
    protected $pdo;

    /**
     * Initialize the report class with any custom dependencies you need.
     *
     * @param array $options
     */
    public function initialize(array $options = [])
    {
        $this->pdo = $options['pdo'];
    }

    /**
     * Method for setting up the report definition.
     */
    protected function define()
    {
        $salesReps = [
            'tstark'  => 'Tony Stark',
            'bbanner' => 'Bruce Banner',
            'nfury'   => 'Nick Fury',
        ];
        
        $this->getDefinition()
            ->setTitle('My Sales Report')
            ->addColumn(new Column(
                'orderId', 'Order ID', Column::TYPE_INTEGER, Column::FORMAT_NUMBER
            ))
            ->addColumn(new Column(
                'date', 'Date', Column::TYPE_DATE, 'Y-m-d'
            ))
            ->addColumn(new Column(
                'customer', 'Customer', Column::TYPE_STRING
            ))
            ->addColumn(new Column(
                'salesRep', 'Sales Rep', Column::TYPE_STRING
            ))
            ->addColumn(new Column(
                'amount', 'Amount', Column::TYPE_FLOAT, Column::FORMAT_CURRENCY, true
            ))
            ->addVariable(new Variable(
                'startDate', 'Start Date', Variable::TYPE_DATE, date('Y-m-d'), [], 'Y-m-d'
            ))
            ->addVariable(new Variable(
                'salesRep', 'Sales Rep', Variable::TYPE_SELECT, 'tstark', $salesReps
            ));
    }

    /**
     * Run the report and return results.
     *
     * @return array[]
     */
    public function run()
    {
        $values = $this->getDefinition()->getVariableValues();
        $sql = "SELECT * FROM orders WHERE start_date >= :startDate AND sales_rep = :salesRep";
        $sth = $this->pdo->prepare($sql);
        $sth->execute($values);
        $results = $sth->fetchAll(PDO::FETCH_ASSOC);
        $rows = [];
        
        foreach ($results as $result) {
            $row = [
                'orderId'  => $result['order_id'],
                'date'     => date('Y-m-d', strtotime($result['date'])),
                'customer' => $result['customer'],
                'salesRep' => $result['sales_rep'],
                'amount'   => number_format($result['amount'], 2, ''),
            ];
            $rows[] = $row;
        }
        
        // IMPORTANT: You must set $this->rows as an associative array of results
        $this->rows = $rows;
        return $this->rows;
    }
}

使用报告类

您可以将报告定义序列化为JSON。如果您想自动生成运行报告的表单，这将非常有用。

$report = new MyReport(['pdo] => $pdo]);
$definition = $report->getDefinition();
echo json_encode($definition);

结果

{
    "title": "My Sales Report",
    "columns": [
        {
            "name": "orderId",
            "display": "Order ID",
            "type": "integer",
            "format": "number",
            "total": false
        },
        {
            "name": "date",
            "display": "Date",
            "type": "date",
            "format": "Y-m-d",
            "total": false
        },
        {
            "name": "customer",
            "display": "Customer",
            "type": "string",
            "format": null,
            "total": false
        },
        {
            "name": "salesRep",
            "display": "Sales Rep",
            "type": "string",
            "format": null,
            "total": false
        },
        {
            "name": "amount",
            "display": "Amount",
            "type": "float",
            "format": "currency",
            "total": true
        }
    ],
    "variables": [
        {
            "name": "startDate",
            "display": "Start Date",
            "type": "date",
            "default": "2017-10-03",
            "options": [],
            "format": "Y-m-d"
        },
        {
            "name": "salesRep",
            "display": "Sales Rep",
            "type": "select",
            "default": "tstark",
            "options": {
                "tstark": "Tony Stark",
                "bbanner": "Bruce Banner",
                "nfury": "Nick Fury"
            },
            "format": null
        }
    ]
}

run()方法将返回报告行，但更有用的输出是将报告编码为JSON。

$report = new MyReport(['pdo] => $pdo]);
$report->setParameters(['startDate' => '2017-01-01', 'salesRep' => 'bbanner']);
$report->run();
echo json_encode($report);

结果

{
    "title": "My Sales Report",
    "columns": [
        {
            "name": "Order ID",
            "type": "integer",
            "format": "number"
        },
        {
            "name": "Date",
            "type": "date",
            "format": "Y-m-d"
        },
        {
            "name": "Customer",
            "type": "string",
            "format": null
        },
        {
            "name": "Sales Rep",
            "type": "string",
            "format": null
        },
        {
            "name": "Amount",
            "type": "float",
            "format": "currency"
        }
    ],
    "rows": [
        {
            "orderId": 1,
            "date": "2017-01-14",
            "customer": "S.H.I.E.L.D.",
            "salesRep": "bbanner",
            "amount": "1000.00"
        },
        {
            "orderId": 2,
            "date": "2017-02-03",
            "customer": "US DOD",
            "salesRep": "bbanner",
            "amount": "2500.00"
        },
        {
            "orderId": 3,
            "date": "2017-03-23",
            "customer": "Acme, Inc.",
            "salesRep": "bbanner",
            "amount": "599.00"
        }
    ],
    "paging": {
      "totalRows": 3,
      "limit": 10,
      "page": 1,
      "totalPages": 1
    },
    "totals": [
        null,
        null,
        null,
        null,
        "4099.00"
    ]
}