PEAR::HTML_BBCodeParser 中文文档及示例

一,获取
http://pear.php.net/package/HTML_BBCodeParser 可下载压缩包及获取API文档。
可从这里获取中文文档 http://www.phpart.org/pear/html/bbcode/doc.html

二,方法及实例
方法: HTML_BBCodeParser( [array $options = array()])
返回: 无
描述:
构造器，加载选项和过滤器.
同用&PEAR::getStaticProperty方法定义的基本选项一起,设置private变量_options,如果参数不 为空，则覆盖它们.同时也定义了用来转义在preg_replace()等函数中的标签字符的附加选项.然后, 最终设置的选项又用&PEAR::getStaticProperty() 存回来,以便过滤器类可以使用它们.所有在选项 中的过 滤器都将被加载,它们定义的标签也被拷贝到private变量_definedTags.
权限: public
参数: 数组 $options - 所用的选项,可以忽略.
实例:
可以定义一个BBCodeParser.ini的配置文件,用来存储这些选项,当使用时,用parse_ini_file来分 析出选项数组,以便在构造器中使用.该文件一般放在程序的当前目录下,自然也和PEAR.php在一起.文 件内容如下:

[HTML_BBCodeParser]

; 可能的值为: single|double
; 分析的结果中的属性是使用单引号还是双引号
quotestyle = double

; 可能的值为: all|nothing|strings
; 用引号引住所有的属性值,还是完全不用,还是只引字符串
quotewhat = all

; 标签的开始字符
open = [

; 标签的闭合字符
close = ]

; 可能的值为: true|false
; 对单个html标签应用xml风格的闭合标签(比如<img> 或 <img />)
xmlclose = true

; 可能的值为一个用逗号(,)隔开的过滤器列表
; 欲使用的用逗号隔开的过滤器列表
; 对大小写不敏感,但如果写错,则会出现Failed to load filter xxx 的提示
filters = Basic,Extended,Links,Images,Lists,Email
然后就可以这样应用了:
require_once("PEAR.php");
require_once("HTML/BBCodeParser.php");

$config = parse_ini_file('BBCodeParser.ini', true);
$options = $config['HTML_BBCodeParser'];

$parser = new HTML_BBCodeParser($options);

方法: getParsed( )
返回: 字符串:对象中设置的分析结果文本.
描述: 从对象中获取分析结果文本
参阅: $_parsed
参阅: parse()
权限: public
实例:
<?php
//*** PEAR::HTML_BBCodeParser 类测试
require_once("PEAR.php");
require_once("HTML/BBCodeParser.php");

//设置选项
$config = parse_ini_file('BBCodeParser.ini', true);
$options = $config['HTML_BBCodeParser'];

//创建实例
$parser = new HTML_BBCodeParser($options);

//供测试的字符串
$test = "[b]woaini[/b] [color=red]emma[/color]";

//设定文本
$parser->setText($test);

//执行分析
$parser->parse();

//得到分析结果
$result = $parser->getParsed();

//输出
echo $result;
?>

结果将是: <strong>woaini</strong> <span style="color: red">emma</span>

方法: getPreparsed( )
返回: 字符串:对象中设置的预分析的文本
描述: 获取对象中预分析的文本,即为已经把所有的标签都转换为BBCode标签的结果
参阅: $_preparsed
参阅: _preparse()
权限: public
实例:
<?php
//*** PEAR::HTML_BBCodeParser 类测试
require_once("PEAR.php");
require_once("HTML/BBCodeParser.php");

//设置选项
$config = parse_ini_file('BBCodeParser.ini', true);
$options = $config['HTML_BBCodeParser'];

//创建实例
$parser = new HTML_BBCodeParser($options);

//供测试的字符串
$test = "[b]woaini[/b] http://www.phpart.org [color=red]emma[/color]";

//设定文本
$parser->setText($test);

//执行分析
$parser->parse();

//得到分析结果
$result = $parser->getPreparsed();

