dev-config-bcbreaks.txt

Configuration Backwards-Compatibility Breaks

In version 4.0.0, the configuration subsystem (composed of the outwards
facing Config class, as well as the ConfigSchema and ConfigSchema_Interchange
subsystems), was significantly revamped to make use of property lists.
While most of the changes are internal, some internal APIs were changed for the
sake of clarity. HTMLPurifier_Config was kept completely backwards compatible,
although some of the functions were retrofitted with an unambiguous alternate
syntax. Both of these changes are discussed in this document.



1. Outwards Facing Changes
--------------------------------------------------------------------------------

The HTMLPurifier_Config class now takes an alternate syntax. The general rule
is:

    If you passed $namespace, $directive, pass "$namespace.$directive"
    instead.

An example:

    $config->set('HTML', 'Allowed', 'p');

becomes:

    $config->set('HTML.Allowed', 'p');

New configuration options may have more than one namespace, they might
look something like %Filter.YouTube.Blacklist. While you could technically
set it with ('HTML', 'YouTube.Blacklist'), the logical extension
('HTML', 'YouTube', 'Blacklist') does not work.

The old API will still work, but will emit E_USER_NOTICEs.



2. Internal API Changes
--------------------------------------------------------------------------------

Some overarching notes: we've completely eliminated the notion of namespace;
it's now an informal construct for organizing related configuration directives.

Also, the validation routines for keys (formerly "$namespace.$directive")
have been completely relaxed. I don't think it really should be necessary.

2.1 HTMLPurifier_ConfigSchema

First off, if you're interfacing with this class, you really shouldn't.
HTMLPurifier_ConfigSchema_Builder_ConfigSchema is really the only class that
should ever be creating HTMLPurifier_ConfigSchema, and HTMLPurifier_Config the
only class that should be reading it.

All namespace related methods were removed; they are completely unnecessary
now. Any $namespace, $name arguments must be replaced with $key (where
$key == "$namespace.$name"), including for addAlias().

The $info and $defaults member variables are no longer indexed as
[$namespace][$name]; they are now indexed as ["$namespace.$name"].

All deprecated methods were finally removed, after having yelled at you as
an E_USER_NOTICE for a while now.

2.2 HTMLPurifier_ConfigSchema_Interchange

Member variable $namespaces was removed.

2.3 HTMLPurifier_ConfigSchema_Interchange_Id

Member variable $namespace and $directive removed; member variable $key added.
Any method that took $namespace, $directive now takes $key.

2.4 HTMLPurifier_ConfigSchema_Interchange_Namespace

Removed.

    vim: et sw=4 sts=4