Kendo Report Tool Laravel Package

Product Decisions This Supports

• Standardizing in-app feedback / bug-report capture across your Laravel fleet. The package gives every app one call — KendoReports::submit($title, $description, $authorName, $files) — to push a report plus screenshots into a single central triage destination. That is the enabling primitive for a consistent "Report a problem" surface rather than each team inventing its own mailto/Slack/form path.
• Build vs. buy on feedback intake. This is the build side of the decision: a thin, ~one-method client against your own "kendo" service, instead of wiring each app into Zendesk/Jira/Linear/Sentry SDKs. It is cheap to adopt (config file + env vars, auto-discovered provider) and keeps report data in your own system — relevant if report content is customer data you would rather not route through a third-party SaaS.
• Roadmap sequencing for a feedback loop. v0.1.0 is intake only: submit, decode a 201, done. There is no read/list/status/triage API, no attachments beyond images, no tagging or categorization field. So roadmap should treat "capture" as shippable now and "close the loop" (status back to reporter, dedupe, routing rules) as explicitly not-yet-supported — a decision point, not an assumption.
• Reliability-vs.-UX trade-off, made configurable. The swallow flag (REPORT_TOOL_SWALLOW=true) is a product lever, not just a config knob: false (default) means a failed report submission breaks the user-visible action and surfaces the error; true means the user never sees a failure and it's only written to the PHP error_log. Someone has to own choosing this per surface — a "Send feedback" button should almost certainly swallow-and-log; a report that is the actual point of the workflow should not.
• Latency budget for the reporting interaction. submit() is a synchronous multipart POST with configurable connect_timeout/timeout. That call sits inside a user request. This directly informs UX design (async job + "we'll send it" acknowledgement, or a spinner with a hard timeout) and the size/quantity limits you impose on files[].

When to Consider This Package

Adopt when all of the following hold:

• You actually run a "kendo" report-tool instance; the client is hard-coded to {kendo_url}/api/projects/{project}/reports with a Bearer report:create token. It is not a general-purpose HTTP client.
• You have multiple Laravel apps (or expect to) and want one shared integration surface instead of N bespoke ones — that's where the value is; for a single app, a few lines of Http::withToken()->post() is arguably enough.
• Image attachments are sufficient. files[] takes UploadedFile instances or local file paths, sent as multipart parts. No PDFs? (Actually, extension-based restrictions are not documented — assume images-by-convention, not enforced.)
• Synchronous submission is acceptable, or you're prepared to wrap it in a queued job yourself. There is no retry, no backoff, no queue integration, no idempotency key in this release — a transient 500 loses the report unless the caller handles it.
• You're comfortable on PHP 8.4/8.5 (the CI matrix targets these). Narrow runtime support is a real constraint for apps on 8.2/8.3.

Look elsewhere or defer when:

• You need guaranteed delivery. Fire-and-forget with no retries is fine for "nice to have feedback," wrong for anything compliance- or SLA-adjacent.
• Data-handling review is a blocker. The release notes state plainly: no PII scrubbing — report content is sent verbatim, and author name is optional but free-text. If reports can contain customer identifiers, health/financial data, or EU personal data, you need a DPIA/retention story and probably redaction at the call site before this touches production.
• You need a supported, stable API. This is v0.1.0 — pre-1.0, single public method, no deprecation policy, no upgrade guide. Treat the submit() signature and config keys as likely to move.
• You need vendor support, SSO/multi-tenant token scoping, or per-project credential rotation. One static token per app is the whole model today.

Also flag for engineering review before rollout: files[] accepting local file paths means the argument must never be built from unvalidated user input; and swallow=true routes failures to error_log, which is typically not a monitored channel — silent loss is the default outcome unless you add alerting.

How to Pitch It (Stakeholders)

To executives: We now have a small, standard piece of plumbing that lets any of our Laravel apps send a problem report — title, description, optional reporter name, screenshots — into one central triage tool. It removes the "every team wires up feedback differently" problem and keeps that data inside our own systems rather than a third-party vendor. It's deliberately minimal: submission only, roughly one function call, cheap to adopt. It is a v0.1.0 building block, not a finished feedback product — no delivery guarantees, no triage/status loop back to the reporter, and no automated redaction of sensitive content, so we should scope it to low-risk feedback surfaces first and budget follow-on work for reliability (retries/queueing) and data handling before we point it at anything regulated.

To engineering: Auto-discovered service provider, published config/report-tool.php, env-driven (REPORT_TOOL_URL, _PROJECT, _TOKEN, _CONNECT_TIMEOUT, _TIMEOUT, _SWALLOW). One public method: KendoReports::submit(string $title, string $description, ?string $authorName = null, array $files = []): ?array — synchronous multipart POST, Bearer report:create, returns the decoded 201 body. Non-201 or transport failure throws ReportSubmissionException with the status (0 for transport) unless swallow is on, in which case it logs to error_log and returns null. Timeouts floor to a sane default so a hung host can't block the caller indefinitely — but the call is still inline, so put it behind a job if it's on a hot path. Code quality signals are strong (PHPStan level max, Pint, Pest/Testbench, audit→format→phpstan→test CI, tag-push release), so the review surface is small and trustworthy — the work is in our call sites: validate anything feeding files[], never log the token, decide swallow per surface, and add alerting if we rely on swallow mode.