Check and diagnostic commands

🌐 Language: 🇻🇳 Tiếng Việt · 🇬🇧 English (current) · 🇯🇵 日本語

Check and diagnostic commands

Introduction

This page describes the commands that tell you what state the site is in: gp247:doctor checks the server, the installation and the security configuration; gp247:info and gp247:core-info show the versions; gp247:cache-rebuild rebuilds the cache. They are all read only (apart from rebuilding the cache), so run them at any time, even on a selling site. It is for site owners and people who run the server. After reading it you understand every line gp247:doctor reports and how to fix it.

At a glance

Use gp247:doctor at three moments:

flowchart LR
    A["Before installing<br/>is the server ready?"] --> B["After install / update<br/>anything to clean?"]
    B --> C["Regularly<br/>still configured safely?"]
  • Three statuses: PASS fine · WARN worth cleaning, does not block · FAIL must be fixed.
  • Any FAIL makes the command exit non-zero — use it as a gate in CI or before installing. WARN does not change the exit code.
  • On an installed site, doctor also checks the security configuration — the same items the System alerts page shows administrators.
  • Need the version to report a bug or check a fix → gp247:info.

gp247:doctor — site health check

  1. In the site folder, type:

    php artisan gp247:doctor
    
  2. Read the result table: each line has the check name, the status and a note (path, count, suggested fix command).

  3. Fix every FAIL line first, then the WARN lines. Run it again until no FAIL is left.

Doctor reads the configuration and the database; it does not open the site over the network (unless you add --probe-headers — see Check the security headers that really reach the browser). Whether http:// redirects to https://, or whether .env can be downloaded from outside, still has to be checked yourself — see Safe production configuration in the Security handbook.

Server and installation

Check What it checks When it fails
php_version PHP 8.3 or newer FAIL — upgrade PHP
ext_pdo, ext_mbstring, ext_openssl, ext_tokenizer, ext_ctype, ext_json Required PHP extensions FAIL — enable the extension
ext_zip, ext_curl, ext_gd, ext_fileinfo Recommended PHP extensions WARN — some features (.zip install, images) do not work
env_file A .env file exists FAIL
writable_storage, writable_bootstrap_cache storage/, bootstrap/cache/ are writable FAIL — fix the folder permissions
writable_app_gp247, writable_public_gp247 app/GP247, public/GP247 are writable WARN — extensions cannot be installed / updated
db_connection The database is reachable FAIL — check DB_* in .env
installed Whether the site is installed WARN when not installed (normal before the first install)

Encryption key and secrets

Check What it checks
encryption_key_dedicated A dedicated GP247_ENCRYPTION_KEY is set for secrets, rather than sharing APP_KEY — see Data encryption
secret_decryptable Encrypted secrets in the configuration can still be decrypted (if not: sign that the key changed without keeping the old one)
backup_post_incident_pending Tasks still open after a "post security incident" restore (change keys, reinstall the code, change database / hosting passwords)

Extensions and look

Check What it checks Fix command
extension_assets An installed extension is missing CSS/JS/images in public/GP247/..., or (from core 3.14.3) has files older than the copy in app/ gp247:ext-publish
extension_data_pending An extension has files newer than the version GP247 recorded (just git pulled, copied over) without its data update gp247:ext-update --local --all
template_source Number of published template files identical to the package — they will not receive fixes gp247:template-prune
file_bom .php / .blade.php files starting with a UTF-8 BOM Save the file again as UTF-8 without BOM
raw_output_scan (WARN, since core 3.12.0) Site templates / plugins (app/GP247/Templates, app/GP247/Plugins) that print a variable with {!! … !!} outside the known safe forms, so text people type is printed as raw HTML; --json lists every file:line Switch to {{ }}

REST API

Check What it checks
api_config_legacy_names .env still uses old, renamed API variable names (skipped while the config is cached)
api_route_gate With routes cached: every REST API route passes through the shared API protection
api_event_retention The API sync event table holds events past their keep time (cleaned automatically on API requests; lower GP247_API_EVENT_DAYS if needed)

Security configuration (installed site)

These checks are only PASS or WARN — even when the admin rates them critical — so they do not change the exit code.

