Reporting Api Laravel Package

Getting Started

• Install the package with Composer: composer require audunru/reporting-api. v3.0.5 is a patch release over v3.0.4 with no API changes, so it is a safe in-place upgrade.
• Publish the package configuration and review the defaults:

  php artisan vendor:publish --tag=reporting-api-config
  

  Check the package README for the exact provider/tag if your install does not expose a config tag.
• Configure the connection details in .env (API endpoint, token, queue/log channel as applicable), then clear cached config during development:

  php artisan config:clear
  

• First use case: send a small, deterministic report (for example a daily count of new users) from a queued job or scheduled command. Start with a single report definition and verify the outgoing payload and the resulting log entry before wiring it into domain events.
• Where to look first: the published config file, the package’s report contract/DTO (if provided), and the README section covering “sending a report”. The v3.0.5 fix specifically affects how report values are rendered in log messages, so review your configured log channel early.

Implementation Patterns

• Define reports as dedicated classes. Keep report values in a small DTO or array-returning class rather than scattering payload construction across controllers. This makes it easy to test and to reuse the same report from a command, job, or event listener.
• Queue report delivery. Reports often make outbound HTTP calls. Implement ShouldQueue on the job that sends the report, use a dedicated queue, and configure retries/backoff. This keeps request latency out of the user path.
• Schedule recurring reports. Register daily/weekly reports in routes/console.php or the console kernel. Use withoutOverlapping() and, where supported, unique jobs to avoid duplicate sends when schedulers run on multiple servers.
• Trigger from domain events. Listen for model events or custom events (UserRegistered, InvoicePaid, etc.) and dispatch a report job. Keep listeners thin: resolve the report definition, then hand off to the queued sender.
• Test with Laravel’s HTTP and log fakes. Because the package ultimately sends a payload and logs report values, use Http::fake() / Log::fake() (or the package’s own fake if provided) to assert the exact report structure without hitting the remote API.
• Use structured logging. v3.0.5 strips line breaks from report values in log messages, which is ideal for single-line log ingestion systems (CloudWatch, Papertrail, Loki, etc.). Prefer passing scalar values and short strings; if you need multiline content, log it separately rather than embedding it in a report value.
• Multi-tenant awareness. If reports are scoped to a tenant, include the tenant identifier in the report metadata and avoid relying on global state. Pass context explicitly into the report/job so queued execution cannot leak the wrong tenant.
• Failure handling. Catch package-specific exceptions (or the underlying HTTP client exception) in the job’s failed() method, log with context, and optionally notify. Report failures should not silently disappear.

Gotchas and Tips

• v3.0.5 changes log output, not payloads. The fix strips line breaks from report values in log messages. If you were relying on multiline log entries for debugging, inspect the raw report payload directly or add a custom formatter. Log parsers that assumed one event per line will now behave more reliably.
• Run php artisan config:cache after changing reporting config. Laravel config caching is a common source of “my endpoint/token changed but the app still uses the old value” confusion.
• Do not commit API tokens. Keep credentials in .env and ensure report payloads logged in non-production environments do not contain PII or secrets. Consider redacting sensitive fields before logging.
• Restart queue workers after deploying v3.0.5. Long-running workers can hold old code; php artisan queue:restart ensures the new log-sanitisation behaviour is active.
• Watch for large reports. Very large arrays or long string values can bloat logs and HTTP payloads. Chunk or summarise where possible, and set appropriate job timeouts.
• Check version constraints when upgrading. v3.0.5 is a patch, but confirm your PHP/Laravel versions still satisfy the package’s composer.json requirements, especially if you are coming from an older major version.
• Extension points to inspect: custom log channels/formatters (relevant to the v3.0.5 fix), custom HTTP client configuration, and any publishable config for report value casting/formatting. Binding a custom formatter is usually preferable to patching vendor code if you need different log rendering.
• Debugging tip: use Http::fake() to capture the outgoing request and Log::spy() to assert the logged context. If a report is not being sent, check the queue connection, job failures table, and whether the scheduler is actually running (php artisan schedule:list).