Download the PHP package ikidnapmyself/seo-checkup without Composer

seo-checkup

A PHP toolbox that runs 29 SEO checks against a live URL and returns each result as a plain array — as a library, a seo-checkup command, or a GitHub Action.

Requirements

• PHP 8.3+
• ext-dom
• ext-mbstring
• ext-zlib

Install

Usage

Every example in this README is real output. The library examples are captured through the library's own test suite against the bundled fixture (tests/fixtures/complete.html) rather than against the live site in the snippet — so data shows the fixture's title, not what example.com serves. Each example says so when it was captured differently (the CLI example below was run against the live example.com).

Every check returns the same envelope: url is the URL you asked for — the checks themselves reason about where the request finally landed, which differs whenever a redirect was followed — status is the fetched page's, headers are the response headers, service is a human-readable label derived from the method name, time is a Unix timestamp of when the check ran, and data is the check's own result — the only field that differs from check to check.

Injecting a client

The constructor takes an optional PSR-18 HTTP client as its second argument:

Leave it out and the library builds its own Guzzle client with sane timeouts and a redirect cap. Pass one in and every request Analyze makes — the page itself, robots.txt, favicon probes, broken-link probes, external scripts for googleAnalytics() — goes through it instead. This is the seam that makes the library testable: the test suite injects a fake client and fixture HTML, and never touches the network. A third, optional argument accepts a DnsLookup implementation for the same reason — it backs the DNS lookup that spfRecord() uses.

Command line

The package ships a seo-checkup command that runs the checks above against one or more pages, judges the results against a small rule catalogue, and exits with a code CI can act on.

Install it per project:

or globally, which puts seo-checkup on your PATH (run composer global config bin-dir --absolute to find the directory to add to PATH if it is not there already):

Check groups

--checks takes group names, individual check (method) names, or a mix; output order is always catalogue order, however the flags were typed.

Without --checks, every group runs — except that the network group is skipped when the host is local (localhost and *.localhost, 127.* loopback addresses, [::1], and the *.local / *.test dev TLDs): HTTPS, SPF and domain length say nothing about a dev server. An explicit --checks is honoured exactly as given, local host or not.

Rules and --fail-on

The checks report data; the rules judge it. Every run evaluates all 13 rules and prints a verdict per rule, but only the rules named in --fail-on can fail the run (exit code 1). A rule whose check was not selected is reported as skip and never fails the run, so a narrow --checks cannot trip --fail-on by accident.

--fail-on also takes three presets: recommended expands to broken-links, missing-title, missing-description, missing-canonical and not-https; all expands to every rule; none expands to nothing (report only — the default when --fail-on is not given at all).

Output

• text (default) — the report below; coloured when stdout is a TTY.
• md — GitHub-flavoured Markdown, one verdict table per page with the raw check data collapsed; made for CI job summaries.
• json — machine-readable: {failed, pages: [{url, status, verdicts: [{rule, result, message, failsRun}], checks: {method: envelope}}]} where each envelope is the unmodified check envelope from the library.

--output=FILE writes the report to a file instead of stdout.

--text=FILE, --md=FILE and --json=FILE write additional reports from the same run — one fetch, several formats. - sends one to stdout instead of a file. --format/--output still choose the primary report (text on stdout by default), and two formats aiming at stdout is an error.

Config file

The CLI reads seo-checkup.json from the current directory when it exists, or the file named by --config. Precedence is flags > file > defaults. Recognised keys: url, paths, checks, fail-on, format, timeout, overrides.

overrides maps a path glob to per-page settings: each glob is matched with fnmatch against the resolved page URL's path (no query), and * crosses / — /blog/* matches /blog/2026/01/post too. The file is validated eagerly: an unknown rule or check name, an unknown format, or a non-positive timeout is an error (exit 2) before anything is fetched.

Example

A real run, captured on 2026-08-20 against the live example.com; the exit code was 1 because recommended includes missing-description and missing-canonical, and example.com has neither:

GitHub Action

The repository doubles as a composite GitHub Action: on pull requests it checks the branch — either a preview URL your deploy produced, or a dev server the action starts in the runner — and on master it checks production. It prints the report in the step log, writes the verdict tables to the job summary, annotates every failed rule (error when it fails the step, warning otherwise), uploads the JSON report as an artifact, and fails the step on exactly the rules you choose.

Inputs

Outputs

Workflow

