README

需求

Craft CMS v5.0.0+
PHP 8.2+

安装

请将以下内容添加到您的 composer.json 需求中。确保将版本号调整为您要安装的版本。

"masugadesign/labreports": "5.0.1",

配置

要自定义Lab Reports配置，在您的Craft config文件夹中创建一个 labreports.php 文件。开始时，您可以复制插件 src 文件夹中包含的 config.php 文件的全部内容。

Lab Reports具有以下配置选项

debug

将debug设置为 true 以启用一些高级插件日志记录。这有助于诊断配置/运行报告时的问题。

fileStorageFolder

指定一个不带尾随斜杠的可写文件夹的完整系统路径。Lab Reports将在此处存储生成的报告文件。如果不想覆盖默认位置，不要在插件配置文件中包含此项，默认位置是Craft存储文件夹中的 "labreports" 子文件夹。

functions

这是高级报告中使用的PHP格式化函数数组。

<?php

return [
	'debug' => true,

	'fileStorageFolder' => '/home/ubuntu/sites/example.com/reports',

	'functions' => [
		'entryDump' => function ($entry) {
			return [
				(int) $entry->id,
				$entry->title,
				$entry->dateCreated->format('F j, Y g:i a')
			];
		}
	]
];

调试

Lab Reports将大多数错误/异常写入到 storage/logs/labreports.log 文件。在某些情况下，一些错误可能会绕过该日志，Craft会将它们写入到 web.log 或 queue.log 文件。

当Lab Reports的 debug 配置选项启用时，插件会记录额外的信息。每个调试日志行都以 [DEBUG] 开头。

在报告构建过程中发生的错误/异常存储在 Report 元素的 statusMessage 属性中。该值将在控制面板的 Report 详细页面中显示。任何导致“错误”状态的报告构建都应该有一个可能有助于诊断报告模板或配置的 statusMessage 值。

基本报告

基本报告是一个基于模板的报告，针对较小的数据导出（< 3000行）。这些报告在生成CSV导出时一次性将整个查询结果加载到内存中。

配置

要配置基本报告，从Craft控制面板中的主Lab Reports页面单击“新建报告”按钮。在表单中，选择报告的类型为“基本”。输入标题、描述（可选）以及到您的Craft主模板文件夹中模板的相对路径。单击“创建”按钮。

例如，我们将创建一个基本报告，导出一些条目元数据。报告模板可能如下所示

