phpman.config.php.example

<?php
// phpMan configuration — copy to phpman.config.php and adjust.
// Created automatically by install.sh or `make staging` / `make release`.
//
// This file lives in ~/.phpman/ (PHPMAN_HOME), NOT in webroot.
// The webroot only needs a minimal phpman.config.php with one line:
//   define('PHPMAN_HOME', '/home/user/.phpman');
//
// === Minimal config (everything else uses defaults) ===
//   define('PHPMAN_HOME', getenv('HOME') . '/.phpman');
//   define('PHPMAN_BASE_URL', 'https://www.example.com/phpMan.php');
//
// Leave values commented to use defaults in src/config.php.

// --- PHPMAN_HOME ---
// Base directory for all phpMan local data (cache DB, logs, backups).
// PHPMAN_HOME is baked into phpMan.php at deploy time (sed-replaced like
// GIT_DESCRIBE). Uncomment below only if you need to override the baked-in
// value (rare — usually only for staging with ~/.phpman_test).
// define('PHPMAN_HOME', getenv('HOME') . '/.phpman');
// define('PHPMAN_HOME', getenv('HOME') . '/.phpman_test');
// Or override individual paths:
// define('PHPMAN_CACHE_DIR', '/path/to/custom/cache');
// define('PHPMAN_LOG_DIR', '/path/to/custom/logs');
// define('PHPMAN_BACKUP_DIR', '/path/to/custom/backups');
//
// This file is loaded BEFORE src/config.php defines the derived defaults
// (PHPMAN_CACHE_DIR / PHPMAN_LOG_DIR / PHPMAN_BACKUP_DIR), so those constants
// are not available on the right-hand side of a define here — referencing one
// raises "Undefined constant" during bootstrap, on every request. Set the
// directory itself with a literal path, or define PHPMAN_LOG_DIR above first
// and reference that.

// --- Base URL (v4.3.3) ---
// Public web URL of this phpMan instance. Used by CLI scripts (build-index,
// build-sitemap) to generate correct links when running offline.
// Default: PHPMAN_BASE_URL env var, then 'http://localhost:8080/phpMan.php'
// define('PHPMAN_BASE_URL', 'https://www.chedong.com/phpMan.php');

// --- JSON / MCP payload size (v4.11) ---
// Section text kept when serialising a page. Very large pages (info py is
// ~19.5MB of text) would otherwise be held in memory in full just to be
// serialised, which exceeds PHP's memory_limit. Text past the budget is
// dropped, and the payload then carries content_truncated/content_bytes/
// content_lines so consumers can tell how much of each section they got.
// define('PHPMAN_JSON_MAX_CONTENT_BYTES', 1048576);  // total (1MB)
// define('PHPMAN_JSON_MAX_SECTION_BYTES', 524288);   // per section (512KB)

// --- Cache TTL (v4.11) ---
// Unified expiry for PageCache found entries and the TLDR cache, in months
// (1 month = 30 days). not_found entries normally expire after 1 day, with two
// exceptions: mode='search' negatives use the found TTL, and timeout-derived
// negatives use PHPMAN_CACHE_TTL_TIMEOUT (below). The old "emoji output never
// expires" rule went away with the emoji layer (v4.10/v4.12).
// define('PHPMAN_CACHE_TTL_MONTHS', 7);  // 7 months = 210 days
//
// Timeout-derived negative rows (#248): when a render subprocess is killed by
// timeout(1) (exit 124) the result means "could not determine", not "does not
// exist". The row is written once per window with this TTL, so repeated
// enumeration of the same name collapses into one scan without freezing a
// transient failure for a day.
// define('PHPMAN_CACHE_TTL_TIMEOUT', 600);  // 10 minutes