Check WARN when
app_debug APP_DEBUG is on
https APP_URL does not start with https:// or SESSION_SECURE_COOKIE is off (WARN only when APP_ENV=production)
trusted_proxies TRUSTED_PROXIES trusts every source (*, REMOTE_ADDR…) — anyone can set their own IP, so sign-in throttling and IP rules stop working
default_admin_password The active admin account still uses the default password
password_policy The minimum administrator password length is under 12 characters
mfa_enabled The MFA two-factor plugin is not installed or not enabled
api_exposure (Information only, PASS) the REST API / MCP is on
support_line The version line in use has under 6 months of security support left, or none
security_headers (Since core 3.16.0) The emergency switch GP247_SECURITY_HEADERS=0 silences every security header, HSTS is on while the site does not run on HTTPS, or a header is switched off
login_failures (Since core 3.11.0) Signs of administrator password guessing in the last 24 hours, or failed administrator sign-ins are not being recorded
backup_vault_exposed (Since core 3.11.0) The folder holding the backups can be downloaded over the web

Checks from gp247/front (sites with front)

Packages and plugins add checks to the same System alerts list; doctor prints them too, again only PASS or WARN.

Check WARN when
seo_audit (Since front 3.11.0) The store's last SEO check still has problems to fix — doctor only reads the stored result, it does not scan again
tracking_consent (Since front 3.12.0) Tracking code runs while the cookie banner is off, or the store's template does not call meta-head, so its tracking code never runs

Check the security headers that really reach the browser

With --probe-headers, doctor opens the home page (APP_URL) exactly once and compares the security headers the browser really receives with the settings on the Security headers screen:

php artisan gp247:doctor --probe-headers

The security_headers_live line reports WARN when a header is missing, sent twice (by both the web server and GP247), or still arrives although it is switched off. If the page cannot be opened (no domain yet, network blocked), the line is PASS with the note could not check. Details: Security headers.

ℹ️ Available since: gp247/core 3.16.0

Why file_bom is worth checking

A BOM is 3 invisible bytes that many Windows editors add at the start of a file saved as "UTF-8". PHP prints them before anything else, causing "headers already sent" errors, JSON/XML/CSV broken at the first character, or HTML starting with a stray character. The file looks perfectly normal when opened, so only a machine can spot it. Doctor scans app/GP247/** and the source of the gp247/* packages.

How to fix: open the file in an editor and save it again as UTF-8 without BOM (VS Code: click UTF-8 with BOM in the bottom-right status bar → Save with Encoding → UTF-8). Run gp247:doctor again to see the check back at PASS.

gp247:info and gp247:core-info — show versions

Command Prints
gp247:info The version of each installed package (core, front, shop, mcp), whether the site is installed, the number of plugins / templates, the extension library address
gp247:core-info Name, core version and sub-version, home page, source repository
php artisan gp247:info

💡 Tip: to know whether the site has a security fix, compare the package versions gp247:info prints with the tables in the Release notes. The S-Cart version in the admin footer is not reliable after the first composer update — always rely on the package versions.

gp247:cache-rebuild — rebuild the cache

Clears and rebuilds the route and config cache. GP247 calls it itself after installing, enabling, updating an extension and at the end of gp247:update. Run it by hand when you just changed .env or routes and the site has not picked them up.

php artisan gp247:cache-rebuild

Q&A

Q1: Doctor shows WARN lines. Does the site still work?

→ Yes. WARN means something worth cleaning (security, leftover files); it does not block the site. Only FAIL must be fixed now.

Q2: Is it useful to run doctor before installing?

→ Yes — that is one of its main uses. Doctor exists right after composer require, even before installing; the checks that need an installed database are skipped.

Q3: Doctor reports secret_decryptable not passing?

→ The encryption key changed and the old one is gone. Put the old key in GP247_ENCRYPTION_PREVIOUS_KEYS and run gp247:encryption-key-rotate — see Data encryption.

Q4: Doctor shows https WARN on my dev machine?

→ It is a WARN only when APP_ENV=production; other environments show PASS with a note. If you see WARN, check your APP_ENV.

Q5: How do I use doctor in CI?

→ php artisan gp247:doctor --json: the command exits non-zero when there is a FAIL, so the CI step stops by itself. See Scripts, CI & Docker.

Q6: Does the doctor security check replace a security review?

→ No. Doctor only reads the configuration. Go through the full Security checklist.

Change history

Date GP247 version Change
2026-11-22 gp247/core 3.11.0–3.16.0, gp247/front 3.11.0–3.12.0 Lists the other doctor rows that come from System alerts: security_headers, login_failures, backup_vault_exposed, raw_output_scan, seo_audit, tracking_consent; adds --probe-headers (the security_headers_live line)
2026-11-17 gp247/core 3.14.3 extension_assets also reports outdated static files (content differs from the copy in app/), not only missing ones

📅 Last updated: 2026-11-22 · ✍️ Author: GP247