Update docs for 0.7: resolver-first keying, review fixes, language pass#7
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation set to match Phirewall 0.7 behavior, especially around resolver-first client-IP keying, TrustedBotMatcher wiring/signature, OWASP CRS semantics, and a broad language/snippet cleanup pass.
Changes:
- Rework proxy/client-IP guidance to standardize on
Config::setIpResolver($trustedProxyResolver->resolve(...))and remove deprecatedKeyExtractors::*usage from snippets. - Correct/expand feature documentation (TrustedBotMatcher parameters/caching, CRS factory options and
@rxbehavior, presets/companion packages, reset semantics, header behavior). - Clean up examples and prose (remove outdated example rows/counts, fix snippet hazards, tighten wording).
Reviewed changes
Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/services.md | Language pass / wording refinement. |
| docs/index.md | Update marketing feature blurb to match current bot-detection capabilities and naming. |
| docs/getting-started.md | Align onboarding guidance and snippets with resolver-first keying and updated bot safelisting guidance. |
| docs/features/trusted-bots.md | Update trusted-bot throttling keying guidance (client IP / proxy context). |
| docs/features/storage.md | Clarify production store guidance (APCu caveat phrasing). |
| docs/features/safelists-blocklists.md | Update TrustedBotMatcher examples to rely on Config resolver autowiring; update known-scanners count; add companion preset note; align IP resolver wiring. |
| docs/features/rate-limiting.md | Rewrite default-key and proxy sections for resolver-first keying; update KeyExtractors section for deprecations and guidance; align proxy examples. |
| docs/features/owasp-crs.md | Document $maxValuesPerCrsVariable, add tuning guidance via presets, and correct @rx truncation/fail-closed semantics. |
| docs/features/fail2ban.md | Update keying/proxy guidance, remove deprecated extractor snippets, and fix unsafe parsed-body access in examples. |
| docs/features/bot-presets.md | Clarify how presets key on resolved client IP via PortableConfig::keyIp() late binding. |
| docs/features/bot-detection.md | Add companion preset package tip; update TrustedBotMatcher usage and signature docs; tighten wording. |
| docs/features/bad-ip-preset.md | Align bad-IP preset client-IP matching guidance with resolver-first behavior. |
| docs/faq.md | Update proxy/client-IP explanation and examples to resolver-first keying; tighten wording. |
| docs/examples.md | Update example count/list to reflect moved OWASP CRS examples; add companion packages section; tighten framework-integration prose. |
| docs/common-attacks.md | Align proxy/keying guidance and production setup wording with resolver-first behavior. |
| docs/advanced/track-notifications.md | Tighten wording and remove deprecated extractor imports from snippets. |
| docs/advanced/request-context.md | Replace framework-specific JsonResponse with a generic PSR-7 response example; wording pass. |
| docs/advanced/psr17.md | Remove deprecated extractor imports from examples. |
| docs/advanced/presets.md | Minor wording pass. |
| docs/advanced/portable-config.md | Clarify keyIp() behavior as resolver-aware / late-bound; add stronger proxy-header warning. |
| docs/advanced/observability.md | Wording pass to reduce filler/marketing phrasing. |
| docs/advanced/infrastructure.md | Update documentation around request-to-IP default extraction and remove deprecated imports. |
| docs/advanced/dynamic-throttle.md | Fix invalid arrow function syntax; document resetThrottle() limitations and header naming behavior. |
| docs/advanced/discriminator-normalizer.md | Minor wording/clarity edits. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Align the docs with the 0.7 core changes and resolve all findings from the 0.6 documentation review. Resolver-first client-IP keying: - Teach setIpResolver($trustedProxyResolver->resolve(...)) as the single proxy-trust setup; keyless counter rules and PortableConfig::keyIp() key on the resolved client IP. - Document the KeyExtractors::ip() / clientIp() deprecations and drop both from all snippets; TrustedBotMatcher examples omit ipResolver so the matcher autowires the Config resolver. Corrected claims: - @rx overlength values are truncated and matched, engine errors count as a match (was described as "skipped / not matched"). - TrustedBotMatcher constructor signature and parameter table (six parameters, named-arguments guidance, cacheTtl). - Proxy guidance on bot-presets and portable-config matches the actual keyIp() late-binding behavior. - X-RateLimit headers carry no rule name; knownScanners ships 26 patterns; sliding-window counters are not cleared by resetThrottle(). Completeness: - Document Presets::coreRuleSet(), Presets::crsVersion(), and the $maxValuesPerCrsVariable per-variable value cap. - Drop the removed CRS example rows (04/05/14), fix the example count, and cross-link the companion preset packages from the guide flow. - Fix copy-paste fatals (JsonResponse, arrow function with use()) and the unsafe getParsedBody() array access. Language pass over all pages: remove filler and marketing wording and unused imports from snippets.
sascha-egerer
force-pushed
the
docs/update-for-next-release
branch
from
836daed to
f2fa427
Compare
…istered resolver, split the bot-detection blurb
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Align the docs with the 0.7 core changes and resolve all findings from the 0.6 documentation review.
Resolver-first client-IP keying:
Corrected claims:
Completeness:
Language pass over all pages: remove filler and marketing wording and unused imports from snippets.