README

Reptor

基于PhpSpreadsheet的报告生成器

PHPSpreadsheet报告生成器是一个面向PHP的解决方案，旨在帮助用户无缝生成报告。它集成了PHP 8.1支持下的PHPSpreadsheet库的现有特性，确保使用基于Excel模板的文件生成动态XLSX报告。

该项目旨在通过将原始数据转换为全面、易于消化的信息，并利用Symfony表达式语言的强大表达能力，革新PHP世界的报告生成方式。它便于包含数据源或数据集，成为满足各种报告需求的通用工具。

无论您是个人寻求对数据进行理解，还是企业寻求简化复杂数据分析，PHPSpreadsheet报告生成器都是一个非常有价值的工具，可用于获取见解、制定战略决策或简单地理解大量信息。

该项目深受alhimik1986和他的PHP Excel Templator库的启发。

关键特性

增强的报告生成：高效地在XLSX、PDF、HTML和其他格式中创建报告。
Symfony表达式语言：利用Symfony组件的力量，简化对对象图的操作。
数据源或数据集：包括众多数据终点或大型数据集，以生成符合您喜好和要求的报告。
模板语言可扩展性：扩展模板语言的能力，允许创建更多个性化且复杂的模板，适应高度定制和功能。
聚合函数：使用聚合函数如sum、avg等，生成具有更高复杂性和功能性的报告。
按组：按特定列分组数据，可以生成更有组织和结构的报告。
灵活的参数声明：参数或属性（如数据源、数据集等）可以在电子表格模板本身中指定，或在运行时声明。这提供了更大的灵活性和定制性。
单元格公式中的原生PHP函数或对象：使用原生PHP函数或对象的能力。
单元格表达式中的Excel公式：使用单元格表达式中的Excel公式，并且可以与基于Symfony表达式语言扩展的或原生PHP函数结合使用。
用户定义的单元格范围作为处理的基本单位：通过将单元格范围解释为处理的基本单位来控制输入数据处理。

安装

Reptor可以通过Git克隆获取并安装，随后进行Composer安装。请按照以下步骤操作

如果您尚未安装Git或Composer，请首先下载并安装它们。请使用Git和Composer的官方下载页面。
安装Git和Composer后，将Reptor仓库克隆到您的本地环境中
```
git clone https://github.com/rixbeck/reptor.git
```
导航到克隆的仓库并安装依赖项
```
cd reptor
composer install
```

请确保您的PHP环境满足composer.json文件中指定的要求，包括启用的扩展，如PDO、JSON和SQLite3。完成这些步骤后，Reptor就可以在您的项目中使用了。

作为Composer依赖项使用

您还可以将Reptor作为依赖项包含在您的PHP项目中，而不是将其作为独立项目使用

导航到您现有的PHP项目目录，并打开终端（或命令提示符）
```
cd /path/to/your/php/project
```
使用以下composer命令将Reptor添加为项目的依赖项。
```
composer require rixbeck/reptor
```

这就完成了！您现在已成功将Reptor添加为PHP项目的依赖项。

Reptor背后的概念：报表生成中的模板化与脚本化

在生成数据驱动报表时，有根本两种方法：脚本化和模板化。

脚本化

脚本化涉及编写自定义代码来处理数据和格式化报表。它提供了灵活性，但需要大量的编程，这使得没有编程专长用户的工作变得复杂和耗时。

模板化

相比之下，模板化（Reptor采用的方法），允许用户在熟悉的界面中直接定义报表布局和格式 - 一个Excel文件。这种方法直观且用户友好，显著降低了学习曲线。

为什么选择使用Excel进行模板化？

熟悉度：Excel是一个广泛使用的工具，拥有许多用户熟悉的界面，使其成为设计报表模板的理想平台。
灵活性：Excel的本地功能（如单元格、公式和格式化选项）为定义数据应如何呈现提供了很大的灵活性。
效率：通过使用Excel进行模板化，用户可以快速原型设计和修改报表设计，而无需深入了解复杂的编程。
动态报表：使用Excel，我们可以创建动态模板，这些模板可以自动调整并填充数据，为生成定制报表提供了一种强大的方式。

通过Reptor，我们将两者的优点结合起来：通过Excel进行模板化的便捷性和PHP处理和生成复杂报表的能力。

使用Excel模板进行高级单元格和行样式设置

使用Excel模板在Reptor中的一大优点是其提供的广泛样式功能

单元格样式：用户可以利用Excel丰富的单元格格式选项来定义单个单元格的外观。这包括字体样式、颜色、边框和背景填充，允许创建高度定制的、视觉上吸引人且易于阅读的报表。
行和列格式化：除了单个单元格之外，Reptor还允许对整个行和列进行样式设置。此功能对于在处理大型数据集时保持一致性和清晰度至关重要。
条件格式化：Excel的条件格式化可以根据单元格包含的数据动态地设置单元格样式。这为报表增加了交互性的一层，使用户能够快速识别趋势、异常或关键指标。
易用性：通过利用Excel熟悉的界面，用户可以在没有任何额外的学习曲线的情况下设置报表样式，使其对技术和非技术用户都易于访问。

通过Reptor，这些样式功能无缝集成到报表生成过程中，确保最终输出不仅信息丰富，而且在美学上令人愉悦，并符合特定的展示需求。

在Excel单元格中利用表达式语言

Reptor利用Symfony表达式语言的力量来增强Excel模板的动态性

