Fix two bugs with caching of customized raw definitions.
[htmlpurifier.git] / docs / dev-config-bcbreaks.txt
2 Configuration Backwards-Compatibility Breaks
4 In version 4.0.0, the configuration subsystem (composed of the outwards
5 facing Config class, as well as the ConfigSchema and ConfigSchema_Interchange
6 subsystems), was significantly revamped to make use of property lists.
7 While most of the changes are internal, some internal APIs were changed for the
8 sake of clarity. HTMLPurifier_Config was kept completely backwards compatible,
9 although some of the functions were retrofitted with an unambiguous alternate
10 syntax. Both of these changes are discussed in this document.
14 1. Outwards Facing Changes
15 --------------------------------------------------------------------------------
17 The HTMLPurifier_Config class now takes an alternate syntax. The general rule
18 is:
20     If you passed $namespace, $directive, pass "$namespace.$directive"
21     instead.
23 An example:
25     $config->set('HTML', 'Allowed', 'p');
27 becomes:
29     $config->set('HTML.Allowed', 'p');
31 New configuration options may have more than one namespace, they might
32 look something like %Filter.YouTube.Blacklist. While you could technically
33 set it with ('HTML', 'YouTube.Blacklist'), the logical extension
34 ('HTML', 'YouTube', 'Blacklist') does not work.
36 The old API will still work, but will emit E_USER_NOTICEs.
40 2. Internal API Changes
41 --------------------------------------------------------------------------------
43 Some overarching notes: we've completely eliminated the notion of namespace;
44 it's now an informal construct for organizing related configuration directives.
46 Also, the validation routines for keys (formerly "$namespace.$directive")
47 have been completely relaxed. I don't think it really should be necessary.
49 2.1 HTMLPurifier_ConfigSchema
51 First off, if you're interfacing with this class, you really shouldn't.
52 HTMLPurifier_ConfigSchema_Builder_ConfigSchema is really the only class that
53 should ever be creating HTMLPurifier_ConfigSchema, and HTMLPurifier_Config the
54 only class that should be reading it.
56 All namespace related methods were removed; they are completely unnecessary
57 now. Any $namespace, $name arguments must be replaced with $key (where
58 $key == "$namespace.$name"), including for addAlias().
60 The $info and $defaults member variables are no longer indexed as
61 [$namespace][$name]; they are now indexed as ["$namespace.$name"].
63 All deprecated methods were finally removed, after having yelled at you as
64 an E_USER_NOTICE for a while now.
66 2.2 HTMLPurifier_ConfigSchema_Interchange
68 Member variable $namespaces was removed.
70 2.3 HTMLPurifier_ConfigSchema_Interchange_Id
72 Member variable $namespace and $directive removed; member variable $key added.
73 Any method that took $namespace, $directive now takes $key.
75 2.4 HTMLPurifier_ConfigSchema_Interchange_Namespace
77 Removed.
79     vim: et sw=4 sts=4