Evolve Docs

Appearance

Health Check System ​

The Evolve health check system provides comprehensive monitoring capabilities for your Laravel application using Spatie's Laravel Health package with custom Evolve extensions.

Overview ​

Evolve includes two health check systems:

  1. Spatie Health Dashboard (Recommended) - Visual dashboard with scheduled checks and result history
  2. Telemetry Data API Endpoint - JSON API for programmatic telemetry data monitoring

This guide covers both systems.

Spatie Health Dashboard ​

The Spatie Health Dashboard provides a visual interface for monitoring all health checks with automatic scheduling and result history.

Accessing the Dashboard ​

Visit /evolve/health on your application (available from the backend):

https://yourdomain.com/evolve/health

The dashboard displays:

  • Current status of all health checks
  • Response times
  • Last run timestamp
  • Status history (last 5 days)
  • Detailed metadata for each check

Publishing the Configuration ​

First, publish the health configuration to customize settings:

bash
php artisan vendor:publish --tag=evolve.health

This creates config/health.php with all available options.

Configuration ​

Edit config/health.php to customize the health check system:

php
return [
    // Result storage - saves check history to database
    'result_stores' => [
        Spatie\Health\ResultStores\EloquentHealthResultStore::class => [
            'keep_history_for_days' => 5,
        ],
    ],

    // Notification settings
    'notifications' => [
        'enabled' => true,
        'mail' => [
            'to' => env('HEALTH_WEBMASTER_ADDRESS', 'admin@example.com'),
        ],
        'throttle_notifications_for_minutes' => 60,
    ],

    // Theme (light or dark)
    'theme' => 'light',

    // Evolve-specific configuration
    'evolve_health_check' => [
        'email_test_recipient' => env('HEALTH_CHECK_EMAIL_RECIPIENT'),

        'email_imap_verification' => [
            'enabled' => env('HEALTH_CHECK_EMAIL_VERIFY_INBOX', false),
            'host' => env('HEALTH_CHECK_IMAP_HOST'),
            'port' => env('HEALTH_CHECK_IMAP_PORT', 993),
            'username' => env('HEALTH_CHECK_IMAP_USERNAME'),
            'password' => env('HEALTH_CHECK_IMAP_PASSWORD'),
            'max_wait_seconds' => 60,
        ],

        'database' => [
            'test_writes' => env('HEALTH_CHECK_DB_WRITES', false),
        ],

        'performance' => [
            'key_pages' => [
                // Add pages to monitor performance
                // 'about' => '/about',
                // 'contact' => '/contact',
            ],
        ],
    ],
];

Environment Variables ​

Add these to your .env file:

env
# Email health check recipient
HEALTH_CHECK_EMAIL_RECIPIENT=healthcheck@yourdomain.com

# Optional: IMAP verification (verifies email delivery)
HEALTH_CHECK_EMAIL_VERIFY_INBOX=false
HEALTH_CHECK_IMAP_HOST=imap.yourdomain.com
HEALTH_CHECK_IMAP_PORT=993
HEALTH_CHECK_IMAP_USERNAME=healthcheck@yourdomain.com
HEALTH_CHECK_IMAP_PASSWORD=your-password

# Optional: Database write testing (disable for read-only replicas)
HEALTH_CHECK_DB_WRITES=false

# Optional: Health check notifications
HEALTH_WEBMASTER_ADDRESS=admin@yourdomain.com

# Optional: Shopify API credentials (if using Shopify integration)
SHOPIFY_API_KEY=your-api-key
SHOPIFY_PASSWORD=your-api-password
SHOPIFY_SHARED_SECRET=your-shared-secret

# Optional: Scout24 API credentials (if using Scout24 integration)
SCOUT24_CLIENT_ID=your-client-id
SCOUT24_CLIENT_SECRET=your-client-secret
SCOUT24_SELLER_IDS=seller-id-1,seller-id-2

Built-in Health Checks ​

Evolve includes these health checks out of the box:

Critical Infrastructure (Run every minute) ​

Disk Space

  • Warns at 70% usage
  • Fails at 90% usage
  • Monitors application disk space

