API Documentation
\
DevOwl
CacheInvalidate
caches
Customize
controls
DeliverAnonymousAsset
FastHtmlTag
finder
match
Freemium
HeadlessContentBlocker
finder
match
matcher
plugins
imagePreview
scanner
Multilingual
RealCookieBanner
base
comp
language
migration
import
lite
comp
language
presets
blocker
rest
settings
view
blocker
customize
banner
overrides
interfce
settings
presets
free
blocker
middleware
pro
blocker
rest
scanner
settings
view
blockable
blocker
checklist
customize
banner
individual
navmenu
shortcode
RealProductManagerWpClient
announcement
client
license
rest
view
RealQueue
queue
rest
RealUtils
cross
view
TcfVendorListNormalize
MatthiasWeb
Utils

\DevOwl\HeadlessContentBlockerHeadlessContentBlocker

Initialize a new headless content blocker.

Summary

Methods
Properties
Constants
__construct()
addFinder()
addCallback()
addSelectorSyntaxFunction()
modifyAny()
modifyHtml()
getSelectorSyntaxFunction()
addPlugin()
addTagAttributeMap()
addSelectorSyntaxMap()
addBlockables()
setBlockables()
addAfterSetupCallback()
addBeforeMatchCallback()
addCheckResultCallback()
addBlockedMatchCallback()
addNotBlockedMatchCallback()
addKeepAlwaysAttributes()
addKeepAlwaysAttributesIfClass()
addKeepAlwaysAttributesCallback()
addSkipInlineScriptVariableAssignments()
addSkipInlineScriptVariableAssignmentsCallback()
setInlineStyleDummyUrlPath()
addVisualParentCallback()
addBlockableStringExpressionCallback()
addReplaceAlwaysAttributes()
addInlineStyleShouldBeExtractedCallback()
addInlineStyleModifyDocumentsCallback()
addInlineStyleBlockRuleCallback()
addVisualParentIfClass()
setup()
runCheckResultCallback()
runKeepAlwaysAttributesCallback()
runSkipInlineScriptVariableAssignmentsCallback()
runInlineStyleShouldBeExtractedByCallback()
runInlineStyleModifyDocumentsCallback()
runInlineStyleBlockRuleCallback()
runVisualParentCallback()
runBlockableStringExpressionCallback()
blockablesToHosts()
getBlockableById()
setAllowMultipleBlockerResults()
isAllowMultipleBlockerResults()
getTagAttributeMap()
getSelectorSyntaxMap()
getBlockables()
getKeepAlwaysAttributes()
getKeepAlwaysAttributesIfClass()
getSkipInlineScriptVariableAssignments()
getInlineStyleDummyUrlPath()
getReplaceAlwaysAttributes()
getVisualParentIfClass()
getPlugins()
getFinderToMatcher()
getPluginsByClassName()
No public properties found
TAG_ATTRIBUTE_MAP_LINKABLE
processMatch()
runAfterSetupCallback()
runBeforeMatchCallback()
runBlockedMatchCallback()
runNotBlockedMatchCallback()
init()
No protected properties found
N/A
No private methods found
$callbacks
$selectorSyntaxFunctions
$finder
$isSetup
$afterSetupCallbacks
$beforeMatchCallbacks
$checkResultCallbacks
$blockedMatchCallbacks
$notBlockedMatchCallbacks
$keepAlwaysAttributes
$keepAlwaysAttributesIfClass
$keepAlwaysAttributesByCallback
$skipInlineScriptVariableAssignments
$skipInlineScriptVariableAssignmentsByCallback
$inlineStyleDummyUrlPath
$inlineStyleShouldBeExtractedByCallback
$inlineStyleModifyDocumentsByCallback
$inlineStyleBlockRuleByCallback
$visualParentCallback
$blockableStringExpressionCallback
$replaceAlwaysAttributes
$visualParentIfClass
$allowMultipleBlockerResults
$blockablesToHostsCache
$plugins
$blockables
$finderToMatcher
$tagAttributeMap
$selectorSyntaxMap
N/A

