Documentation

Rule
in package

Describe scan options for a specific expression.

Table of Contents

Properties

$assignedToGroups  : null|array<string|int, string>
If you want to configure group resolving, you need to configure the appropriated group via `$ruleGroups`.
$blockable  : mixed
$expression  : mixed
$needsRequiredSiblingRule  : mixed
The rule must be fulfilled together with a rule within its group, which does not have this flag, for the group to be resolved.
$queryArgs  : mixed
A list of query argument validations. Example:
$roles  : array<string|int, string>
The roles that are allowed to see this rule. Can be `null` (or undefined, or empty array) if the rule is allowed for all roles.

Methods

__construct()  : mixed
C'tor.
getAssignedToGroups()  : null|array<string|int, string>
Getter.
getBlockable()  : mixed
Getter.
getExpression()  : mixed
Getter.
getQueryArgs()  : mixed
Getter.
hasRole()  : bool
Getter.
isNeedsRequiredSiblingRule()  : mixed
Getter.
urlMatchesQueryArgumentValidations()  : mixed
Check if a given URL matches our query argument validations.
parseUrlQueryEncodedSafe()  : mixed
In some cases, a URL could contain `&#038;` instead of `&`. This function returns the query string decoded from an URL whether it is using `&` or `&#038;`.

Properties

$assignedToGroups

If you want to configure group resolving, you need to configure the appropriated group via `$ruleGroups`.

private null|array<string|int, string> $assignedToGroups

Otherwise, defaults of the group are considered. Means: Without group configured it will be marked as "one rule within the group must-be-resolved".

$blockable

private mixed $blockable

$expression

private mixed $expression

$needsRequiredSiblingRule

The rule must be fulfilled together with a rule within its group, which does not have this flag, for the group to be resolved.

private mixed $needsRequiredSiblingRule

Example:

  1. You have embedded Google Analytics via a self hosted https://wordpress.ci-runner-7.owlsrv.de/?local_ga_js=1 script (RankMath SEO plugin)
  2. Another inline script configures Google Analytics via gtag('config', 'UA-66641795-4', {'anonymize_ip': true} );.
  3. Your content blocker has a set of the following rules / expressions:
    • gtag( (Group 1)
    • G- (Group 1) (for Google Analytics v4 property)
    • ?local_ga-js (Group 2).
<script id="google_gtagjs" src="https://wordpress.ci-runner-7.owlsrv.de/?local_ga_js=1" async>
<script id="google_gtagjs-inline">
window.dataLayer = window.dataLayer || [];function gtag(){dataLayer.push(arguments);}gtag('js', new Date());gtag('config', 'UA-66641795-4', {'anonymize_ip': true} );
</script>

Now, the gtag('js' of Group 1 resolves the group but in real scenario, only G- should be considered to fulfil the group, but we do not have a string G- in the inline-script. We can now configure the gtag( expression to be not part of the group validation and it does not fulfil the group (i.e. not respected at validation-time).

Note: If this is set to true, this does not modify the scan results itself, so an inline script with <script>gtag("something")</script> is still found as scan result, but will never fulfil Group 1.

$queryArgs

A list of query argument validations. Example:

private mixed $queryArgs 
[
     [
         'queryArg' => 'id',
         'isOptional' => true,
         'regExp' => '/^UA-/'
     ]
]

$roles

The roles that are allowed to see this rule. Can be `null` (or undefined, or empty array) if the rule is allowed for all roles.

private array<string|int, string> $roles

Allowed roles:

  • blocker: The rule will be used by the created Content Blocker
  • scanner: The rule will be used by the scanner

Methods

__construct()

C'tor.

public __construct(ScannableBlockable $blockable, string $expression[, null|array<string|int, string> $roles = null ][, string|array<string|int, string> $assignedToGroups = [] ][, array<string|int, array<string|int, mixed>> $queryArgs = [] ][, bool $needsRequiredSiblingRule = false ]) : mixed
Parameters
$blockable : ScannableBlockable
$expression : string
$roles : null|array<string|int, string> = null
$assignedToGroups : string|array<string|int, string> = []
$queryArgs : array<string|int, array<string|int, mixed>> = []
$needsRequiredSiblingRule : bool = false

getAssignedToGroups()

Getter.

public getAssignedToGroups() : null|array<string|int, string>
Return values
null|array<string|int, string>

getBlockable()

Getter.

public getBlockable() : mixed
Tags
codeCoverageIgnore

getExpression()

Getter.

public getExpression() : mixed

getQueryArgs()

Getter.

public getQueryArgs() : mixed
Tags
codeCoverageIgnore

hasRole()

Getter.

public hasRole(string $role) : bool
Parameters
$role : string
Return values
bool

isNeedsRequiredSiblingRule()

Getter.

public isNeedsRequiredSiblingRule() : mixed

urlMatchesQueryArgumentValidations()

Check if a given URL matches our query argument validations.

public urlMatchesQueryArgumentValidations(string $url) : mixed
Parameters
$url : string

parseUrlQueryEncodedSafe()

In some cases, a URL could contain `&#038;` instead of `&`. This function returns the query string decoded from an URL whether it is using `&` or `&#038;`.

protected parseUrlQueryEncodedSafe(string $url[, int $iteration = 0 ]) : mixed
Parameters
$url : string
$iteration : int = 0

As this function is recursively used, we need to pass the iteration so we can e.g. avoid memory leaks when using a $url like https://www.google.com/recaptcha/api.js?hl=en&ver=6.0.2#038;render=explicit. Why? As you can see in the URL, #038; is used without & -> falsy query args, but should be treated as-is.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results