Documentation

ImagePreview extends AbstractPlugin
in package

Application

Detects, if there could be created an image preview for a given URL, downloads it and appends it as a custom attribute to the blocked HTML tag so the visual content blocker could create something cool.

You need to pass a setCache to the plugin instance, otherwise the mechanism does not track any URLs. The purpose of the headless content blocker is to block external URLs, and we do not want to use an external URL as image preview!
Your AbstractBlockable needs to implement ImagePreviewBlockable interface to determine if thumbnails should be loaded for the blocked content!

Constants

HTML_ATTRIBUTE_TO_FETCH_URL_FROM = 'hcb-fetch-image-from'
HTML_ATTRIBUTE_TO_FETCH_URL_FROM_ALTERNATIVE = 'hcb-fetch-image-from-alt'
SKIP_EMBED_URL_EXTENSIONS = ['js', 'css', 'zip', 'pdf']

Properties

$attributesToCheckForUrl : array<string|int, string>: A list of possible link attributes.
$cache : ImagePreviewCache: ImagePreviewCache.
$headlessContentBlocker : mixed
$htmlHeadThumbnailParser : HtmlHeadThumbnailParser: HtmlHeadThumbnailParser.
$revertAttributesToCachedUrl : array<string|int, string>: See `addRevertAttribute`.

Methods