Constants

TAG_ATTRIBUTE_MAP_LINKABLE

TAG_ATTRIBUTE_MAP_LINKABLE ='linkable'

The tag-attribute map for the usual links like `script[src],link[href],iframe[href]`.

Properties

$callbacks

$callbacks :array<mixed,callable>

Callbacks.

Type

array<mixed,callable>

$selectorSyntaxFunctions

$selectorSyntaxFunctions :array<mixed,callable>

Callbacks for `SelectorSyntaxAttributeFunction`.

Type

array<mixed,callable>

$isSetup

$isSetup :

Type

$afterSetupCallbacks

$afterSetupCallbacks :

Type

$beforeMatchCallbacks

$beforeMatchCallbacks :

Type

$checkResultCallbacks

$checkResultCallbacks :

Type

$blockedMatchCallbacks

$blockedMatchCallbacks :

Type

$notBlockedMatchCallbacks

$notBlockedMatchCallbacks :

Type

$keepAlwaysAttributes

$keepAlwaysAttributes :

Type

$keepAlwaysAttributesIfClass

$keepAlwaysAttributesIfClass :

Type

$keepAlwaysAttributesByCallback

$keepAlwaysAttributesByCallback :

Type

$skipInlineScriptVariableAssignments

$skipInlineScriptVariableAssignments :

Type

$skipInlineScriptVariableAssignmentsByCallback

$skipInlineScriptVariableAssignmentsByCallback :

Type

$inlineStyleDummyUrlPath

$inlineStyleDummyUrlPath :

Type

$inlineStyleShouldBeExtractedByCallback

$inlineStyleShouldBeExtractedByCallback :

Type

$inlineStyleModifyDocumentsByCallback

$inlineStyleModifyDocumentsByCallback :

Type

$inlineStyleBlockRuleByCallback

$inlineStyleBlockRuleByCallback :

Type

$visualParentCallback

$visualParentCallback :

Type

$blockableStringExpressionCallback

$blockableStringExpressionCallback :

Type

$replaceAlwaysAttributes

$replaceAlwaysAttributes :

Type

$visualParentIfClass

$visualParentIfClass :

Type

$allowMultipleBlockerResults

$allowMultipleBlockerResults :

Type

$blockablesToHostsCache

$blockablesToHostsCache :

Type

$plugins

$plugins :array<mixed,\DevOwl\HeadlessContentBlocker\AbstractPlugin[]>

List of registered plugins pointing to their object instance.

Type

array<mixed,\DevOwl\HeadlessContentBlocker\AbstractPlugin[]>

$finderToMatcher

$finderToMatcher :

Type

$tagAttributeMap

$tagAttributeMap :

Type

$selectorSyntaxMap

$selectorSyntaxMap :array<mixed,string>

Selector syntax map.

Type

array<mixed,string>

Methods

__construct()

__construct()

C'tor.

addCallback()

addCallback(callable  $callback)

Add a callable. The first parameter is the HTML string and should return HTML.

Parameters

callable $callback

addSelectorSyntaxFunction()

addSelectorSyntaxFunction(string  $functionName,callable  $callback)

Add a callable for a Selector Syntax function.

The callback gets the following parameters and expects boolean as result:

SelectorSyntaxAttributeFunction $function, SelectorSyntaxMatch $match, mixed $value

Parameters

string $functionName
callable $callback

modifyAny()

modifyAny(string  $mixed)

Allows to parse and modify any content. This could be e.g. a JSON string (each value gets iterated and parsed if it is a HTML).

Parameters

string $mixed

modifyHtml()

modifyHtml(string  $html)

Allow to parse and modify a given HTML string.

Parameters

string $html

getSelectorSyntaxFunction()

getSelectorSyntaxFunction(string  $functionName)

Get a defined selector syntax function by name.

Parameters

string $functionName

addPlugin()

addPlugin(string  $pluginName)

Register a complete plugin to this headless content blocker.

Parameters

string $pluginName

The class name of the plugin (extended from AbstractPlugin)

