Document 0.10.0 features

[sascha-egerer]

No description provided.

[Copilot]

Pull request overview

This PR updates the Phirewall documentation for the 0.10.0 feature set, focusing on (1) new/clarified fail-open vs fail-closed behavior, (2) throttle scoping via a new scope closure parameter, and (3) updated semantics for post-handler banning/signaling.

Changes:

• Document how fail-open/fail-closed affects pattern-blocklist regex match-time engine errors.
• Add scope to throttle docs (add(), sliding(), multi()) and update examples to use scope: instead of “null-returning key” patterns where appropriate.
• Clarify post-handler signal banning behavior and the opt-in behavior to block the banning request.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/getting-started.md	Adds fail-open/fail-closed note for pattern-blocklist regex match-time errors.
docs/features/rate-limiting.md	Documents new throttle scope parameter and updates guidance/examples.
docs/features/fail2ban.md	Clarifies signal-only rule behavior and references new “block on signal ban” option.
docs/faq.md	Adds a concise note about regex engine-error behavior under fail-open/fail-closed.
docs/examples.md	Updates multiple throttle examples to prefer scope: over custom rule construction.
docs/common-attacks.md	Updates attack-mitigation examples to use scope: + keyless throttles where applicable.
docs/advanced/request-context.md	Explains post-handler banning behavior and the new opt-in to block the banning request.
docs/advanced/dynamic-throttle.md	Refactors conditional throttling guidance toward scope: and keyless defaults.
docs/advanced/architecture.md	Updates architecture description for post-handler signal processing and optional blocking.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/advanced/dynamic-throttle.md:327

• This inline example uses new ThrottleRule(...) without importing the class, which can be confusing when copy/pasting. Since the preceding text already names the fully-qualified class, prefer using the FQCN in the snippet (or add an explicit use in a code block).

For a matcher-backed scope (an `IpMatcher` instance, a preset filter), construct a `Flowd\Phirewall\Config\Rule\ThrottleRule` directly and register it via `$config->throttles->addRule(new ThrottleRule(..., scope: $matcher))`.

docs/advanced/request-context.md:49

• The text claims there is a portable option blockOnSignalBan, but docs/advanced/portable-config.md does not list such an option in its Options table. Either document this portable option there as part of the PR, or remove the portable-option mention here to avoid pointing readers to a non-existent/undocumented setting.

By default the banning signal never changes the current response: the handler's response is delivered as-is and the ban takes effect from the next request. Opt in to a 403 for the banning request itself with `$config->enableBlockOnSignalBan()` (portable option `blockOnSignalBan`) - the middleware then replaces the handler response with the regular blocked response, including `Retry-After` for allow2ban bans.