//输出
echo $result;
?>
输出的结果将是: [b]woaini[/b] [url=http://www.phpart.org]http://www.phpart.org[/url] [color=red]emma[/color]

方法: getText( )
返回:对象中设置的文本
描述:从对象中获取未分析的文本
参阅: $_text
参阅: setText()
权限: public
实例: 参阅 getParsed

方法: parse( )
返回: 无
描述: 分析对象中设置的文本
参阅: _buildParsedString()
参阅: _validateTagArray()
参阅: _buildTagArray()
参阅: _preparse()
权限: public
实例: 参阅getParsed

方法: qparse( mixed $str)
返回: 结果文本
描述: 一次性完成setText(),pare()以及getParsed()
参阅: $_text
参阅: parse()
权限: public
实例:
//创建实例
$parser = new HTML_BBCodeParser($options);

//供测试的字符串
$test = "[b]woaini[/b] http://www.phpart.org [color=red]emma[/color]";

//设定文本
$result = $parser->qparse($test);

//输出
echo $result;

输出的结果将是:
<strong>woaini</strong> <a href="http://www.phpart.org">http://www.phpart.org</a> <span style="color: red">emma</span>

方法: setText( string $str)
返回: 无
描述: 设置对象中欲要分析的文本
参阅: $_text
参阅: getText()
权限: public
参数: 字符串 $str - 欲在对象中设置的文本
是列: 参阅getParsed

方法: staticQparse( mixed $str)
返回: 结果文本
描述: 一次性完成doText,parse()以及getParsed()的快速静态方法.与qparse的不同是,该方法不会对当前 对象的数据成员产生影响.
参阅: $_text
参阅: parse()
权限: public
实例:
//创建实例
$parser = new HTML_BBCodeParser($options);

//供测试的字符串
$test = "[b]woaini[/b] http://www.phpart.org [color=red]emma[/color]";

//设定文本
$result = $parser->staticQparse($test);

//输出
echo $result;

输出的结果将是:
<strong>woaini</strong> <a href="http://www.phpart.org">http://www.phpart.org</a> <span style="color: red">emma</span>

在qparse和staticQparse的实例中,如果加入
echo $parser->getPreparsed();
echo $parser->getParsed();
就可以轻易看出两者的区别.

三,更简洁的用法

<?php
//*** PEAR::HTML_BBCodeParser 类测试
require_once("PEAR.php");
require_once("HTML/BBCodeParser.php");

$test = "[b]woaini[/b] http://www.phpart.org [color=red]emma[/color]";
echo HTML_BBCodeParser::staticQparse($test);
?>

但只能分析一些基本的标签,比如[b][/b],[i][/i],[u][/u]等.

四,自定义标签
比如我想添加[q][/q]对应<quote></quote>,就可以修改BBCodeParser/Filter/目录下的Basic.php文件,在类成员$_definedTags中加入
'q' => array( 'htmlopen' => 'quote',
'htmlclose' => 'quote',
'allowed' => 'all',
'attributes'=> array())
元素.其中htmlopen定义开始标签,htmlclose定义结束标签,如果没有则置为空.比如<img>的 htmlopen为img,htmlclose为空.allowed定义该标签允许出现的标签,可以为all,none或者两者之一,然后加一个^号,后面跟着例外的标签列表,以逗号相隔.attributes定义允许的属性列表,如img的属性可定义如下
'attributes'=> array('img' => 'src=%2$s%1$s%2$s','w'=> 'width=%2$s%1$d%2$s','h'=>'height=%2$s%1$d%2$s')
然后就可以在img标签里定义w,h属性,而其他属性则会被忽略,其中%2$s可视为引号,%1$s可视为属性的值.

五,一些常用的BBCode
[b]bold[/b]
[i]italic[/i]
[u]underline[/u]
[s]strike[/s]
[sub]subscript[/sub]
[sup]superscript[/sup]

[color=blue]blue text[/color]
[size=18]the size of this text is 18pt[/size]
[font=arial]different font type[/font]
[align=right]yes, you're right, this isn't on the left[/align]
he said: [quote=http://www.server.org/quote.html]i'm tony montana[/quote]
[code]x + y = 6;[/code]

http://www.server.org
[url]http://www.server.org[/url]
[url=http://www.server.org]server[/url]
[url=http://www.server.org target=new]server[/url]

[e-mail]
[email][e-mail][/email]
[email=[e-mail]]mail me[/email]

[img]http://www.server.org/image.jpg[/img]
[img w=100 h=200]http://www.server.org/image.jpg[/img]

[ulist]
[*]unordered item 1
[*]unordered item 2
[/ulist]
[list]
[*]unordered item 1
[*]unordered item 2
[/list]

[list=1]
[*]ordered item 1
[*]ordered item 2
[/list]
[list=i]
[*]ordered item 1 type i
[li=4]ordered item 4 type i[/li]
[/list]
[list=I]
[*]ordered item 1 type I
[/list]
[list=a s=5]
[li]ordered item 5 type a[/li]
[*]ordered item 6 type a
[/list]
[list=A]
[li]ordered item 1 type A[/li]
[li=12]ordered item 12 type A[/li]
[/list]

[list=A s=3]
[li]ordered item 1, nested list:
[list=I]
[li]nested item 1[/li]
[li]nested item 2[/li]
[/list][/li]
[li]ordered item 2[/li]
[/list]

六,总结
该类可以方便地实现BBCode到HTML的替换,且遵循xhtml 1.0,易扩展,亦可以实现标签属性的控制,配置也较方便,很适合初,中级PHP程序员使用.