always-open/report-engine

General reporting engine for Laravel

Fund package maintenance!
always-open


README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

General reporting engine for Laravel

Installation

You can install the package via composer:

composer require always-open/report-engine

Usage

Create a report

Create a report that extends the ReportBase. Within this class you will define the query to fetch the data as well as the columns which will be output.

<?php

namespace App\Reports\User;

use App\Models\User;
use AlwaysOpen\ReportEngine\BaseFeatures\Data\Types\Text;
use AlwaysOpen\ReportEngine\ReportBase;
use Illuminate\Database\Query\Builder;

class UserReport extends ReportBase
{
    protected $autoloadInitialData = true;

    /**
     * @return string
     */
    public function title(): string
    {
        return 'User Maintenance';
    }

    /**
     * @return string
     */
    public function description(): string
    {
        return 'List of all users within the system';
    }

    /**
     * @return Builder
     */
    public function baseQuery(): Builder
    {
        return User::toBase()
            ->select([
                'id',
                'email',
                'name',
            ]);
    }

    /**
     * @return array
     */
    public function availableColumns(): array
    {
        return [
            'name' => [
                'label'      => 'Name',
                'filterable' => true,
                'type'       => new Text(),
            ],
            'email' => [
                'label'      => 'Email',
                'filterable' => true,
                'type'       => new Text(),
            ],
        ];
    }
}

Create a controller

Create a controller to output the report

<?php

namespace App\Http\Controllers;

use App\Reports\User\UserReport;

class UserController extends Controller
{
    /**
     * @return UserReport
     */
    public function index() : UserReport
    {
        return app(UserReport::class);
    }
}

Create a route

When creating a route ensure you include multiformat as this will handle things like .sql and .json endpoint calls.

<?php

use App\Http\Controllers\UserController;

Route::get('users', [UserController::class, 'index'])
    ->multiformat();

Routes

Multiformat adds handling multiple formats to the url which can give the following output building upon the above examples.

This will output an HTML page that will contain a tabulator table and make ajax requests to get the data needed.

{{ base_url }}/users

This will output a JSON payload of the data

{{ base_url }}/users.json

This will output the entire SQL query, useful for debugging

{{ base_url }}/users.sql

This will return the output of the explain command for the query, useful for debugging

{{ base_url }}/users.explain

Filters

Here are the possible filters for the default types. To build a filter follow this format:

let filterParams = new URLSearchParams();
let filterName = 'name'
let action = 'equals'
let value = 'bob'
filterParams.append('filters['+filterName+']['+action+']', value)

DateTime

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • less_than
  • less_than_or_equal

Decimal

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • less_than
  • less_than_or_equal

Dollar

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • less_than
  • less_than_or_equal

Enum

  • equals

Html

  • contains
  • does_not_contain

Integer

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • less_than
  • less_than_or_equal

NullableDecimal

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • is_empty
  • is_not_empty
  • less_than
  • less_than_or_equal

NullableInteger

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • is_empty
  • is_not_empty
  • less_than
  • less_than_or_equal

Number

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • less_than
  • less_than_or_equal

NumericHtml

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • less_than
  • less_than_or_equal

Percentage

  • does_not_equal
  • equals
  • greater_than
  • greater_than_or_equal
  • less_than
  • less_than_or_equal

Text

  • contains
  • does_not_contain
  • does_not_equal
  • equals

Url

  • contains
  • does_not_contain

YesNo

  • is_true
  • is_false

YesNoShort

  • is_true
  • is_false

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.