Database

  • Tests database connectivity
  • Verifies query execution
  • Optional write testing (configurable)

Cache

  • Tests cache read/write operations
  • Verifies cache driver connectivity

Optimized App

  • Checks if config is cached
  • Checks if routes are cached
  • Verifies production optimizations

Communication (Run hourly) ​

Email System

  • Sends actual test email
  • Measures send time
  • Optional: Verifies inbox delivery via IMAP
  • Reports on delivery time

Configuration:

php
'email_test_recipient' => env('HEALTH_CHECK_EMAIL_RECIPIENT'),

'email_imap_verification' => [
    'enabled' => true,
    'host' => 'imap.gmail.com',
    'port' => 993,
    'username' => 'healthcheck@yourdomain.com',
    'password' => 'your-app-password',
],

Security (Run every minute) ​

Security Health Check

  • Validates SSL/TLS certificates
  • Checks security headers
  • Verifies HTTPS enforcement
  • Tests mixed content
  • Makes external HTTP requests to verify configuration

Debug Mode

  • Warns if debug mode is enabled in production

Environment

  • Verifies production environment

Performance (Run every minute) ​

Performance Health Check

  • Tests page response times
  • Monitors memory usage
  • Validates Laravel optimizations
  • Checks key page performance
  • Configurable page list

Configuration:

php
'performance' => [
    'key_pages' => [
        'home' => '/',
        'about' => '/about',
        'contact' => '/contact',
    ],
],

External APIs (Run hourly) ​

Shopify API Health Check

  • Tests OAuth authentication
  • Verifies API connectivity
  • Gets shop information
  • Reports response time
  • Skips automatically if not configured

Configuration:

env
SHOPIFY_API_KEY=your-api-key
SHOPIFY_PASSWORD=your-api-password
SHOPIFY_SHARED_SECRET=your-shared-secret

Scout24 API Health Check

  • Tests OAuth authentication
  • Retrieves seller listings
  • Verifies API connectivity
  • Reports listing count
  • Skips automatically if not configured

Configuration:

env
SCOUT24_CLIENT_ID=your-client-id
SCOUT24_CLIENT_SECRET=your-client-secret
SCOUT24_SELLER_IDS=12345,67890

Scheduling ​

Health checks run automatically via Laravel's scheduler. Ensure your cron is configured:

bash
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

The scheduler runs health checks every minute. Individual checks use throttling (hourly, daily, etc.) to control execution frequency.

Manual Execution ​

Run all health checks manually:

bash
php artisan health:check

View registered health checks:

bash
php artisan health:list

Check Frequency Configuration ​

You can customize how often checks run in EvolveServiceProvider.php:

php
protected function registerHealthChecks(): void
{
    Health::checks([
        // Run every minute (default)
        DatabaseCheck::new(),

        // Run hourly
        EmailHealthCheck::new()
            ->hourly(),

        // Run daily
        EmailHealthCheck::new()
            ->daily(),

        // Run every 5 minutes
        Scout24ApiHealthCheck::new()
            ->everyFiveMinutes(),

        // Conditional execution
        ShopifyApiHealthCheck::new()
            ->hourly()
            ->if(fn () => config('shopify.enabled')),
    ]);
}

Creating Custom Health Checks ​

Create a custom health check class:

php
<?php

namespace App\HealthChecks;

use Spatie\Health\Checks\Check;
use Spatie\Health\Checks\Result;

class CustomApiHealthCheck extends Check
{
    public function run(): Result
    {
        $result = Result::make();

        try {
            // Your health check logic here
            $apiResponse = $this->testApiConnection();

            if ($apiResponse->successful()) {
                return $result->ok('API is responding');
            }

            return $result->failed('API is not responding');

        } catch (\Exception $e) {
            return $result->failed('API error: ' . $e->getMessage());
        }
    }

    protected function testApiConnection()
    {
        // Implement your API test logic
        return Http::get('https://api.example.com/health');
    }
}

Register your custom check in app/Providers/AppServiceProvider.php or EvolveServiceProvider.php:

php
use App\HealthChecks\CustomApiHealthCheck;
use Spatie\Health\Facades\Health;

