README

Framework agnostic PHP CLI package for checking domain health from the terminal. It validates URLs, HTTP status, redirects, DNS records, SSL expiry, security headers, and basic SEO signals without requiring external APIs.

External API integrations for PageSpeed Insights, SSL Labs, crt.sh, and Cloudflare are available as optional checks and stay disabled by default.

Installation

composer require lukman-ss/php-domain-health

For local development:

composer install
composer quality

Basic Usage

Check a single domain:

vendor/bin/domain-health check https://example.com

Bare domains are normalized to HTTPS:

vendor/bin/domain-health check example.com

Useful options:

vendor/bin/domain-health check example.com --timeout=5
vendor/bin/domain-health check example.com --no-color
vendor/bin/domain-health check example.com --block-private-targets
vendor/bin/domain-health check example.com --output=report.txt

Check Single Domain

The check command runs the built-in checks for one target and returns an exit code that can be used in scripts.

vendor/bin/domain-health check https://example.com
vendor/bin/domain-health check https://example.com --json
vendor/bin/domain-health check https://example.com --markdown

Scan Multiple Domains

Use scan for more than one target:

vendor/bin/domain-health scan example.com example.org

Limit the scan to selected checks:

vendor/bin/domain-health scan example.com example.org --checks=url,http,dns

Write a Markdown report to disk:

vendor/bin/domain-health scan example.com example.org --markdown --output=domain-health-report.md

Available Checks

Built-in checks:

url or url_validity: validates the normalized URL.
host or host_resolution: checks whether the host can resolve.
http or http_status: checks HTTP status, response time, and content type.
redirect: inspects redirect chains, loops, final URL, and HTTPS redirects.
dns: checks A, AAAA, CNAME, NS, and MX records.
ssl or ssl_expiry: checks certificate issuer, subject, and expiry date. This check reads certificate metadata for expiry monitoring; it does not validate the CA trust chain or hostname match.
headers or security_headers: checks common security headers.
seo: checks robots.txt, sitemap.xml, canonical, title, meta description, H1, and Open Graph basics.

Optional integration checks:

pagespeed: PageSpeed Insights performance score.
ssllabs: SSL Labs endpoint grade.
crtsh: certificate transparency count from crt.sh.
cloudflare: Cloudflare zone lookup.

Optional integrations only run when they are enabled in config.

Configuration

Batch scans can be driven by PHP or JSON config files.

vendor/bin/domain-health scan --config=domain-health.json
vendor/bin/domain-health scan --config=domain-health.php --markdown --output=report.md

Example domain-health.json:

{
  "urls": [
    "https://example.com",
    {
      "url": "example.org",
      "timeout": 5
    }
  ],
  "timeout": 10,
  "checks": {
    "url": true,
    "host": true,
    "http": true,
    "redirect": true,
    "dns": true,
    "ssl": true,
    "headers": true,
    "seo": true
  },
  "thresholds": {
    "ssl_expiry_warn_days": 30
  },
  "missing_mx_is_warning": false,
  "fail_non_https_ssl": false,
  "block_private_targets": false
}

Example optional integrations:

{
  "urls": ["https://example.com"],
  "checks": {
    "pagespeed": true,
    "ssllabs": true,
    "crtsh": true,
    "cloudflare": true
  },
  "integrations": {
    "pagespeed": {
      "enabled": true,
      "api_key": null
    },
    "ssllabs": {
      "enabled": true
    },
    "crtsh": {
      "enabled": true
    },
    "cloudflare": {
      "enabled": true,
      "api_token": "cloudflare-api-token",
      "zone_id": "cloudflare-zone-id"
    }
  }
}

If an external API is rate limited, unavailable, or missing credentials, the integration reports info and the core scan keeps running.

JSON Report

Use --json for automation-friendly output:

vendor/bin/domain-health check example.com --json
vendor/bin/domain-health scan example.com example.org --json

Example shape:

{
  "url": "https://example.com",
  "timeout": 10,
  "status": "warn",
  "exit_code": 1,
  "summary": {
    "ok": 15,
    "info": 8,
    "warn": 5,
    "fail": 0
  },
  "checks": [
    {
      "name": "URL is valid",
      "status": "ok",
      "label": "URL is valid",
      "message": "URL is valid",
      "metadata": {
        "url": "https://example.com"
      }
    }
  ]
}

Markdown Report

Use --markdown for a report that can be saved to GitHub issues, pull requests, or build artifacts:

vendor/bin/domain-health check example.com --markdown
vendor/bin/domain-health scan example.com example.org --markdown --output=domain-health-report.md

CI/CD Usage

Basic GitHub Actions example:

- name: Domain Health Check
  run: vendor/bin/domain-health check https://example.com --ci --fail-on-warn

Common CI flags:

vendor/bin/domain-health check example.com --ci
vendor/bin/domain-health check example.com --ci --fail-on-warn
vendor/bin/domain-health check example.com --ci --fail-on-missing-header
vendor/bin/domain-health check example.com --ci --fail-on-ssl-days=30
vendor/bin/domain-health check example.com --ci --block-private-targets

The repository also includes a test workflow in .github/workflows/tests.yml that runs linting, coding style checks, PHPStan, and PHPUnit on PHP 8.1, 8.2, and 8.3.

Exit Codes

0: healthy enough to pass.
1: warning found.
2: failed check, invalid input, config error, or CI escalation.

In normal mode, warnings return 1. In CI mode, flags such as --fail-on-warn, --fail-on-missing-header, and --fail-on-ssl-days=30 can escalate selected warnings to exit code 2.

Examples

Console summary for a selected URL-only scan:

[1/2] Scanning https://example.com...
[2/2] Scanning https://invalid domain...
+------------------------+--------+----+------+------+------+
| URL                    | Status | OK | INFO | WARN | FAIL |
+------------------------+--------+----+------+------+------+
| https://example.com    | OK     | 1  | 0    | 0    | 0    |
| https://invalid domain | FAIL   | 0  | 0    | 0    | 1    |
+------------------------+--------+----+------+------+------+

Final Summary: URLs 2 | OK 1 | INFO 0 | WARN 0 | FAIL 1

Markdown report excerpt:

# Domain Health Report

- URL: `https://example.com`
- Status: `warn`
- Exit code: `1`
- Summary: OK 15, INFO 8, WARN 5, FAIL 0

| Check | Status | Message |
| --- | --- | --- |
| URL is valid | OK | URL is valid |
| HTTP Status | OK | HTTP Status: 200 |
| Strict-Transport-Security | WARN | Missing Strict-Transport-Security |

Troubleshooting

Config file not found: check the path passed to --config.

Choose only one output format: use either --json or --markdown, not both.

Unknown check: check the names in --checks or the checks config object.

Timeout must be an integer between 1 and 120 seconds: lower the timeout value or pass a valid integer.

URL is invalid: make sure the target has no whitespace and uses http or https if a scheme is included.

SSL certificate not available: the tool could not fetch or parse the certificate from port 443. The built-in SSL check focuses on certificate metadata and expiry; use a dedicated TLS scanner when you need trust-chain or hostname validation.

Private or local targets are allowed by default for local CLI usage. Use --block-private-targets or "block_private_targets": true when running in public or shared CI environments.

Roadmap

More output formats for CI annotations.
Additional SEO and accessibility checks.
Dedicated TLS trust-chain and hostname validation.
Config presets for common production policies.
More optional integrations while keeping the core package usable without API keys.

Development

composer lint
composer cs
composer analyse
composer test
composer quality

License

MIT

lukman-ss / php-domain-health

Maintainers

Package info

Statistics

Security