From 5bf7ac4e9f1798ab6c7bcc9ce299c5bbbb23396f Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Fri, 29 May 2009 22:10:47 -0400 Subject: [PATCH] Add docs and facilities for having separate directories of schemas. Signed-off-by: Edward Z. Yang --- .gitignore | 1 + NEWS | 3 ++ TODO | 3 +- configdoc/generate.php | 18 +++++----- docs/dev-config-schema.html | 41 ++++++++++++++++++++-- docs/enduser-customize.html | 11 +++--- library/HTMLPurifier/Config.php | 1 + .../ConfigSchema/InterchangeBuilder.php | 13 ++++--- maintenance/common.php | 2 +- maintenance/generate-schema-cache.php | 28 +++++++++++---- 10 files changed, 91 insertions(+), 30 deletions(-) diff --git a/.gitignore b/.gitignore index eb5aba76..cd6988d8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ tags conf/ test-settings.php +config-schema.php library/HTMLPurifier/DefinitionCache/Serializer/*/ library/standalone/ library/HTMLPurifier.standalone.php diff --git a/NEWS b/NEWS index 7e5f9f3e..4c00e02b 100644 --- a/NEWS +++ b/NEWS @@ -37,6 +37,9 @@ NEWS ( CHANGELOG and HISTORY ) HTMLPurifier ! Implement %Attr.AllowedClasses, which allows administrators to restrict classes users can use to a specified finite set of classes, and %Attr.ForbiddenClasses, which is the logical inverse. +! You can now maintain your own configuration schema directories by + creating a config-schema.php file or passing an extra argument. Check + docs/dev-config-schema.html for more details. - Fix bug where URIDefinition would not get cleared if it's directives got changed. - Fix fatal error in HTMLPurifier_Encoder on certain platforms (probably NetBSD 5.0) diff --git a/TODO b/TODO index a4769270..6bc6aa71 100644 --- a/TODO +++ b/TODO @@ -26,7 +26,6 @@ afraid to cast your vote for the next feature to be implemented! - Make it easy for people to cache their entire configuration (so that they have one script they run to change configuration, and then a stub loader to get that configuration) - - Implement FUTURE VERSIONS --------------- @@ -35,6 +34,8 @@ FUTURE VERSIONS # Implement untrusted, dangerous elements/attributes # Implement IDREF support (harder than it seems, since you cannot have IDREFs to non-existent IDs) + - Implement (client and server side image maps are blocking + on IDREF support) # Frameset XHTML 1.0 and HTML 4.01 doctypes - Figure out how to simultaneously set %CSS.Trusted and %HTML.Trusted (?) diff --git a/configdoc/generate.php b/configdoc/generate.php index a8f50c5e..e0c4e674 100644 --- a/configdoc/generate.php +++ b/configdoc/generate.php @@ -18,22 +18,24 @@ TODO: if (version_compare(PHP_VERSION, '5.2', '<')) exit('PHP 5.2+ required.'); error_reporting(E_ALL | E_STRICT); -chdir(dirname(__FILE__)); - // load dual-libraries -require_once '../extras/HTMLPurifierExtras.auto.php'; -require_once '../library/HTMLPurifier.auto.php'; +require_once dirname(__FILE__) . '/../extras/HTMLPurifierExtras.auto.php'; +require_once dirname(__FILE__) . '/../library/HTMLPurifier.auto.php'; // setup HTML Purifier singleton HTMLPurifier::getInstance(array( 'AutoFormat.PurifierLinkify' => true )); -$interchange = HTMLPurifier_ConfigSchema_InterchangeBuilder::buildFromDirectory(); +$builder = new HTMLPurifier_ConfigSchema_InterchangeBuilder(); +$interchange = new HTMLPurifier_ConfigSchema_Interchange(); +$builder->buildDir($interchange); +$loader = dirname(__FILE__) . '/../config-schema.php'; +if (file_exists($loader)) include $loader; $interchange->validate(); $style = 'plain'; // use $_GET in the future, careful to validate! -$configdoc_xml = 'configdoc.xml'; +$configdoc_xml = dirname(__FILE__) . '/configdoc.xml'; $xml_builder = new HTMLPurifier_ConfigSchema_Builder_Xml(); $xml_builder->openURI($configdoc_xml); @@ -50,13 +52,13 @@ if (!$output) { } // write out -file_put_contents("$style.html", $output); +file_put_contents(dirname(__FILE__) . "/$style.html", $output); if (php_sapi_name() != 'cli') { // output (instant feedback if it's a browser) echo $output; } else { - echo 'Files generated successfully.'; + echo "Files generated successfully.\n"; } // vim: et sw=4 sts=4 diff --git a/docs/dev-config-schema.html b/docs/dev-config-schema.html index 8b816b53..07aecd35 100644 --- a/docs/dev-config-schema.html +++ b/docs/dev-config-schema.html @@ -114,7 +114,7 @@ Test.Example VALUE-ALIASES - 'baz' => 'bar' + 'baz' => 'bar' Optional. Mapping of one value to another, and should be a comma separated list of keypair duples. This is only allowed string, istring, text and itext TYPEs. @@ -213,7 +213,7 @@ Test.Example lookup - array('key' => true) + array('key' => true) Lookup array, used with isset($var[$key]) @@ -223,7 +223,7 @@ Test.Example hash - array('key' => 'val') + array('key' => 'val') Associative array of keys to values @@ -267,6 +267,41 @@ Test.Example If you ever make changes to your configuration directives, you will need to run this script again.

+

Adding in-house schema definitions

+ +

+ Placing stuff directly in HTML Purifier's source tree is generally not a + good idea, so HTML Purifier 4.0.0+ has some facilities in place to make your + life easier. +

+ +

+ The first is to pass an extra parameter to maintenance/generate-schema-cache.php + with the location of your directory (relative or absolute path will do). For example, + if I'm storing my custom definitions in /var/htmlpurifier/myschema, run: + php maintenance/generate-schema-cache.php /var/htmlpurifier/myschema. +

+ +

+ Alternatively, you can create a small loader PHP file in the HTML Purifier base + directory named config-schema.php (this is the same directory + you would place a test-settings.php file). In this file, add + the following line for each directory you want to load: +

+ +
$builder->buildDir($interchange, '/var/htmlpurifier/myschema');
+ +

You can even load a single file using:

+ +
$builder->buildFile($interchange, '/var/htmlpurifier/myschema/MyApp.Directive.txt');
+ +

Storing custom definitions that you don't plan on sending back upstream in + a separate directory is definitely a good idea! Additionally, picking + a good namespace can go a long way to saving you grief if you want to use + someone else's change, but they picked the same name, or if HTML Purifier + decides to add support for a configuration directive that has the same name.

+ +

Errors

diff --git a/docs/enduser-customize.html b/docs/enduser-customize.html index 3562b4bb..6af0e9e7 100644 --- a/docs/enduser-customize.html +++ b/docs/enduser-customize.html @@ -18,12 +18,11 @@
HTML Purifier End-User Documentation

- You may have heard of the Advanced API. - If you're interested in reading dry prose and boring functional - specifications, feel free to click that link to get a no-nonsense overview - on the Advanced API. For the rest of us, there's this tutorial. By the time - you're finished reading this, you should have a pretty good idea on - how to implement custom tags and attributes that HTML Purifier may not have. + HTML Purifier has this quirk where if you try to allow certain elements or + attributes, HTML Purifier will tell you that it's not supported, and that + you should go to the forums to find out how to implement it. Well, this + document is how to implement elements and attributes which HTML Purifier + doesn't support out of the box.

Is it necessary?

diff --git a/library/HTMLPurifier/Config.php b/library/HTMLPurifier/Config.php index 5f709e68..6927f990 100644 --- a/library/HTMLPurifier/Config.php +++ b/library/HTMLPurifier/Config.php @@ -216,6 +216,7 @@ class HTMLPurifier_Config /** * Retrieves all directives, organized by namespace + * @warning This is a pretty inefficient function, avoid if you can */ public function getAll() { if (!$this->finalized) $this->autoFinalize(); diff --git a/library/HTMLPurifier/ConfigSchema/InterchangeBuilder.php b/library/HTMLPurifier/ConfigSchema/InterchangeBuilder.php index a8db5c08..785b72ce 100644 --- a/library/HTMLPurifier/ConfigSchema/InterchangeBuilder.php +++ b/library/HTMLPurifier/ConfigSchema/InterchangeBuilder.php @@ -15,10 +15,15 @@ class HTMLPurifier_ConfigSchema_InterchangeBuilder public static function buildFromDirectory($dir = null) { $builder = new HTMLPurifier_ConfigSchema_InterchangeBuilder(); $interchange = new HTMLPurifier_ConfigSchema_Interchange(); + return $builder->buildDir($interchange, $dir); + } - if (!$dir) $dir = HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema/'; - $info = parse_ini_file($dir . 'info.ini'); - $interchange->name = $info['name']; + public function buildDir($interchange, $dir = null) { + if (!$dir) $dir = HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema'; + if (file_exists($dir . '/info.ini')) { + $info = parse_ini_file($dir . '/info.ini'); + $interchange->name = $info['name']; + } $files = array(); $dh = opendir($dir); @@ -32,7 +37,7 @@ class HTMLPurifier_ConfigSchema_InterchangeBuilder sort($files); foreach ($files as $file) { - $builder->buildFile($interchange, $dir . $file); + $this->buildFile($interchange, $dir . '/' . $file); } return $interchange; diff --git a/maintenance/common.php b/maintenance/common.php index 82d3d00f..888c7daf 100644 --- a/maintenance/common.php +++ b/maintenance/common.php @@ -17,6 +17,6 @@ function postfix_is($comp, $subject) { } // Load useful stuff like FSTools -require_once '../extras/HTMLPurifierExtras.auto.php'; +require_once dirname(__FILE__) . '/../extras/HTMLPurifierExtras.auto.php'; // vim: et sw=4 sts=4 diff --git a/maintenance/generate-schema-cache.php b/maintenance/generate-schema-cache.php index e7a59c41..339ff12d 100644 --- a/maintenance/generate-schema-cache.php +++ b/maintenance/generate-schema-cache.php @@ -1,9 +1,8 @@ #!/usr/bin/php buildDir($interchange); + +$loader = dirname(__FILE__) . '/../config-schema.php'; +if (file_exists($loader)) include $loader; +foreach ($_SERVER['argv'] as $i => $dir) { + if ($i === 0) continue; + $builder->buildDir($interchange, realpath($dir)); +} -$interchange = HTMLPurifier_ConfigSchema_InterchangeBuilder::buildFromDirectory(); $interchange->validate(); $schema_builder = new HTMLPurifier_ConfigSchema_Builder_ConfigSchema(); -- 2.11.4.GIT