docs: improve descriptions to Filters#9002

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.

Sign up for GitHub

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

Merged
kenjis merged 4 commits into from
Jun 25, 2024
Merged

docs: improve descriptions to Filters #9002

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a69c876
docs: update outdated description for HTTP method names
kenjis Jun 25, 2024
33dc973
docs: add empty lines
kenjis Jun 25, 2024
75a9350
docs: small improvements
kenjis Jun 25, 2024
9a9a9a0
docs: add note for HTTP method names lowercase
kenjis Jun 25, 2024
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
20 changes: 13 additions & 7 deletions user_guide_src/source/incoming/filters.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
Because a controller method might be accessible by different URLs than you think.
For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
and the URI paths specified in the filter could be different.
See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down
9 changes: 5 additions & 4 deletions user_guide_src/source/incoming/routing.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
(not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
:ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
docs: improve descriptions to Filters#9002

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.

 Sign up for GitHub

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

 Merged

kenjis
merged 4 commits into

from

Jun 25, 2024
 Merged


docs: improve descriptions to Filters
#9002
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a69c876

docs: update outdated description for HTTP method names


kenjis Jun 25, 2024
33dc973

docs: add empty lines


kenjis Jun 25, 2024
75a9350

docs: small improvements


kenjis Jun 25, 2024
9a9a9a0

docs: add note for HTTP method names lowercase


kenjis Jun 25, 2024

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


20 changes: 13 additions & 7 deletions
user_guide_src/source/incoming/filters.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
 Because a controller method might be accessible by different URLs than you think.
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
 it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
 and the URI paths specified in the filter could be different.
 See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
 because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
 Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
 ``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down

9 changes: 5 additions & 4 deletions
user_guide_src/source/incoming/routing.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
 (not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
 :ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
 for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: improve descriptions to Filters#9002

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.

 Sign up for GitHub

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

 Merged

kenjis
merged 4 commits into

from

Jun 25, 2024
 Merged


docs: improve descriptions to Filters
#9002
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a69c876

docs: update outdated description for HTTP method names


kenjis Jun 25, 2024
33dc973

docs: add empty lines


kenjis Jun 25, 2024
75a9350

docs: small improvements


kenjis Jun 25, 2024
9a9a9a0

docs: add note for HTTP method names lowercase


kenjis Jun 25, 2024

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


20 changes: 13 additions & 7 deletions
user_guide_src/source/incoming/filters.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
 Because a controller method might be accessible by different URLs than you think.
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
 it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
 and the URI paths specified in the filter could be different.
 See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
 because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
 Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
 ``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down

9 changes: 5 additions & 4 deletions
user_guide_src/source/incoming/routing.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
 (not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
 :ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
 for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: improve descriptions to Filters#9002

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.

 Sign up for GitHub

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

 Merged

kenjis
merged 4 commits into

from

Jun 25, 2024
 Merged


docs: improve descriptions to Filters
#9002
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a69c876

docs: update outdated description for HTTP method names


kenjis Jun 25, 2024
33dc973

docs: add empty lines


kenjis Jun 25, 2024
75a9350

docs: small improvements


kenjis Jun 25, 2024
9a9a9a0

docs: add note for HTTP method names lowercase


kenjis Jun 25, 2024

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


20 changes: 13 additions & 7 deletions
user_guide_src/source/incoming/filters.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
 Because a controller method might be accessible by different URLs than you think.
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
 it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
 and the URI paths specified in the filter could be different.
 See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
 because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
 Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
 ``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down

9 changes: 5 additions & 4 deletions
user_guide_src/source/incoming/routing.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
 (not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
 :ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
 for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
docs: improve descriptions to Filters#9002

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.

 Sign up for GitHub

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

 Merged

kenjis
merged 4 commits into

from

Jun 25, 2024
 Merged


docs: improve descriptions to Filters
#9002
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a69c876

docs: update outdated description for HTTP method names


kenjis Jun 25, 2024
33dc973

docs: add empty lines


kenjis Jun 25, 2024
75a9350

docs: small improvements


kenjis Jun 25, 2024
9a9a9a0

docs: add note for HTTP method names lowercase


kenjis Jun 25, 2024

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


20 changes: 13 additions & 7 deletions
user_guide_src/source/incoming/filters.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
 Because a controller method might be accessible by different URLs than you think.
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
 it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
 and the URI paths specified in the filter could be different.
 See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
 because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
 Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
 ``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down

9 changes: 5 additions & 4 deletions
user_guide_src/source/incoming/routing.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
 (not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
 :ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
 for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: improve descriptions to Filters#9002

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.

 Sign up for GitHub

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

 Merged

kenjis
merged 4 commits into

from

Jun 25, 2024
 Merged


docs: improve descriptions to Filters
#9002
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a69c876

docs: update outdated description for HTTP method names


kenjis Jun 25, 2024
33dc973

docs: add empty lines


kenjis Jun 25, 2024
75a9350

docs: small improvements


kenjis Jun 25, 2024
9a9a9a0

docs: add note for HTTP method names lowercase


kenjis Jun 25, 2024

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


20 changes: 13 additions & 7 deletions
user_guide_src/source/incoming/filters.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
 Because a controller method might be accessible by different URLs than you think.
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
 it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
 and the URI paths specified in the filter could be different.
 See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
 because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
 Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
 ``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down

9 changes: 5 additions & 4 deletions
user_guide_src/source/incoming/routing.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
 (not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
 :ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
 for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
docs: improve descriptions to Filters#9002

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.

 Sign up for GitHub

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

 Merged

kenjis
merged 4 commits into

from

Jun 25, 2024
 Merged


docs: improve descriptions to Filters
#9002
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a69c876

docs: update outdated description for HTTP method names


kenjis Jun 25, 2024
33dc973

docs: add empty lines


kenjis Jun 25, 2024
75a9350

docs: small improvements


kenjis Jun 25, 2024
9a9a9a0

docs: add note for HTTP method names lowercase


kenjis Jun 25, 2024

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


20 changes: 13 additions & 7 deletions
user_guide_src/source/incoming/filters.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
 Because a controller method might be accessible by different URLs than you think.
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
 it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
 and the URI paths specified in the filter could be different.
 See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
 because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
 Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
 ``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down

9 changes: 5 additions & 4 deletions
user_guide_src/source/incoming/routing.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
 (not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
 :ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
 for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
docs: improve descriptions to Filters#9002

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.

 Sign up for GitHub

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

 Merged

kenjis
merged 4 commits into

from

Jun 25, 2024
 Merged


docs: improve descriptions to Filters
#9002
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


4 commits


Select commit
Hold shift + click to select a range
a69c876

docs: update outdated description for HTTP method names


kenjis Jun 25, 2024
33dc973

docs: add empty lines


kenjis Jun 25, 2024
75a9350

docs: small improvements


kenjis Jun 25, 2024
9a9a9a0

docs: add note for HTTP method names lowercase


kenjis Jun 25, 2024

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


20 changes: 13 additions & 7 deletions
user_guide_src/source/incoming/filters.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,7 +82,7 @@ Configuring Filters
There are two ways to configure filters when they get run. One is done in
**app/Config/Filters.php**, the other is done in **app/Config/Routes.php**.

If you want to specify filter to a specific route, use **app/Config/Routes.php**
If you want to specify filters to defined routes, use **app/Config/Routes.php**
and see :ref:`URI Routing <applying-filters>`.

.. Note:: The safest way to apply filters is to :ref:`disable auto-routing <use-defined-routes-only>`, and :ref:`set filters to routes <applying-filters>`.
Expand All@@ -95,9 +95,11 @@ configure exactly when the filters run.

.. Warning:: It is recommended that you should always add ``*`` at the end of a URI in the filter settings.
 Because a controller method might be accessible by different URLs than you think.
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index``,
 For example, when :ref:`auto-routing-legacy` is enabled, if you have ``Blog::index()``,
 it can be accessible with ``blog``, ``blog/index``, and ``blog/index/1``, etc.

.. _filters-aliases:

$aliases
--------

Expand All@@ -106,7 +108,9 @@ filters to run:

.. literalinclude:: filters/003.php

Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
Aliases are mandatory and if you try to use a full class name later, the system will throw an error.

Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter's class and you're done.

Expand DownExpand Up@@ -170,7 +174,7 @@ an array with the ``except`` key and a URI path (relative to BaseURL) to match a
 and the URI paths specified in the filter could be different.
 See :ref:`upgrade-447-filter-paths` for details.

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
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 above, 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.

Expand All@@ -186,17 +190,19 @@ $methods
 because :ref:`auto-routing-legacy` permits any HTTP method to access a controller.
 Accessing the controller with a method you don't expect could bypass the filter.

You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in **lowercase**. It's value would be an array of filters to run:
You can apply filters to all requests of a certain HTTP method, like ``POST``, ``GET``, ``PUT``, etc.
It's value would be an array of filters to run:

.. literalinclude:: filters/008.php

.. note:: Unlike the ``$globals`` or the
 ``$filters`` properties, these will only run as before filters.

In addition to the standard HTTP methods, this also supports one special case: ``cli``. The ``cli`` method would apply to
In addition to the standard HTTP methods, this also supports one special case: ``CLI``. The ``CLI`` method would apply to
all requests that were run from the command line.

.. note:: Prior to v4.5.0, due to a bug, you needed to specify the HTTP method names in **lowercase**.

$filters
--------

Expand Down

9 changes: 5 additions & 4 deletions
user_guide_src/source/incoming/routing.rst

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -388,12 +388,13 @@ Applying Filters
================

You can alter the behavior of specific routes by supplying filters to run before or after the controller. This is especially handy during authentication or api logging.

The value for the filter can be a string or an array of strings:

* matching the aliases defined in **app/Config/Filters.php**.
* filter classnames

See :doc:`Controller Filters <filters>` for more information on setting up filters.
See :ref:`Controller Filters <filters-aliases>` for more information on defining aliases.

.. Warning:: If you set filters to routes in **app/Config/Routes.php**
 (not in **app/Config/Filters.php**), it is recommended to disable Auto Routing (Legacy).
Expand All@@ -405,7 +406,7 @@ See :doc:`Controller Filters <filters>` for more information on setting up filte
Alias Filter
------------

You specify an alias defined in **app/Config/Filters.php** for the filter value:
You specify an alias :ref:`defined in app/Config/Filters.php <filters-aliases>` for the filter value:

.. literalinclude:: routing/034.php

Expand All@@ -418,7 +419,7 @@ Classname Filter

.. versionadded:: 4.1.5

You specify a filter classname for the filter value:
You can specify a filter classname for the filter value:

.. literalinclude:: routing/036.php

Expand All@@ -435,7 +436,7 @@ Multiple Filters
 :ref:`Upgrading from 4.1.4 to 4.1.5 <upgrade-415-multiple-filters-for-a-route>`
 for the details.

You specify an array for the filter value:
You can specify an array for the filter value:

.. literalinclude:: routing/037.php

Expand Down