docs/dev-config-bcbreaks.txt

   1
   2 Configuration Backwards-Compatibility Breaks
   3
   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.
  11
  12
  13
  14 1. Outwards Facing Changes
  15 --------------------------------------------------------------------------------
  16
  17 The HTMLPurifier_Config class now takes an alternate syntax. The general rule
  18 is:
  19
  20     If you passed $namespace, $directive, pass "$namespace.$directive"
  21     instead.
  22
  23 An example:
  24
  25     $config->set('HTML', 'Allowed', 'p');
  26
  27 becomes:
  28
  29     $config->set('HTML.Allowed', 'p');
  30
  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.
  35
  36 The old API will still work, but will emit E_USER_NOTICEs.
  37
  38
  39
  40 2. Internal API Changes
  41 --------------------------------------------------------------------------------
  42
  43 Some overarching notes: we've completely eliminated the notion of namespace;
  44 it's now an informal construct for organizing related configuration directives.
  45
  46 Also, the validation routines for keys (formerly "$namespace.$directive")
  47 have been completely relaxed. I don't think it really should be necessary.
  48
  49 2.1 HTMLPurifier_ConfigSchema
  50
  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.
  55
  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().
  59
  60 The $info and $defaults member variables are no longer indexed as
  61 [$namespace][$name]; they are now indexed as ["$namespace.$name"].
  62
  63 All deprecated methods were finally removed, after having yelled at you as
  64 an E_USER_NOTICE for a while now.
  65
  66 2.2 HTMLPurifier_ConfigSchema_Interchange
  67
  68 Member variable $namespaces was removed.
  69
  70 2.3 HTMLPurifier_ConfigSchema_Interchange_Id
  71
  72 Member variable $namespace and $directive removed; member variable $key added.
  73 Any method that took $namespace, $directive now takes $key.
  74
  75 2.4 HTMLPurifier_ConfigSchema_Interchange_Namespace
  76
  77 Removed.
  78
  79     vim: et sw=4 sts=4