mdigi/laravel-jasper-client

Laravel package (standalone) sebagai wrapper HTTP untuk Jasper Reporting Engine REST API.

Installation

Tambahkan via Composer (path repo atau VCS sesuai setup kamu), lalu jalankan:

composer require mdigi/laravel-jasper-client

Configuration

Publish config:

php artisan vendor:publish --tag=jasper-config

Env yang didukung:

• Base
  • JASPER_BASE_URL (default http://localhost:8080)
  • JASPER_TIMEOUT (detik, default 30)
  • JASPER_RETRY_TIMES (default 0)
  • JASPER_RETRY_SLEEP_MS (default 0)
• Auth
  • JASPER_AUTH_TYPE (none|basic|bearer, default none)
  • JASPER_USERNAME (basic)
  • JASPER_PASSWORD (basic)
  • JASPER_TOKEN (bearer)
• Endpoint map
  • JASPER_ENDPOINT_UPLOAD_TEMPLATE (default /api/v1/templates)
  • JASPER_ENDPOINT_GENERATE_ASYNC (default /api/v1/reports/jobs)
  • JASPER_ENDPOINT_GENERATE_STATUS (default /api/v1/reports/jobs/{job_id})
  • JASPER_ENDPOINT_DOWNLOAD_REPORT (default /api/v1/reports/jobs/{job_id}/download)
  • JASPER_ENDPOINT_DATASOURCES (default /api/v1/datasources)

Usage

Facade (recommended, explicit import):

use Mdigi\LaravelJasper\Facades\Jasper;

$resp = Jasper::listDataSources();

Global short alias Jasper (optional):

• Package discovery now provides alias mapping via composer.json (extra.laravel.aliases).
• If your app disables discovery, add alias manually in config/app.php:

'aliases' => [
    // ...
    'Jasper' => Mdigi\LaravelJasper\Facades\Jasper::class,
],

Via dependency injection:

use Mdigi\LaravelJasper\Contracts\JasperClientInterface;

public function __construct(private JasperClientInterface $jasper) {}

IDE Autocomplete (Jasper::)

This package adds facade type metadata so static autocomplete can resolve methods from JasperClientInterface.

If autocomplete is not refreshed yet in your app:

composer dump-autoload

Then reload your IDE window or restart the PHP language server (Intelephense / PHPStorm indexer).

uploadTemplate

$upload = Jasper::uploadTemplate(storage_path('app/templates/invoice.jrxml'), 'invoice_template');

generateAsync

use Mdigi\LaravelJasper\DTO\SubmitJobRequest;

$job = Jasper::generateAsync(new SubmitJobRequest(
    templateId: 'tpl-001',
    outputFormat: 'pdf',
    dataSourceKey: 'main-db',
    sqlQuery: 'SELECT * FROM invoices WHERE id = :id',
    reportParams: ['id' => 1001],
));

getGenerationStatus

$status = Jasper::getGenerationStatus('job-123');

downloadGeneratedReport

$binary = Jasper::downloadGeneratedReport('job-123');
file_put_contents(storage_path('app/reports/invoice.pdf'), $binary);

listDataSources

$items = Jasper::listDataSources(); // array<DataSourceItem>

Error Handling

use Mdigi\LaravelJasper\Exceptions\JasperConfigurationException;
use Mdigi\LaravelJasper\Exceptions\JasperRequestException;

try {
    $items = Jasper::listDataSources();
} catch (JasperConfigurationException $e) {
    // env/config salah
} catch (JasperRequestException $e) {
    // request ke Jasper gagal / non-2xx
}

Full Async Flow Example

1. Upload template
2. Submit job async
3. Poll status sampai FINISHED
4. Download report

Testing

Run:

vendor/bin/phpunit

Compatibility

Planned compatibility matrix:

• Laravel 9.x (min PHP 8.0.2)
• Laravel 10.x (min PHP 8.1.0)
• Laravel 11.x (min PHP 8.2.0)
• Laravel 12.x (min PHP 8.2.0)

Catatan: package ditulis kompatibel PHP 8.0 syntax supaya tetap install di Laravel 9.

Docker Testing

Lihat Dockerfile, docker-compose.yml, dan .env.testing.example.