Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: improve filters #8117

Merged
merged 4 commits into from
Oct 31, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions user_guide_src/source/incoming/filters.rst
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,12 @@ You should define as many aliases as you need.
$globals
========

The second section allows you to define any filters that should be applied to every request made by the framework.
The second section allows you to define any filters that should be applied to every valid request made by the framework.

You should take care with how many you use here, since it could have performance implications to have too many
run on every request. Filters can be specified by adding their alias to either the before or after array:
run on every request.

Filters can be specified by adding their alias to either the ``before`` or ``after`` array:

.. literalinclude:: filters/005.php

Expand All @@ -130,14 +133,18 @@ Except for a Few URIs

There are times where you want to apply a filter to almost every request, but have a few that should be left alone.
One common example is if you need to exclude a few URI's from the CSRF protection filter to allow requests from
third-party websites to hit one or two specific URI's, while keeping the rest of them protected. To do this, add
third-party websites to hit one or two specific URI's, while keeping the rest of them protected.

To do this, add
an array with the ``except`` key and a URI path (relative to BaseURL) to match as the value alongside the alias:

.. literalinclude:: filters/006.php

Any place you can use a URI path (relative to BaseURL) in the filter settings, you can use a regular expression or, like in this example, use
an asterisk (``*``) for a wildcard that will match all characters after that. In this example, any URI path starting with ``api/``
would be exempted from CSRF protection, but the site's forms would all be protected. If you need to specify multiple
would be exempted from CSRF protection, but the site's forms would all be protected.

If you need to specify multiple
URI paths, you can use an array of URI path patterns:

.. literalinclude:: filters/007.php
Expand Down
2 changes: 1 addition & 1 deletion user_guide_src/source/incoming/filters/004.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
class Filters extends BaseConfig
{
public array $aliases = [
'apiPrep' => [
'api-prep' => [
\App\Filters\Negotiate::class,
\App\Filters\ApiAuth::class,
],
Expand Down
2 changes: 1 addition & 1 deletion user_guide_src/source/incoming/filters/008.php
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ class Filters extends BaseConfig
// ...

public array $methods = [
'post' => ['InvalidChars', 'csrf'],
'post' => ['invalidchars', 'csrf'],
'get' => ['csrf'],
];

Expand Down