README

A small Laravel package that periodically generates a health/status report for your application or packages and sends it to a remote endpoint.

The package exposes an Artisan command that:

Decides whether a report should be sent (via a configurable decider class)
Generates a report payload
Sends the payload to a configured API endpoint
Fails gracefully when the endpoint is unreachable

Features

🩺 Centralized health/status reporting
🔌 Pluggable decision logic to control when data is sent
📦 Customizable report generation
🔐 Token-based authentication
🧯 Graceful handling of connection failures

Requirements

PHP 8.0+
Laravel 9.x or higher

Installation

Install the package via Composer:

composer require ifresh/package-health

Publish the configuration file:

php artisan vendor:publish --tag=package-health-config

Configuration

The package is configured via config/health.php.

Available options

return [
    // The URL where health reports will be posted
    'url' => env('HEALTH_ENDPOINT_URL'),

    // API token used for authenticating requests
    'api_token' => env('HEALTH_API_TOKEN'),

    // Class responsible for deciding whether a report should be sent
    'decider' => \IFresh\PackageHealth\Deciders\DefaultDecider::class,
];

Environment variables

HEALTH_ENDPOINT_URL=https://example.com/api/health
HEALTH_API_TOKEN=your-api-token

Artisan Command

The package registers the following command:

php artisan health:send-package-status

What the command does

Resolves the configured decider and calls shouldPost()
Stops immediately if the decider returns false
Generates a report using ReportGenerator
Sends the report as JSON to the configured endpoint
Logs a warning if the request fails due to a connection error

Decision Logic (Decider)

The decider determines if and when the health report should be sent.

A decider class must implement a shouldPost(): bool method.

Example:

class DefaultDecider
{
    public function shouldPost(): bool
    {
        return app()->environment('production');
    }
}

This allows you to:

Limit reports to production
Send reports on a schedule
Implement rate limiting or time-based logic

Report Generation

Reports are generated by:

IFresh\PackageHealth\Generators\ReportGenerator

You can extend or replace this class to customize the payload structure or contents.

Error Handling & Logging

If the endpoint cannot be reached, the package:

Catches Illuminate\Http\Client\ConnectionException
Logs a warning with the request URL and error message
Does not throw or fail the command

This ensures your scheduled jobs remain stable.

Scheduling

You can run the command automatically using Laravel's scheduler:

$schedule->command('health:send-package-status')->hourly();

Security

Requests are authenticated using a Bearer token
Payloads are sent as JSON
Ensure the endpoint is served over HTTPS

License

This package is proprietary and maintained by iFresh Workspace.

Support

For questions or issues, contact:

Email: info@ifresh.nl
Organization: iFresh Workspace

ifresh / package-health

Maintainers

Details