{#
Report Title : Books Entries Export
Report Description : A very basic export of all the Books entries.
Report Template : _reports/booksBasic
#}

{# Initialize the rows array by placing an array of column headers/labels in it. #}
{% set rows = [[
	'ID',
	'Title',
	'Date Published',
	'Author',
	'Cover Image'
]] %}

{# Construct a query and execute it with .all(). #}
{% set entries = craft.entries.section('books')
	.with(['bookAuthor','coverImage'])
	.orderBy('title')
	.all() %}

{# Loop through the entries and add them to the report rows array. #}
{% for entry in entries %}
	{% set author = entry.bookAuthor[0] ?? null %}
	{% set coverImage = entry.coverImage[0] ?? null %}
	{% set rows = rows|merge([[
		entry.id,
		entry.title,
		entry.bookPublishDate|date('F j, Y g:i A'),
		(author ? author.title : ''),
		(coverImage ? coverImage.url : '')
	]]) %}
{% endfor %}

{# Tell Lab Reports to construct the CSV File and save a new Report element. #}
{% do report.build(rows) %}

在模板中自动定义了 report 变量。它包含一个Lab Reports Report 元素实例。

高级报告

高级报告是一个基于模板的报告，针对较大的数据导出（>= 3000行）以及具有许多列和/或关系的报告。这些报告允许开发者定义一个查询（不执行）以及一个PHP格式化函数，该函数应在插件构建报告文件时在后台应用于所有查询结果。

格式化函数

PHP格式化函数应该在labreports.php配置文件中的functions数组中定义。每个函数必须接受一个参数。参数的值是围绕您的报告类型而构建的Craft元素。变量的名称不重要。函数必须返回一个数组，表示报告中的一行。请注意数组中每个项目的顺序，因为它需要与您在报告模板中定义的列名顺序匹配。

<?php

return [

	'functions' => [
		// The function name in this example is "bookDump"
		'bookDump' => function ($entry) {
			$author = $entry->getFieldValue('bookAuthor')->one();
			$coverImage = $entry->getFieldValue('coverImage')->one();
			return [
				(int) $entry->id,
				$entry->title,
				$entry->postDate->format('F j, Y g:i a'),
				($author ? $author->title : null),
				($coverImage ? $coverImage->getUrl() : null),
				$entry->getFieldValue('publisherName')
			];
		},
		// The function name in this example is "assetDump"
		'assetDump' => function ($asset) {
			return [
				(int) $asset->id,
				$asset->filename,
				(int) $asset->folderId,
				(int) $asset->volumeId,
				$asset->getFieldValue('customFieldHandle'),
				$asset->getFieldValue('someOtherCustomField')
			];
		}
	],

];

如果您不习惯用PHP编程，以下是一些从Twig到PHP的示例，可能有助于您

纯文本/富文本/数字

{# Twig #}
{% set value = entry.fieldHandle %}
// PHP
$value = $entry->getFieldValue('fieldHandle');

关系字段（非预加载）

{# Twig #}
{% set relatedEntry = entry.entryFieldHandle.one %}
// PHP
$relatedEntry = $entry->getFieldValue('entryFieldHandle')->one();

关系字段（预加载）

这些示例在预加载的关系字段没有值的情况下使用了空合并运算符。

{# Twig #}
{% set relatedEntry = entry.entryFieldHandle[0] ?? null %}
// PHP
$relatedEntry = $entry->getFieldValue('entryFieldHandle')[0] ?? null;

日期/时间字段

{# Twig #}
{% set postDate = entry.postDate|date('F j, Y') %}
{% set customDate = entry.customDateField|date('Y-m-d') %}
// PHP
$postDate = $entry->postDate->format('F j, Y');
$customDate = $entry->getFieldValue('customDateField')->format('Y-m-d');

下拉/单选字段

{# Twig #}
{% set fieldValue = entry.dropdownField %}
{% set fieldLabel = entry.dropdownField.label %}
// PHP
$fieldValue = $entry->getFieldValue('dropdownField')->value;
$fieldLabel = $entry->getFieldValue('dropdownField')->label;

复选框字段

“use”语句应放在labreports.php文件的最顶部。

{# Twig #}
{% set commaSepValues = entry.checkboxField|join(', ') %}
// PHP
use craft\helpers\ArrayHelper;

$commaSepValues = implode(', ', ArrayHelper::getColumn(ArrayHelper::toArray( (array) $entry->getFieldValue('checkboxField') ), 'value'));

配置

要配置高级报告，请从Craft控制面板中的主实验室报告页面点击“新建报告”按钮。在表单中，选择报告的类型为“高级”。输入标题、描述（可选）、指向您主要Craft模板文件夹中的模板的相对路径以及格式化函数名称。点击“创建”按钮。

例如，我们将创建一个高级报告，导出一些条目元数据和一些关系数据。请注意，格式化函数保存到配置的报告元素记录中，并在报告模板中不显示。报告模板可能看起来如下所示

{# Create a single array of column headers/labels. #}
{% set columnNames = [
	'ID',
	'Title',
	'Date Published',
	'Author',
	'Cover Image',
	'Publisher Name'
] %}

{# Construct an EntryQuery object WITHOUT .limit() or .all(). Do not execute the query here! #}
{% set entriesQuery = craft.entries.section('books').orderBy('title') %}

{# Tell Lab Reports to construct the CSV File and save a new Report element. #}
{% do report.build(columnNames, entriesQuery) %}

与基本报告一样，report变量在模板中自动定义，包含一个实验室报告的Report元素实例。

运行报告

报告可以通过多种方式生成。

从控制面板

在实验室报告控制面板区域的配置报告标签页中，每个配置的报告都有一个“运行”链接列。点击该按钮链接以生成新的报告。报告也可以通过从单个配置报告的控制面板编辑表单中的“运行”按钮生成。

控制台命令

生成新报告的另一种方法是使用控制台命令。例如，以下命令可以通过cron作业定期运行。每个配置的报告都是一个Craft元素，具有唯一的ID，就像任何其他元素一样。使用reportId选项将ID传递给命令。

php craft labreports/reports/build --reportId=15

计划任务

如上例所示的控制台命令可以通过cron作业定期运行。如果您计划安排报告计划，最好将Craft配置为通过cron作业执行队列。为此，将以下行添加到您的general.php配置文件数组中

'runQueueAutomatically' => false,

此设置将禁用Craft在控制面板中有活动时执行队列作业的默认行为。然后在服务器上创建以下cron作业。请确保更新路径。

* * * * * cd /path/to/projectroot && /path/to/php craft queue/run

如果没有这种配置，队列报告不会运行，除非有人登录到控制面板。

模板变量

以下模板变量可用于使用

`craft.labreports.configuredReports`

根据以下标准查询实验室报告ConfiguredReport元素

reportTitle
reportType
reportDescription
template
formatFunction

{% set basicReports = craft.labreports.configuredReports
	.reportType('basic')
	.orderBy('reportTitle').all() %}

{% set advReports = craft.labreports.configuredReports
	.reportType('advanced')
	.orderBy('reportTitle').all() %}

`craft.labreports.generatedReports`

根据以下标准查询实验室报告Report元素

dateGenerated
configuredReportId
userId
filename
totalRows

{% set reports = craft.labreports.generatedReports
    .configuredReportId(6)
    .dateGenerated('>= ' ~ someDateVar)
    .orderBy('filename').all() %}

{% set reports = craft.labreports.generatedReports
    .userId(4)
    .orderBy('dateGenerated desc').all() %}

`craft.labreports.formatFunctionNames`

此模板变量返回一个包含所有定义的PHP格式化函数名称的数组。

{% set functionNames = craft.labreports.formatFunctionNames %}

{#
It might look like this only with real function names:
[
    'entryFormatter',
    'assetFormatter',
    'anotherFunctionName',
    'yetAnotherFunctionName'
]
#}

`craft.labreports.formatFunctionOptions`

此模板变量返回一个关联数组，包含PHP格式化函数HTML选择选项，包括一个空选项。这在插件的控制面板中使用，可能在该上下文之外不太有用，但它是可用的。

{% set options = craft.labreports.formatFunctionOptions %}

{#
It might look like this only with real function names:
{
    '' : 'Select Function...'
    'entryFormatter' : 'entryFormatter',
    'assetFormatter' : 'assetFormatter',
    'anotherFunctionName' : 'anotherFunctionName',
    'yetAnotherFunctionName' : 'yetAnotherFunctionName'
}
#}

元素属性与方法

`ConfiguredReport`

以下公共属性和方法可用于ConfiguredReport元素。

属性

以下属性和方法在ConfiguredReport元素对象上是公开的。

reportTitle

注意，不仅限于“标题”。此元素类型不使用Craft的本地标题。

reportType

值将是“基本”或“高级”。

reportDescription

报告的简要描述。

template

此值包含到报告模板的相对路径。

formatFunction

如果ConfiguredReport是高级报告，则此值包含使用的PHP格式函数名称。

方法

getRunUrl()

此方法返回ConfiguredReport的控制面板“运行”URL。请注意，返回的URL对没有权限访问控制面板插件的用户将不起作用。

getCpEditUrl()

此方法返回控制面板编辑表单URL。

getTotalRan()

此方法返回从该配置生成的报告的总次数。

`报告`

以下公共属性和方法在Report（生成的报告）元素上可用。

属性

configuredReportId

方法

build($param1, $param2)

此方法生成报告文件。方法参数根据报告类型而变化。对于基本报告，提供嵌套在另一个数组中的单个列标题/标签数组。对于高级报告，提供单个列标题/标签数组（不在另一个数组中），后跟查询对象。

{# Basic Reports (Example) #}
{% do report.build(rowsArray) %}

{# Advanced Reports (Example) #}
{% do report.build(columnLabels, entryQuery) %}

addRows(array $rows)

提供要写入报告文件的数组或报告行数组。

addRow(array $row)

提供要写入报告文件的单个报告行数组。

filePath()

此方法返回报告文件的完整系统文件路径，无论文件是否存在。

fileExists()

此方法返回一个布尔值true/false，表示报告文件是否存在。

setUser(User $user)

此方法将报告的作者设置为指定的User元素。

getUser()

此方法返回报告的作者User元素或null如果不存在。

setConfiguredReport(ConfiguredReport $cr)

此方法在Report元素上设置ConfiguredReport对象。这决定了构建报告文件时将使用哪个配置。

getConfiguredReport()

此方法返回报告的相关ConfiguredReport或null如果不存在。

setQueueJob(GenerateReport $job)

此方法设置报告的队列任务，以便在构建报告时更新任务进度。

updateStatus($status)

此方法将报告的状态更新为给定的字符串（in_progress|finished），然后保存Report元素。

getStatusLabel()

此方法返回报告的状态标签，如果没有，则返回null。可能的值是In Progress|Finished。

getDownloadUrl()

此方法返回报告文件的控制面板下载URL字符串。请注意，此URL对没有控制面板访问权限的用户将不起作用。

计划功能

绘图工具
其他导出格式（自定义分隔符，XML）
动态报告参数

masugadesign / labreports

维护者

详细信息