// --- Render subprocess timeout (#248) ---
// Upper bound, in seconds, on every document-render subprocess: man, perldoc,
// pydoc3, ri, info, apropos (see src/exec.php). Without it a single request can
// hold a FastCGI slot for as long as the command runs — production has measured
// 36-second renders whose response body was 34 bytes, and a few of those
// concurrently saturate the mod_fcgid pool so everyone else gets 503.
//
// 15s is chosen to cut the pathological tail without touching working paths:
// `pydoc3 -k` (the pydoc search fallback) measures 9.5s by itself, and mf
// telemetry puts the p50 render at 799ms and the p99 at 4.1s.
//
// Needs timeout(1) from GNU coreutils; if it is not on the host (macOS does not
// ship it), the bound is silently skipped and commands run unbounded as before.
// 0 = no limit.
// define('PHPMAN_CMD_TIMEOUT', 15);
//
// Per-call override for `pydoc3 -k` (#248). The keyword scan measures 10–14s, so
// the global 15s bound sat right on its edge and the same query answered
// differently under load. Raising the *global* bound would weaken the slot
// guarantee for every command, so the scan gets its own:
// define('PHPMAN_PYDOC_K_TIMEOUT', 20);

// --- Machine-format render telemetry (#244, #249) ---
// One line per machine-format render (/markdown, /json, /mcp) that was slow OR
// large, written to its own file — never to phpman_error.log, so that file stays
// a place where "it grew" means something (#251).
//
//   mf mode=man name=zshall sec=1 fmt=markdown elapsed=4164ms peak=94.2MB bytes=1666546
//
// It exists to separate two failures that otherwise leave identical traces: a 5xx
// *with* a matching line means the render finished and delivery failed; a 5xx
// *with no* line means the process died before reaching the end.
//
// The two thresholds are OR'd. Both are needed:
//   - elapsed: a cold render is 400-4200ms, a cache hit 30-90ms, so 500ms keeps
//     the log proportional to pages crawled for the first time.
//   - bytes: the responses that lose their body are LARGE, not slow. Measured
//     production bodies were 77-81KB truncated against 157-646KB full, and all
//     six sampled 500s were warm cache hits rendering in ~150ms — invisible to an
//     elapsed-only threshold (133 lines against 3,102 requests, 4.3%).
//     With this set, compare the logged `bytes=` against the access log's `%b`:
//     they differ when the client left mid-delivery. (Caveat: `%b` is what was
//     sent, so gzipped responses are legitimately smaller.)
//
// 0 on either disables that trigger. Both 0 = no telemetry.
// define('PHPMAN_MF_LOG_MS', 500);
// define('PHPMAN_MF_LOG_BYTES', 65536);
// Literal path on purpose: PHPMAN_LOG_DIR is not defined yet when this file
// loads (see the PHPMAN_HOME section above).
// define('PHPMAN_MF_LOG_FILE', '/path/to/logs/phpman_mf.log');

// --- Google Analytics (v4.4.4+) ---
// Set your GA4 measurement ID to enable pageview tracking.
// Leave empty to disable (default).
// define('PHPMAN_GA_ID', 'G-XXXXXXXXXX');

// --- Google AdSense (v4.9.26+) ---
// Set your AdSense publisher ID to load the adsbygoogle.js loader script.
// Leave empty to disable (default).
//
// NOTE: this only injects the loader — phpman ships no
// <ins class="adsbygoogle"> ad units. Ads therefore appear only if Auto Ads
// is enabled for the site in the AdSense console. Enabling this also widens
// the CSP automatically (script-src / connect-src / frame-src), so no CSP
// edit is needed. Do not set this on staging: serving ads from a test host
// counts as invalid traffic.
//
// Use the ca-pub-... form here — that is what the loader's client= param
// expects. ads.txt uses the bare pub-... form, without the ca- prefix.
// define('PHPMAN_ADSENSE_ID', 'ca-pub-XXXXXXXXXXXXXXXX');

// --- MCP Authentication (#97) ---
// Every POST /mcp request must carry this key in the X-Api-Key header.
// Fail-closed: while it is left empty (the default) the endpoint returns 401
// for every request, so set it to use MCP at all. A random 32-char hex value
// is generated by install.sh; `openssl rand -hex 16` makes one by hand.
// define('MCP_API_KEY', 'your-secret-key-here');

// --- Debug ---
// Set true for development/troubleshooting; false for production.
// define('PHPMAN_DEBUG', false);