__construct() : mixed: C'tor.
addRevertAttribute() : mixed: A list of selector syntax strings which should be reverted to the cached URL for all transformed attributes.
afterSetup() : mixed: The content blocker got setup completely.
beforeMatch() : mixed: Called before a match got found.
beforeSetBlockedInResult() : bool: Allows to add an additional check before a blockable and expression gets added to a `BlockedResult`.
blockableStringExpression() : string: Allows to modify the passed string expression to a blockable.
blockedMatch() : mixed: See `AbstractPlugin`.
checkResult() : BlockedResult: Special case: Read attribute of the original embed URL if it got passed via a custom attribute.
fetchMetadata() : mixed: Use multiple mechanism to extract a thumbnail from any URL. It returns an map of URL => thumbnail, and if a thumbnail got not found it is no longer part of the returned map.
getCache() : mixed: Getter.
getHeadlessContentBlocker() : mixed: Getter.
getWriteJson() : mixed: Create the result for the HTML attribute which our unblocker can consume.
init() : mixed: Init.
inlineStyleBlockRule() : bool: Decide if a URL in a CSS rule should be blocked.
inlineStyleModifyDocuments() : bool: Allows to modify blocked CSS documents.
inlineStyleShouldBeExtracted() : bool: Do not extract blocked rules of a CSS inline script to a second document.
iterateBlockablesInString() : mixed: This method is run while iterating blockables and check if rules are found within a string.
keepAlwaysAttributes() : array<string|int, string>: Keep attributes for a specific match.
modifyBlockables() : array<string|int, AbstractBlockable>: Modify the blockables array before it gets registered.
modifyHtmlAfterProcessing() : mixed: Allows to modify the HTML after the content blocker has done its job.
notBlockedMatch() : mixed: Called after a match got not blocked. Opposite of `blockedMatch`.
revertTransformAttributeOnMatch() : mixed: When a match with `consent-thumbnail is found, revert the transformation of the attribute.
setCache() : mixed: Setter.
setup() : mixed: Before the content blocker gets setup.
skipInlineScriptVariableAssignment() : array<string|int, string>: Skip inline script by variable name.
visualParent() : bool|string|number: Set a visual parent for a specific match.
findUrlForSpecialMatch() : mixed: Find an embed URL for a special match.
isValidEmbedUrl() : mixed: Check if a given embed URL is valid.
revertTransformAttribute() : mixed: Revert the transformation of a URL attribute when we have found a thumbnail and it is cached.

HTML_ATTRIBUTE_TO_FETCH_URL_FROM


    public
        mixed
    HTML_ATTRIBUTE_TO_FETCH_URL_FROM
    = 'hcb-fetch-image-from'

HTML_ATTRIBUTE_TO_FETCH_URL_FROM_ALTERNATIVE


    public
        mixed
    HTML_ATTRIBUTE_TO_FETCH_URL_FROM_ALTERNATIVE
    = 'hcb-fetch-image-from-alt'

SKIP_EMBED_URL_EXTENSIONS


    public
        mixed
    SKIP_EMBED_URL_EXTENSIONS
    = ['js', 'css', 'zip', 'pdf']

$attributesToCheckForUrl

A list of possible link attributes.


    private
        array<string|int, string>
    $attributesToCheckForUrl
     = []

$cache

ImagePreviewCache.


    private
        ImagePreviewCache
    $cache

$headlessContentBlocker


    private
        mixed
    $headlessContentBlocker

$htmlHeadThumbnailParser

HtmlHeadThumbnailParser.


    private
        HtmlHeadThumbnailParser
    $htmlHeadThumbnailParser

$revertAttributesToCachedUrl

See `addRevertAttribute`.


    private
        array<string|int, string>
    $revertAttributesToCachedUrl
     = []

__construct()

C'tor.


    public
        final            __construct(HeadlessContentBlocker $headlessContentBlocker) : mixed

Parameters

$headlessContentBlocker : HeadlessContentBlocker

addRevertAttribute()

A list of selector syntax strings which should be reverted to the cached URL for all transformed attributes.


    public
                    addRevertAttribute(string $selectorSyntax) : mixed

E.g. div[class*="et_pb_video_slider_item_"] will revert e.g. consent-original-data-image back to data-image with the cached URL.

Parameters

$selectorSyntax : string

afterSetup()

The content blocker got setup completely.


    public
                    afterSetup() : mixed

beforeMatch()

Called before a match got found.


    public
                    beforeMatch(AbstractMatcher $matcher, AbstractMatch $match) : mixed

Parameters

$matcher : AbstractMatcher
$match : AbstractMatch

beforeSetBlockedInResult()

Allows to add an additional check before a blockable and expression gets added to a `BlockedResult`.


    public
                    beforeSetBlockedInResult(BlockedResult $result, AbstractBlockable $blockable, string $expression, AbstractMatcher $matcher) : bool

Parameters

$result : BlockedResult
$blockable : AbstractBlockable
$expression : string
$matcher : AbstractMatcher

Return values

bool

blockableStringExpression()

Allows to modify the passed string expression to a blockable.


    public
                    blockableStringExpression(string $expression, AbstractBlockable $blockable) : string

Parameters

$expression : string
$blockable : AbstractBlockable

Return values

string

blockedMatch()

See `AbstractPlugin`.


    public
                    blockedMatch(BlockedResult $result, AbstractMatcher $matcher, AbstractMatch $match) : mixed

Parameters

$result : BlockedResult
$matcher : AbstractMatcher
$match : AbstractMatch

checkResult()

Special case: Read attribute of the original embed URL if it got passed via a custom attribute.


    public
                    checkResult(BlockedResult $result, AbstractMatcher $matcher, AbstractMatch $match) : BlockedResult

Parameters

$result : BlockedResult
$matcher : AbstractMatcher
$match : AbstractMatch

Return values

BlockedResult

fetchMetadata()

Use multiple mechanism to extract a thumbnail from any URL. It returns an map of URL => thumbnail, and if a thumbnail got not found it is no longer part of the returned map.


    public
                    fetchMetadata(array<string|int, Thumbnail> &$thumbnails) : mixed

Mechanism:

Cache
Oembed
HTML Head Parser and extract thumbnail URL from known meta tags

Parameters

$thumbnails : array<string|int, Thumbnail>: Key needs to be the embed URL

getCache()

Getter.


    public
                    getCache() : mixed

getHeadlessContentBlocker()

Getter.


    public
        final            getHeadlessContentBlocker() : mixed

getWriteJson()

Create the result for the HTML attribute which our unblocker can consume.


    public
                    getWriteJson(Thumbnail $thumbnail) : mixed

Parameters

$thumbnail : Thumbnail

init()

Init.


    public
                    init() : mixed

inlineStyleBlockRule()

Decide if a URL in a CSS rule should be blocked.


    public
                    inlineStyleBlockRule(BlockedResult $result, string $url, StyleInlineMatcher|StyleInlineAttributeMatcher $matcher, StyleInlineMatch|StyleInlineAttributeMatch $match) : bool

Parameters

$result : BlockedResult
$url : string
$matcher : StyleInlineMatcher|StyleInlineAttributeMatcher
$match : StyleInlineMatch|StyleInlineAttributeMatch

Return values

bool

inlineStyleModifyDocuments()

Allows to modify blocked CSS documents.


    public
                    inlineStyleModifyDocuments(Document $document, Document $extractedDocument, StyleInlineMatcher|StyleInlineAttributeMatcher $matcher, StyleInlineMatch|StyleInlineAttributeMatch $match) : bool

Parameters

$document : Document
$extractedDocument : Document
$matcher : StyleInlineMatcher|StyleInlineAttributeMatcher
$match : StyleInlineMatch|StyleInlineAttributeMatch

Return values

bool

inlineStyleShouldBeExtracted()

Do not extract blocked rules of a CSS inline script to a second document.


    public
                    inlineStyleShouldBeExtracted(bool $extract, StyleInlineMatcher|StyleInlineAttributeMatcher $matcher, StyleInlineMatch|StyleInlineAttributeMatch $match) : bool

Parameters

$extract : bool
$matcher : StyleInlineMatcher|StyleInlineAttributeMatcher
$match : StyleInlineMatch|StyleInlineAttributeMatch

Return values

bool

iterateBlockablesInString()

This method is run while iterating blockables and check if rules are found within a string.


    public
                    iterateBlockablesInString(AbstractMatcher $matcher, BlockedResult $result, string $string, bool $useContainsRegularExpression, bool $multilineRegexp, array<string|int, string> $useRegularExpressionFromMap, array<string|int, AbstractBlockable> $useBlockables, bool $allowMultiple) : mixed

It allows you to add additional blockables to the result even if isAllowMultipleBlockerResults is false.

Note: All required IDs from each matching Blockable will be merged together, but only the ID of the first Blockable found will be assigned as the consent-id of the element.

Parameters

$matcher : AbstractMatcher
$result : BlockedResult
$string : string
$useContainsRegularExpression : bool
$multilineRegexp : bool
$useRegularExpressionFromMap : array<string|int, string>
$useBlockables : array<string|int, AbstractBlockable>
$allowMultiple : bool

keepAlwaysAttributes()

Keep attributes for a specific match.


    public
                    keepAlwaysAttributes(array<string|int, string> $keepAttributes, AbstractMatcher $matcher, AbstractMatch $match) : array<string|int, string>

Parameters

$keepAttributes : array<string|int, string>
$matcher : AbstractMatcher
$match : AbstractMatch

Return values

array<string|int, string>

modifyBlockables()

Modify the blockables array before it gets registered.


    public
                    modifyBlockables(array<string|int, AbstractBlockable> $blockables) : array<string|int, AbstractBlockable>

Parameters

$blockables : array<string|int, AbstractBlockable>

Return values

array<string|int, AbstractBlockable>

modifyHtmlAfterProcessing()

Allows to modify the HTML after the content blocker has done its job.


    public
                    modifyHtmlAfterProcessing(string $html) : mixed

Parameters

$html : string

notBlockedMatch()

Called after a match got not blocked. Opposite of `blockedMatch`.


    public
                    notBlockedMatch(BlockedResult $result, AbstractMatcher $matcher, AbstractMatch $match) : mixed

Parameters

$result : BlockedResult
$matcher : AbstractMatcher
$match : AbstractMatch

revertTransformAttributeOnMatch()

When a match with `consent-thumbnail is found, revert the transformation of the attribute.


    public
                    revertTransformAttributeOnMatch(AbstractMatch $match) : mixed