addTagAttributeMap()

addTagAttributeMap(array<mixed,string>  $tags,array<mixed,string>  $attributes = array(),string  $mapName = self::TAG_ATTRIBUTE_MAP_LINKABLE)

Respect additional tags and attributes for a given map. For example, there is the `self::TAG_ATTRIBUTE_MAP_LINKABLE` map which respects known linkable tags like `script[src],link[href],iframe[href]`.

Parameters

array<mixed,string> $tags

Additional tags to consider for the passed map
array<mixed,string> $attributes

Additional tags to consider for the passed map
string $mapName

Default is self::TAG_ATTRIBUTE_MAP_LINKABLE

addSelectorSyntaxMap()

addSelectorSyntaxMap(array<mixed,string>  $selectorSyntax)

Respect additional selector-syntax as blockable candiates. Keep in mind that this selector-syntax does not automatically block the defined attribute. Instead, you need to create a custom plugin / callback for `checkResult`.

Parameters

array<mixed,string> $selectorSyntax

addBlockables()

addBlockables(array<mixed,\DevOwl\HeadlessContentBlocker\AbstractBlockable>  $blockables)

Add a blockable item. In general, this are the URLs and elements you want to block.

Parameters

array<mixed,\DevOwl\HeadlessContentBlocker\AbstractBlockable> $blockables

setBlockables()

setBlockables(array<mixed,\DevOwl\HeadlessContentBlocker\AbstractBlockable>  $blockables)

Set blockable items. In general, this are the URLs and elements you want to block.

Parameters

array<mixed,\DevOwl\HeadlessContentBlocker\AbstractBlockable> $blockables

addAfterSetupCallback()

addAfterSetupCallback(callable  $callback)

Add a callable after the content blocker got setup.

Parameters

callable $callback

addBeforeMatchCallback()

addBeforeMatchCallback(callable  $callback)

Add a callable before a match got found (this does not mean that the match is blocked!).

Parameters: AbstractMatcher $matcher, AbstractMatch $match.

Parameters

callable $callback

addCheckResultCallback()

addCheckResultCallback(callable  $callback)

Add a callable after a match got found and the matcher decided if it should be blocked or not.

Parameters: BlockedResult $result, AbstractMatcher $matcher, AbstractMatch $match. This function needs to return a BlockedResult instance.

Parameters

callable $callback

addBlockedMatchCallback()

addBlockedMatchCallback(callable  $callback)

Add a callable after a blocked match got found so you can alter the match again. Parameters: `BlockedResult $result, AbstractMatcher $matcher, AbstractMatch $match`.

Parameters

callable $callback

addNotBlockedMatchCallback()

addNotBlockedMatchCallback(callable  $callback)

Add a callable after a blocked match got not found, but a match. Parameters: `BlockedResult $result, AbstractMatcher $matcher, AbstractMatch $match`.

Parameters

callable $callback

addKeepAlwaysAttributes()

addKeepAlwaysAttributes(array<mixed,string>  $attributes)

In some cases we need to keep the attributes as original instead of prefix it with `consent-original-`.

Keep in mind, that no external data should be loaded if the attribute is set!

Parameters

array<mixed,string> $attributes

addKeepAlwaysAttributesIfClass()

addKeepAlwaysAttributesIfClass(array<mixed,string[]>  $classToAttributesMap)

See `addKeepAlwaysAttributes`, but consider the keep only if the found match has a given class.

Parameters

array<mixed,string[]> $classToAttributesMap

addKeepAlwaysAttributesCallback()

addKeepAlwaysAttributesCallback(callable  $callback)

Add a callable after a match got found and the matcher decided if it should be blocked or not.

Parameters: string[] $keepAttributes, AbstractMatcher $matcher, AbstractMatch $match. This function needs to return a string[] array!

Parameters

callable $callback

addSkipInlineScriptVariableAssignments()

addSkipInlineScriptVariableAssignments(array<mixed,string>  $names)

Do not block inline scripts starting with `var $variableName =`.

Parameters

array<mixed,string> $names