fail-on, paths and checks normally live in the repository's own seo-checkup.json, which the CLI auto-discovers after checkout — that keeps both steps this short, and the url input overrides the file's url, so the same file serves the PR step and the production step.

If your deploy already produces a preview URL, check that instead of serving locally (note that actions/deploy-pages itself needs pages: write and id-token: write — the no-extra-permissions statement below is about the seo-checkup action only):

Notes

• The action needs no permissions beyond the default contents: read.
• It installs PHP via setup-php (the php-version input) and the package via Composer: running the action at a release tag vX.Y.Z installs that package version, vX the latest release in that major, and a branch or SHA reference runs the action's own checkout. Use @v1 for the latest 1.x, or pin @v1.1.0.
• artifact-name must be unique per workflow run if the action runs more than once (matrix builds, several sites).
• Runs against a local host (the serve mode's default) skip the network check group by default, like the CLI.
• Each page is fetched once; the step log, the job summary and the artifact are all rendered from that single run.
• $GITHUB_STEP_SUMMARY caps at 1 MiB; on big multi-page runs, narrow --checks (the raw check data dominates the summary's size).

Checks

All 29 checks are camelCase methods on Analyze. Each returns the envelope above; the data column below describes what data holds.

Errors

The constructor can throw:

• SEOCheckup\Exception\InvalidUrlException — the URL is malformed, has no host, uses a scheme other than http/https, or the host/path fails validation.
• SEOCheckup\Exception\RequestFailedException — the initial request could not be completed (DNS failure, connection refused, timeout, a redirect chain still going after Fetcher::MAX_REDIRECTS hops, and so on).

A URL that merely needs encoding is not invalid: spaces and other characters RFC 3986 does not allow in a path or query are percent-encoded on the way out, exactly as a browser does. URL-embedded credentials (https://user:[email protected]/) are sent as Basic auth. Unicode hostnames are converted to punycode when ext-intl is installed; without it the raw hostname is handed to the transport as-is.

Both extend SEOCheckup\Exception\SeoCheckupException. Captured from a real run:

Once construction succeeds, individual checks do not throw. A check that has nothing to report returns an empty value for its data — '', false, or an empty array, depending on the check — rather than raising an exception. robotsFile() and favicon(), for example, return false and '' respectively when nothing is found, and network probes used inside checks (brokenLinks(), favicon()) treat an unreachable target as status 0 rather than propagating the failure.

Security

Analyzing a page means fetching URLs that page controls. brokenLinks() probes the page's own links, favicon() probes its declared icon hrefs, and googleAnalytics() downloads its external scripts — all of them following redirects, and none of them restricting the host or IP that gets contacted. brokenLinks() then reports the status of every URL it probed.

The consequence is worth stating plainly: a page you analyze can make this library issue requests to hosts you did not choose, including addresses inside your own network (http://127.0.0.1:8080/, http://169.254.169.254/, an internal hostname), and brokenLinks() hands the resulting statuses back to the caller. That is enough to enumerate what is reachable from wherever the analysis runs. Treat the URL you pass to Analyze as untrusted input, and do not run the library against arbitrary user-supplied URLs from inside a network you care about.

The library ships no allowlist of its own, because the right policy depends on your network. The PSR-18 constructor argument is exactly where you install one: the client you inject sees every outgoing request, so a wrapping ClientInterface — or a Guzzle handler/middleware — can resolve the host, reject private and link-local ranges, pin an allowlist, or refuse redirects to hosts outside it, before the request goes out.

These caveats apply equally to the CLI and the GitHub Action, which fetch the same page-controlled URLs from wherever they run.

Upgrading from 0.1

• All methods are camelCase now (BrokenLinks() → brokenLinks(), MetaTitle() → metaTitle(), and so on for all 29). There are no deprecated PascalCase aliases.
• PreRequirements is gone. The library no longer builds a new HTTP client per request; a PSR-18 client is injected once, in the constructor.
• canonicalTag() (formerly CanonicalTag()) returns the resolved canonical href, e.g. https://example.com/canonical. It used to return the literal string "canonical".
• characterSet() (formerly CharacterSet()) returns '' when the Content-Type header has no charset, instead of raising a PHP error on explode(';')[1].
• The package name is now ikidnapmyself/seo-checkup; the namespace is unchanged, SEOCheckup\.
• The constructor's second argument is now an optional PSR-18 ClientInterface, not a superglobal-touching base class.