单元格中的表达式语言：用户可以直接将表达式嵌入到Excel单元格中。这些基于Symfony强大框架的表达式可以动态地操纵和展示数据，为您的报告增加显著的功能。
变量和对象集成：可以在这些表达式中使用各种用户定义或预定义的对象和变量。这些可以在Excel文档的自定义属性中直接定义，也可以通过初始化引导脚本或在任何报告生成预处理阶段定义。
适配器和数据源：Reptor通过其可适应的接口支持各种数据源，包括PDO、Socket、Array等，如Reptor/Adaptor/Datasource命名空间中所示。这种灵活性允许集成不同的数据集。
统一的连接字符串：数据源使用统一的连接字符串连接，类似于Java或PHP DSN，简化了链接和利用不同数据集的过程。

通过这些功能，Reptor允许广泛的定制和动态数据处理，使用户能够直接从Excel创建高度复杂和定制的报告。

渲染哲学：基于Excel模板的概念

Reptor引入了一种独特的处理Excel模板的方法，围绕“单元”的概念

单元 - 模板的核心：在Reptor中，“单元”是相互关联的表达式的基本单位，对于理解同一数据行中的表达式如何交互至关重要。
使用命名范围定义单元：用户使用Excel中的命名范围定义这些“单元”。这种方法组织模板并为其处理做准备。
顺序处理和评估：模板处理涉及顺序评估这些单元。在这个过程中，评估后的表达式转换为对象。
单元的优先级和类型：每个对象都有一个类型，这些类型具有固有的优先级。对象的优先级决定了评估过程中相应单元的类型。
由单元类型驱动的渲染逻辑：一旦单元被分类，渲染逻辑就接管了，由每个单元的类型驱动。这一步骤确保最终输出与模板的预期结构和格式相符。

理解Excel模板中的单元

在Reptor系统中，“单元”封装了一组逻辑上相关且一起处理的表达式，以产生报告的连贯部分。

以下是它是如何工作的

绑定表达式：如图所示，表达式绑定在Excel中的命名范围内，形成一个“单元”。这确保了属于同一概念组的数据被一起处理。
命名范围：使用如unit_partner_group之类的命名范围有助于有效地识别和处理这些单元，将相关的表达式保持在一起。
处理多个单元：用户可以在Excel模板中定义多个单元，每个单元代表报告的不同部分或不同的数据分组。
顺序处理：Reptor按顺序遍历这些单元，处理其单元格，直到最后一个单元格。之后，发出事件，指示数据集迭代器可以获取下一数据行（如果有的话）。因此，以这种方式逐行处理，只要任何单元中还有剩余的引用数据集行。
表达式语法：单元格内的语法{{activity.GroupBy('partner')}}是对Reptor提供的引用对象进行评估。这允许基于数据生成动态内容。

理解单元格中基于模板的表达式语言

Reptor的模板系统允许使用受Symfony启发的表达式语言，在Excel单元格中直接进行复杂的数据操作。该系统的灵活性源于定义属性的能力，这些属性是用于渲染表达式的基变量。

brix\Reptor\Bootstrap类设置了Reptor环境，包括

属性初始化：这些是在模板系统中可用于所有表达式的变量。它们可以是默认属性，也可以通过addProperties方法进行扩展。
表达式语言设置：该类初始化ExpressionLanguage组件，注册了各种扩展，以增强其功能，如CoreExtension、DataExtension和UtilityExtension。
数据源集成：通过DataExtension，Reptor可以连接到各种数据源，如数据库、CSV、JSON和数组。它将这些数据源映射为模板引擎可读的对象。
模板处理：初始化后的Templator对象处理Excel模板，调用表达式并渲染最终输出。
上下文提供：ContextProvider管理单元格渲染过程中的上下文，确保渲染过程中可用适当的属性。
单位管理：UnitManager帮助管理命名范围，称为“单位”，它们将相关表达式分组以进行连贯处理。

此初始化过程至关重要，因为它设置了整个模板引擎，该引擎为Reptor中报告的动态渲染提供动力，利用Symfony表达式语言在Excel单元格中评估复杂表达式。

除了设置Reptor环境外，项目还包括一个bin/目录，其中包含用于简化应用程序初始化和配置的脚手架脚本。此目录包含示例和样板代码，帮助用户快速设置他们的报告项目。

脚手架脚本：这些是在bin/文件夹中预先编写的脚本，为常见任务提供模板，使用户能够轻松地为应用程序搭建脚手架。
快速入门示例：新用户可以参考这些示例，了解如何启动他们的Reptor应用程序，配置数据源和定义属性。
定制和可扩展性：虽然示例提供了一种快速入门的方式，但它们也被设计为易于定制，为用户提供一个起点，以根据他们的特定报告需求定制应用程序。

此脚手架方法旨在简化设置过程，使用户能够轻松地使用Reptor开始他们的报告生成项目。

关于项目的状态

提供的内容是Reptor项目和其底层结构的简要介绍。它旨在作为快速入门指南，使用户能够快速了解系统的功能，尤其是基于表达式语言的Excel单元格模板。

尽管项目仍处于早期阶段，但它功能齐全，可以用于生成报告。当前版本是0.1.0-beta，项目处于积极开发中。我们欢迎社区提供反馈、问题报告和贡献，以帮助改进项目并使其对用户更加易于访问。

接下来是什么？

我们目前正在主要专注于以下方面的文档

详细文档：我们正在创建一份全面文档，它将涵盖项目的所有方面，包括详细说明、示例和最佳实践。
贡献指南：我们也在编写一个贡献指南，以帮助用户为项目做出贡献，使其更易于社区使用。
发布计划：我们计划在未来几个月内发布项目的第一个稳定版本。
测试自动化：我们正在开发一个测试自动化框架，以确保项目的稳定性和可靠性。在这个领域任何形式的帮助都将非常感激。
错误修复：我们正在积极修复社区报告的错误和问题。请随时报告您遇到的任何问题。
功能请求：我们也欢迎来自社区的功能请求和建议。请随时与我们分享您的想法。

rixbeck / reptor

维护者

详情