addSkipInlineScriptVariableAssignmentsCallback()

addSkipInlineScriptVariableAssignmentsCallback(callable  $callback)

Add a callable after a match got found and skip a script by custom variable name.

Parameters: string[] $variableNames, ScriptInlineMatcher $matcher, ScriptInlineMatch $match. This function needs to return a string[] array!

Parameters

callable $callback

setInlineStyleDummyUrlPath()

setInlineStyleDummyUrlPath(string  $urlPath)

When blocking CSS inline styles, we replace URLs with dummy URLs and we cannot rely on data-uri's as we need to pass parameters, too.

Default: https://assets.devowl.io/packages/devowl-wp/headless-content-blocker/

In the folder there need to exist the following two files: dummy.css, dummy.png.

Parameters

string $urlPath

addVisualParentCallback()

addVisualParentCallback(callable  $callback)

Decide a visual parent for an individual match.

Parameters: boolean|string|number $useVisualParent, AbstractMatcher $matcher, AbstractMatch $match. This function needs to return a boolean|string|number array!

Parameters

callable $callback

addBlockableStringExpressionCallback()

addBlockableStringExpressionCallback(callable  $callback)

Allows to modify the passed string expression to a blockable.

Parameters: string $expression, Blockable $blockable. This function needs to return a string!

Parameters

callable $callback

addReplaceAlwaysAttributes()

addReplaceAlwaysAttributes(array<mixed,string[]>  $tagToAttributesMap)

A set of HTML tags => attribute names which should always prefix with `consent-original-`.

Parameters

array<mixed,string[]> $tagToAttributesMap

addInlineStyleShouldBeExtractedCallback()

addInlineStyleShouldBeExtractedCallback(callable  $callback)

Add a callable after a blocked inline style got found and skip creation of a second document with blocked URLs.

Parameters: boolean $extract, StyleInlineMatcher $matcher, StyleInlineMatch $match. This function needs to return a boolean array!

Parameters

callable $callback

addInlineStyleModifyDocumentsCallback()

addInlineStyleModifyDocumentsCallback(callable  $callback)

Add a callable after a blocked inline style got found, parsed and you can modify the `Document` instance.

Parameters: boolean $extract, StyleInlineMatcher $matcher, StyleInlineMatch $match.

Parameters

callable $callback

addInlineStyleBlockRuleCallback()

addInlineStyleBlockRuleCallback(callable  $callback)

Add a callable after a blocked inline CSS rule got found, and we need to decide to block it or not.

Parameters: BlockedResult $extract, string $url, StyleInlineMatcher $matcher, StyleInlineMatch $match.

Parameters

callable $callback

addVisualParentIfClass()

addVisualParentIfClass(array<mixed,string[]>  $classToVisualParent)

See `Constants::HTML_ATTRIBUTE_VISUAL_PARENT` for more details about this mechanism.

Parameters

array<mixed,string[]> $classToVisualParent

setup()

setup()

Setup the content blocker mechanism. You need to use this before you `modifyAny/modifyHtml` your content!

runCheckResultCallback()

runCheckResultCallback(\DevOwl\HeadlessContentBlocker\BlockedResult  $result,\DevOwl\HeadlessContentBlocker\matcher\AbstractMatcher  $matcher,\DevOwl\FastHtmlTag\finder\match\AbstractMatch  $match): \DevOwl\HeadlessContentBlocker\BlockedResult

Run registered check-result callbacks.

Parameters

\DevOwl\HeadlessContentBlocker\BlockedResult $result
\DevOwl\HeadlessContentBlocker\matcher\AbstractMatcher $matcher
\DevOwl\FastHtmlTag\finder\match\AbstractMatch $match

Returns

\DevOwl\HeadlessContentBlocker\BlockedResult

runSkipInlineScriptVariableAssignmentsCallback()

runSkipInlineScriptVariableAssignmentsCallback(array<mixed,string>  $names,\DevOwl\HeadlessContentBlocker\matcher\ScriptInlineMatcher  $matcher,\DevOwl\FastHtmlTag\finder\match\ScriptInlineMatch  $match): array<mixed,string>

