Kendo Report Tool Laravel Package

Getting Started

• Install the package with Composer. Laravel auto-discovers KendoReportToolServiceProvider; if package discovery is disabled, register the provider manually.
• Publish and review config/report-tool.php first. The keys you will normally care about are kendo_url, project, token, connect_timeout, timeout, and swallow.
• Configure the environment values backing those keys, typically via REPORT_TOOL_*. At minimum set the Kendo URL, project, and a token with the report:create scope.
• Keep swallow off by default. With it off, failures throw ReportSubmissionException; with it on, failures are logged to PHP error_log and submit() returns null.
• First use case: an internal “submit a bug report” action that sends a title, description, optional author name, and uploaded screenshots:

use KendoReports;
use KendoReportTool\Exceptions\ReportSubmissionException;

try {
    $report = KendoReports::submit(
        title: $request->string('title')->toString(),
        description: $request->string('description')->toString(),
        authorName: $request->user()?->name,
        files: (array) $request->file('files', []),
    );

    // $report is the decoded 201 response body when submitted successfully.
    return back()->with('status', $report ? 'Report submitted.' : 'Report could not be submitted.');
} catch (ReportSubmissionException $e) {
    report($e);

    return back()->withErrors('Report submission failed.');
}

Implementation Patterns

• Controller action for simple, interactive submissions. The client is synchronous, so a direct call is fine for admin tools or low-volume forms where the user can wait for the Kendo round trip.
• Queued job for user-facing or bulk submissions. Because submit() performs a blocking HTTP call, dispatch a job when the report is not part of the immediate user response. Let exceptions bubble in the job when swallow is false so Laravel’s queue retry/backoff can apply.
• Treat null as “submission did not succeed,” never as success. null only appears when report-tool.swallow is enabled. If you enable swallow, log and monitor the PHP error_log, because the package does not throw.
• File uploads accept either UploadedFile instances or local file paths. Pass request uploads directly, or pass readable local paths for generated reports/screenshots. Validate file type and size in your own request/job before calling the client.
• Omit the author cleanly. A null authorName is omitted from the multipart payload, so anonymous/internal submissions do not need a placeholder string.
• Configure per environment. Use distinct project and token values per environment. Keep the token in secrets management and rotate it like any other Bearer credential.
• Wrap the client behind your own application service if you need testability or portability. The public surface is a concrete call, so an adapter/interface around it keeps controllers and jobs easy to fake or swap later.
• Test against a faked HTTP layer where possible. Use Laravel’s HTTP fake/Testbench tooling to assert the multipart fields and simulate 201, non-201, and transport failures. Keep one integration test against a real sandbox if Kendo provides one.

Gotchas and Tips

• Synchronous calls can block requests and workers. Set conservative connect_timeout and timeout values. Non-positive timeout values are floored to the package default, so 0 does not mean “no timeout.”
• swallow=true hides failures from normal Laravel exception handling. Failures go to local PHP error_log, not necessarily your configured Laravel log channel. Avoid enabling it in production unless you actively monitor that log and can tolerate silent null returns.
• Inspect the exception status. ReportSubmissionException carries the HTTP status for non-201 responses and 0 for transport failures. Use that distinction for retries and alerting.
• Only 201 is success. Other 2xx responses are treated as failures. Do not assume any non-exception response is a successful Kendo submission.
• The token needs the report:create scope. A valid token with the wrong scope will fail at the HTTP layer; check scope before debugging the payload.
• Report content is sent verbatim and is not PII-scrubbed. That is intentional, but it means your application owns redaction/compliance. Do not include secrets or regulated data unless the destination and policy allow it.
• File paths must be local and readable. Remote URLs are not supported as path values; upload them as UploadedFile instances or download them first.
• Clear/rebuild config cache after changing REPORT_TOOL_* values. Standard Laravel config caching applies; stale cached config is a common cause of “it still uses the old project/token.”
• Publishing the config is the main extension point. The initial release is intentionally small: config, provider registration, and the submit client. If you need custom retry policy, payload shaping, or logging, implement it in your own wrapper/job rather than expecting package-level hooks.