Health Status

The framework includes a lightweight health check endpoint for monitoring and uptime verification. This endpoint is customizable and can optionally be secured using a secret, which is especially useful in production environments.

Enabling and Configuring

Enable the health check middleware by updating your configs/app.php:

return [
    'health_status' => [
        'enabled' => true,
        'secret'  => 'your-secret-value', // optional but recommended
        'route'   => 'up',
        'critical' => ['api/ping', 'contact-us'],
    ],
];

• enabled: Toggles the health check endpoint.
• route: Defines the URL path (e.g., example.com/up).
• secret: If defined, all requests must include this value.
• critical: Optionally test additional internal or external URLs.

If secret is set, access will be denied unless the correct value is provided via HTTP header or, as a fallback, query string. The HTTP header method is preferred.

---

Authorization Mechanism

When secret is configured, requests must provide the value using:

1. Preferred: Custom HTTP header X-Health-Check-Secret
2. Fallback: URL query parameter ?secret=your-secret

If the secret is missing or incorrect, the middleware check will return:

{
  "error": "Unauthorized"
}

with HTTP status code 401 Unauthorized.

---

Accessing the Endpoint

Replace your-secret-value and the base URL with your actual values.

🔧 CLI (cURL)

curl -H "X-Health-Check-Secret: your-secret-value" https://example.com/up

OR

curl -I -H "X-Health-Check-Secret: your-secret-value" https://example.com/up

Or, less securely (fallback mode):

curl https://example.com/up?secret=your-secret-value

---

⚙️ HTTPie

http https://example.com/up X-Health-Check-Secret:your-secret-value

---

📡 Postman

1. URL: https://example.com/up
2. Method: GET
3. Headers tab:
   • Key: X-Health-Check-Secret
   • Value: your-secret-value

Alternatively, add ?secret=your-secret-value to the URL for fallback mode.

---

📊 Uptime Monitors (e.g., Pingdom, UptimeRobot)

If your monitoring tool supports custom headers, configure it to send:

• Header: X-Health-Check-Secret: your-secret-value

If not supported, use the query string fallback:

https://example.com/up?secret=your-secret-value

⚠️ Note: Query string access may expose secrets in logs. Prefer headers whenever supported.

---

Sample Response

Successful response:

{
  "code": 200,
  "healthy": true,
  "status": "OK",
  "services": {
    "database": { "status": true, "message": "Database connection is healthy." },
    "home": { "status": true, "message": "https://example.com returned HTTP 200 OK" },
    "disk_space": { "status": true, "message": "Disk space is sufficient." },
    "memory_usage": { "status": true, "message": "Memory usage is within acceptable limits." },
    "critical_urls": { "status": true, "message": "All critical URLs are reachable.", "details": [...] },
    "cache": { "status": true, "message": "Cache Connection is OK" }
  },
  "timestamp": "2025-04-10T14:01:22+00:00"
}

If one or more checks fail:

{
  "code": 503,
  "healthy": false,
  "status": "ERROR",
  ...
}

---

Summary

Use Case	Approach	Recommended
Manual CLI testing	curl or httpie with header	✅ Yes
GUI tools	Postman with X-Health-Check-Secret	✅ Yes
Monitors	Header if supported, query fallback	⚠️ With caution