Run registered skip-inline-names callbacks.

Parameters

array<mixed,string> $names
\DevOwl\HeadlessContentBlocker\matcher\ScriptInlineMatcher $matcher
\DevOwl\FastHtmlTag\finder\match\ScriptInlineMatch $match

Returns

array<mixed,string>

runInlineStyleModifyDocumentsCallback()

runInlineStyleModifyDocumentsCallback(\Sabberworm\CSS\CSSList\Document  $document,\Sabberworm\CSS\CSSList\Document  $extractedDocument,\DevOwl\HeadlessContentBlocker\matcher\StyleInlineMatcher  $matcher,\DevOwl\FastHtmlTag\finder\match\StyleInlineMatch  $match)

Run registered callbacks to not extract blocked CSS rules to a second document.

Parameters

\Sabberworm\CSS\CSSList\Document $document
\Sabberworm\CSS\CSSList\Document $extractedDocument
\DevOwl\HeadlessContentBlocker\matcher\StyleInlineMatcher $matcher
\DevOwl\FastHtmlTag\finder\match\StyleInlineMatch $match

runInlineStyleBlockRuleCallback()

runInlineStyleBlockRuleCallback(\DevOwl\HeadlessContentBlocker\BlockedResult  $result,string  $url,\DevOwl\HeadlessContentBlocker\matcher\AbstractMatcher  $matcher,\DevOwl\FastHtmlTag\finder\match\AbstractMatch  $match): \DevOwl\HeadlessContentBlocker\BlockedResult

Run registered check-result callbacks.

Parameters

\DevOwl\HeadlessContentBlocker\BlockedResult $result
string $url
\DevOwl\HeadlessContentBlocker\matcher\AbstractMatcher $matcher
\DevOwl\FastHtmlTag\finder\match\AbstractMatch $match

Returns

\DevOwl\HeadlessContentBlocker\BlockedResult

runBlockableStringExpressionCallback()

runBlockableStringExpressionCallback(string  $expression,\DevOwl\HeadlessContentBlocker\AbstractBlockable  $blockable)

Run registered blockable string expression callbacks.

Parameters

string $expression
\DevOwl\HeadlessContentBlocker\AbstractBlockable $blockable

blockablesToHosts()

blockablesToHosts()

Create an expression => regular expression cache for all available URLs in available blockables.

getBlockableById()

getBlockableById(integer  $id)

Get blockable by blocker ID.

Parameters

integer $id

setAllowMultipleBlockerResults()

setAllowMultipleBlockerResults(boolean  $status)

If you pass `true`, the generated `BlockedResult` will contain multiple results and will not break after the first found blockable to block.

Parameters

boolean $status

isAllowMultipleBlockerResults()

isAllowMultipleBlockerResults()

Getter.

getTagAttributeMap()

getTagAttributeMap()

Getter.

getSelectorSyntaxMap()

getSelectorSyntaxMap()

Getter.

getBlockables()

getBlockables()

Getter.

getKeepAlwaysAttributes()

getKeepAlwaysAttributes()

Getter.

getKeepAlwaysAttributesIfClass()

getKeepAlwaysAttributesIfClass()

Getter.

getSkipInlineScriptVariableAssignments()

getSkipInlineScriptVariableAssignments()

Getter.

getInlineStyleDummyUrlPath()

getInlineStyleDummyUrlPath()

Getter.

getReplaceAlwaysAttributes()

getReplaceAlwaysAttributes()

Getter.

getVisualParentIfClass()

getVisualParentIfClass()

Getter.

getPlugins()

getPlugins()

Getter.

getFinderToMatcher()

getFinderToMatcher()

Getter.

getPluginsByClassName()

getPluginsByClassName(string  $className)

Getter.

Parameters

string $className

runAfterSetupCallback()

runAfterSetupCallback()

Run registered after-setup callbacks.

init()

init()

Add a callback which should throw an `Exception` when the content blocker is not setup.