Parameters

$match : AbstractMatch

setCache()

Setter.


    public
                    setCache(ImagePreviewCache $cache) : mixed

Parameters

$cache : ImagePreviewCache

setup()

Before the content blocker gets setup.


    public
                    setup() : mixed

skipInlineScriptVariableAssignment()

Skip inline script by variable name.


    public
                    skipInlineScriptVariableAssignment(array<string|int, string> $names, ScriptInlineMatcher $matcher, ScriptInlineMatch $match) : array<string|int, string>

Parameters

$names : array<string|int, string>
$matcher : ScriptInlineMatcher
$match : ScriptInlineMatch

Return values

array<string|int, string>

visualParent()

Set a visual parent for a specific match.


    public
                    visualParent(bool|string|number $visualParent, AbstractMatcher $matcher, AbstractMatch $match) : bool|string|number

Parameters

$visualParent : bool|string|number
$matcher : AbstractMatcher
$match : AbstractMatch

Return values

bool|string|number

findUrlForSpecialMatch()

Find an embed URL for a special match.


    protected
                    findUrlForSpecialMatch(AbstractMatch $match) : mixed

Parameters

$match : AbstractMatch

isValidEmbedUrl()

Check if a given embed URL is valid.


    protected
                    isValidEmbedUrl(string $embedUrl[, bool $respectSpecialCases = true ]) : mixed

Parameters

$embedUrl : string
$respectSpecialCases : bool = true

revertTransformAttribute()

Revert the transformation of a URL attribute when we have found a thumbnail and it is cached.


    protected
                    revertTransformAttribute(string $html) : mixed

Parameters

$html : string

ImagePreview extends AbstractPlugin in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

HTML_ATTRIBUTE_TO_FETCH_URL_FROM

HTML_ATTRIBUTE_TO_FETCH_URL_FROM_ALTERNATIVE

SKIP_EMBED_URL_EXTENSIONS

Properties

$attributesToCheckForUrl

$cache

$headlessContentBlocker

$htmlHeadThumbnailParser

$revertAttributesToCachedUrl

Methods

__construct()

Parameters

addRevertAttribute()

Parameters

afterSetup()

beforeMatch()

Parameters

Tags

beforeSetBlockedInResult()

Parameters

Tags

Return values

blockableStringExpression()

Parameters

Tags

Return values

blockedMatch()

Parameters

checkResult()

Parameters

Return values

fetchMetadata()

Parameters

getCache()

getHeadlessContentBlocker()

getWriteJson()

Parameters

init()

inlineStyleBlockRule()

Parameters

Tags

Return values

inlineStyleModifyDocuments()

Parameters

Tags

Return values

inlineStyleShouldBeExtracted()

Parameters

Tags

Return values

iterateBlockablesInString()

Parameters

Tags

keepAlwaysAttributes()

Parameters

Tags

Return values

modifyBlockables()

Parameters

Tags

Return values

modifyHtmlAfterProcessing()

Parameters

Tags

notBlockedMatch()

Parameters

Tags

revertTransformAttributeOnMatch()

Parameters

setCache()

Parameters

setup()

Tags

ImagePreview extends AbstractPlugin
in package

Application