public function boot()
{
    Health::checks([
        CustomApiHealthCheck::new()
            ->everyFiveMinutes(),
    ]);
}

Result Methods ​

Customize check results with these methods:

php
// Success
return $result->ok('Everything is working');

// Warning (passes but with concerns)
return $result->warning('Slow response time');

// Failure
return $result->failed('Service unavailable');

// Add short summary (displayed in dashboard)
return $result->ok('API responding')
    ->shortSummary('125ms');

// Add metadata (displayed in details)
return $result->ok('API responding')
    ->meta([
        'response_time_ms' => 125,
        'endpoint' => 'https://api.example.com',
    ]);

// Add notification message (sent on failure)
return $result->failed('API timeout')
    ->notificationMessage('Critical: API not responding after 30s');

Notifications ​

Enable email notifications for failed checks:

php
// config/health.php
'notifications' => [
    'enabled' => true,

    'notifications' => [
        Spatie\Health\Notifications\CheckFailedNotification::class => ['mail'],
    ],

    'mail' => [
        'to' => env('HEALTH_WEBMASTER_ADDRESS', 'admin@example.com'),
    ],

    // Throttle notifications to avoid spam
    'throttle_notifications_for_minutes' => 60,
],

Troubleshooting ​

Health checks not running

  • Verify Laravel scheduler is configured in cron
  • Check php artisan schedule:list to see scheduled tasks
  • Run php artisan health:check manually to test

Email health check fails

  • Verify SMTP configuration in config/mail.php
  • Check HEALTH_CHECK_EMAIL_RECIPIENT is set
  • Test manual email: php artisan tinker → Mail::raw('test', fn($m) => $m->to('test@example.com'))

IMAP verification fails

  • Verify IMAP credentials and host
  • Check firewall allows IMAP port (usually 993)
  • Disable IMAP verification: HEALTH_CHECK_EMAIL_VERIFY_INBOX=false

External API checks failing

  • Verify API credentials are configured
  • Check if APIs are conditionally registered: they should skip gracefully if not configured
  • Review logs: tail -f storage/logs/laravel.log | grep HealthCheck

Dashboard shows old results

  • Clear result cache: php artisan cache:clear
  • Run checks manually: php artisan health:check
  • Check database table: health_check_result_history_items

CMS Telemetry Data API ​

INFO

This endpoint provides system information, configuration, and environment details for dashboard and monitoring purposes. It does NOT run health checks. For actual health monitoring, use the Spatie Health Dashboard at /evolve/health.

Overview ​

The Telemetry Data API endpoint returns comprehensive system information and configuration data that can be used by:

  • External monitoring dashboards
  • Infrastructure management tools
  • Configuration management systems
  • Deployment verification scripts
  • System documentation tools

This endpoint is read-only and lightweight - it simply reports current configuration values and basic connectivity status without performing any actual tests.

Authentication ​

All telemetry endpoints require authentication via token:

bash
curl -H "Authorization: Bearer your_health_check_token" \
  "https://yourdomain.com/api/health-check"
bash
curl "https://yourdomain.com/api/health-check?token=your_health_check_token"

Configuration: Set EVOLVE_HEALTH_CHECK_TOKEN in your .env file to a secure random string.

env
EVOLVE_HEALTH_CHECK_TOKEN=your_secure_random_token_here

Endpoint ​

URL: GET /api/health-check

Returns system information, configuration, and environment details.

Response Structure:

json
{
  "status": "healthy",
  "timestamp": "2025-08-18T07:44:41.000Z",
  "system": {
    "php_version": "8.3.19",
    "laravel_version": "10.48.20",
    "environment": "production",
    "debug": false,
    "timezone": "UTC",
    "memory_limit": "256M",
    "max_execution_time": "60",
    "upload_max_filesize": "64M",
    "post_max_size": "64M"
  },
  "project": {
    "name": "Your Project Name",
    "url": "https://yourdomain.com",
    "locale": "en",
    "fallback_locale": "en"
  },
  "database": {
    "connection": "mysql",
    "status": "connected"
  },
  "mail": {
    "driver": "smtp",
    "from_address": "noreply@yourdomain.com",
    "from_name": "Your Project Name"
  },
  "cache": {
    "default": "redis"
  },
  "session": {
    "driver": "redis",
    "lifetime": "120"
  },
  "queue": {
    "default": "redis"
  },
  "storage": {
    "default": "public"
  },
  "evolve": {
    "version": "2.x.x"
  },
  "environment": {
    "image_driver": "gd",
    "broadcast_driver": "log",
    "log_channel": "stack",
    "app_key_set": true,
    "maintenance_mode": false,
    "opcache_enabled": true,
    "extensions": {
      "gd": true,
      "imagick": false,
      "curl": true,
      "mbstring": true,
      "openssl": true,
      "pdo": true,
      "tokenizer": true,
      "xml": true,
      "ctype": true,
      "json": true,
      "bcmath": true,
      "fileinfo": true
    }
  },
  "tracking": {
    "gtm_id": "GTM-XXXXXX",
    "ga_measurement_id": "G-XXXXXXXXXX"
  }
}

Data Categories ​

System Information ​

  • PHP version and configuration (memory limits, execution time, upload limits)
  • Laravel version
  • Environment (production, staging, local)
  • Debug mode status
  • Timezone configuration

Project Configuration ​

  • Application name and URL
  • Locale settings
  • Fallback locale

Infrastructure Status ​

  • Database: Connection type and connectivity status (simple PDO check)
  • Mail: Driver configuration and sender information
  • Cache: Default cache driver
  • Session: Session driver and lifetime
  • Queue: Queue connection
  • Storage: Default filesystem disk

Evolve Information ​

  • Evolve framework version
  • Custom Evolve configuration

Environment Details ​

  • Image Processing: Configured driver (GD, Imagick)
  • Broadcasting: Broadcast driver configuration
  • Logging: Default log channel
  • Security: App key set status
  • Maintenance: Down for maintenance status
  • OPcache: PHP OPcache enabled status
  • PHP Extensions: Availability of required/optional extensions

Tracking Configuration ​

  • Google Tag Manager ID
  • Google Analytics Measurement ID

Use Cases ​

Infrastructure Monitoring

bash
# Poll system information for monitoring dashboards
curl -H "Authorization: Bearer $TOKEN" \
  "https://yourdomain.com/api/health-check" \
  | jq '.system.memory_limit, .database.status'

Deployment Verification

bash
# Verify configuration after deployment
curl -H "Authorization: Bearer $TOKEN" \
  "https://yourdomain.com/api/health-check" \
  | jq '.system.environment, .environment.app_key_set'

Documentation Generation

bash
# Extract system information for documentation
curl -H "Authorization: Bearer $TOKEN" \
  "https://yourdomain.com/api/health-check" \
  | jq '.system, .project' > system-info.json

Extension Verification

bash
# Check PHP extensions are installed
curl -H "Authorization: Bearer $TOKEN" \
  "https://yourdomain.com/api/health-check" \
  | jq '.environment.extensions'

Important Notes ​

What This Endpoint Does NOT Do

This endpoint:

  • ❌ Does NOT send test emails
  • ❌ Does NOT run performance tests
  • ❌ Does NOT crawl for dead links
  • ❌ Does NOT test external APIs
  • ❌ Does NOT measure response times
  • ❌ Does NOT store historical data

It only reports current configuration values and performs a simple database PDO connection check.

For Actual Health Monitoring

For comprehensive health testing and monitoring, use:

  • Spatie Health Dashboard: /evolve/health (visual interface)
  • Spatie Health JSON API: Configure via config/health.php

Authentication Errors ​

401 Unauthorized Response:

json
{
  "error": "Unauthorized"
}

Common causes:

  • EVOLVE_HEALTH_CHECK_TOKEN not set in .env
  • Token mismatch between request and configuration
  • Missing Authorization header or token parameter

Legacy Compatibility ​

This endpoint was originally named "Health Check" but has been clarified as a telemetry/system information endpoint. The name is maintained for backward compatibility with existing monitoring tools and dashboards.

For new integrations, consider using dedicated endpoints or configuration files for system information rather than polling this API endpoint.