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.

Methods

__construct() : mixed: C'tor.
afterSetup() : mixed: The content blocker got setup completely.
beforeMatch() : mixed: Called before a match got found.
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.
keepAlwaysAttributes() : array<string|int, string>: Keep attributes for a specific match.
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`.
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.

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

__construct()

C'tor.


    public
        final            __construct(HeadlessContentBlocker $headlessContentBlocker) : mixed

Parameters

$headlessContentBlocker : HeadlessContentBlocker

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

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

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>

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

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

ImagePreview extends AbstractPlugin in package Application

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

Methods

__construct()

Parameters

Tags

afterSetup()

beforeMatch()

Parameters

blockableStringExpression()

Parameters

Return values

blockedMatch()

Parameters

checkResult()

Parameters

Return values

fetchMetadata()

Parameters

getCache()

Tags

getHeadlessContentBlocker()

Tags

getWriteJson()

Parameters

init()

inlineStyleBlockRule()

Parameters

Return values

inlineStyleModifyDocuments()

Parameters

Return values

inlineStyleShouldBeExtracted()

Parameters

Return values

keepAlwaysAttributes()

Parameters

Return values

modifyHtmlAfterProcessing()

Parameters

notBlockedMatch()

Parameters

setCache()

Parameters

Tags

setup()

skipInlineScriptVariableAssignment()

Parameters

Return values

visualParent()

Parameters

Return values

findUrlForSpecialMatch()

Parameters

isValidEmbedUrl()

Parameters

ImagePreview extends AbstractPlugin
in package

Application