README

Write reports with Twig.

Requirements

This plugin requires Craft CMS 3.0.0 or later.

Installation

To install the plugin, follow these instructions.

Open your terminal and go to your Craft project:
```
 cd /path/to/project
```

Then tell Composer to load the plugin:

 composer require superbig/craft-reports

In the Control Panel, go to Settings → Plugins and click the “Install” button for Reports.

Reports Overview

Reports for Craft CMS and Craft Commerce makes it possible to write reports in Twig via a simple, fluent API.

It also makes it possible to setup report targets like email and (soon) Slack.

This way you can send reports directly to your target channels, either on demands or (soon) on a schedule.

Configuring Reports

You can override the options with a config file called reports.php:

<?php
return [
    'enableScheduler' => true,
    'helpers'          => [
        'formatUsers' => function($users) {
            /** @var \craft\elements\User[] $user */
        }
    ],
];

Using Reports

You may use includes both for the Report Content and Settings fields.

The content Twig will be passed the following variables:

result - a ReportResult model behind the scenes
report - a Report model behind the scenes

Report Example

To generate a list of users that has logged in the last 30 days:

{% set loginPeriod = now|date_modify('-30 days') %}
{% set users = craft.users.lastLoginDate('> ' ~ loginPeriod|atom).all() %}

{% if result is defined %}
    {% do result.setHeader(['Username', 'Name', 'Email']) %}
    {% for user in users %}
        {% do result.append([user.username, user.getName(), user.email ]) %}
    {% endfor %}
{% endif %}

Report Target Example

Report targets makes it possible to send the result of a report to target channels.

For now, email is supported, with Slack and more coming soon.

Example email body:

Report generated for {{ target.name }}<br>
This report includes:<br><br>

{% for report in reports %}
- {{ report.name }}<br>
{% endfor %}

Note that you have access to both the reports attached to the target and the target itself.

Running report targets through Craft's console command

You can run any report targets through the console with the following command

./craft reports/default/run-target targetHandle

The command can also receive the target's ID.

This way of running report targets is particularly useful if you want to run it from a cron job, or you have bigger reports that require more memory or runs longer than a normal web request can handle.

Reports Roadmap

Some things to do, and ideas for potential features:

Port Craft 2 version
Chainable content API
Document content API
Document report targets
Fields support
Charts support
Widget support
Scheduled reports
Email as report target
Slack as report target
Event for registering report target
Template helpers
Document helpers
Report sources (think Slack slash command or CraftQL)
Run report targets via cli
Report targets dropdown in Reports index
Override title
Use queue job when running report targets
Screenshots
Permissions (Create, View, Export, Run, Delete)

Brought to you by Superbig

superbig / craft-reports

Maintainers

Details