1<?php
2
3/**
4 * Chainable filters for custom URI processing.
5 *
6 * These filters can perform custom actions on a URI filter object,
7 * including transformation or blacklisting.  A filter named Foo
8 * must have a corresponding configuration directive %URI.Foo,
9 * unless always_load is specified to be true.
10 *
11 * The following contexts may be available while URIFilters are being
12 * processed:
13 *
14 *      - EmbeddedURI: true if URI is an embedded resource that will
15 *        be loaded automatically on page load
16 *      - CurrentToken: a reference to the token that is currently
17 *        being processed
18 *      - CurrentAttr: the name of the attribute that is currently being
19 *        processed
20 *      - CurrentCSSProperty: the name of the CSS property that is
21 *        currently being processed (if applicable)
22 *
23 * @warning This filter is called before scheme object validation occurs.
24 *          Make sure, if you require a specific scheme object, you
25 *          you check that it exists. This allows filters to convert
26 *          proprietary URI schemes into regular ones.
27 */
28abstract class HTMLPurifier_URIFilter
29{
30
31    /**
32     * Unique identifier of filter.
33     * @type string
34     */
35    public $name;
36
37    /**
38     * True if this filter should be run after scheme validation.
39     * @type bool
40     */
41    public $post = false;
42
43    /**
44     * True if this filter should always be loaded.
45     * This permits a filter to be named Foo without the corresponding
46     * %URI.Foo directive existing.
47     * @type bool
48     */
49    public $always_load = false;
50
51    /**
52     * Performs initialization for the filter.  If the filter returns
53     * false, this means that it shouldn't be considered active.
54     * @param HTMLPurifier_Config $config
55     * @return bool
56     */
57    public function prepare($config)
58    {
59        return true;
60    }
61
62    /**
63     * Filter a URI object
64     * @param HTMLPurifier_URI $uri Reference to URI object variable
65     * @param HTMLPurifier_Config $config
66     * @param HTMLPurifier_Context $context
67     * @return bool Whether or not to continue processing: false indicates
68     *         URL is no good, true indicates continue processing. Note that
69     *         all changes are committed directly on the URI object
70     */
71    abstract public function filter(&$uri, $config, $context);
72}
73
74// vim: et sw=4 sts=4
75