包 core

包 mvc

包 orm

包 form

包 database

包 helper

包 cache

包 webcontrols

包 behavior

包 exception

包 debug

类 - Q

包	core
类层次	class Q
版本	$Id: q.php 2628 2009-07-17 08:40:15Z jerry $

类 Q 是 QeePHP 框架的核心类，提供了框架运行所需的基本服务

类 Q 提供 QeePHP 框架的基本服务，包括：

公共方法

隐藏继承的方法

方法	描述	定义于
version()	返回 QeePHP 版本号	Q
ini()	获取指定的设置内容	Q
loadDefaultIni()		Q
changeIni()	修改指定设置的内容	Q
replaceIni()	替换已有的设置值	Q
loadClass()	载入指定类的定义文件，如果载入失败抛出异常	Q
import()	添加一个类搜索路径	Q
singleton()	返回指定 class 的唯一实例	Q
set_obj()	用指定名字设置对象	Q
get_obj()	取得指定名字的对象	Q
has_obj()	确定指定的对象是否存在	Q
cache()	读取指定的缓存内容，如果内容不存在或已经失效，则返回 false	Q
writeCache()	将变量内容写入缓存，失败抛出异常	Q
cleanCache()	删除指定的缓存内容	Q
normalize()	对字符串或数组进行格式化，返回格式化后的数组	Q
control()	创建一个用户界面控件对象	Q
autoload()	用于 QeePHP 的类自动载入，不需要由开发者调用	Q
registerAutoload()	注册或取消注册一个自动类载入方法	Q
__()	QeePHP 内部使用的多语言翻译函数	Q

属性详细说明

$_objects 属性

对象注册表

$_class_path 属性

类搜索路径

$_class_path_options 属性

类搜索路径的选项

$_ini 属性

应用程序设置

方法详细说明

version() 方法

public static string version()

返回 QeePHP 版本号

ini() 方法

public static mixed ini($option, $default)

$option	string	要获取设置项的名称
$default	mixed	当设置不存在时要返回的设置默认值
{return}	mixed	返回设置项的值

获取指定的设置内容

$option 参数指定要获取的设置名。如果设置中找不到指定的选项，则返回由 $default 参数指定的值。

$option_value = Q::ini('my_option');

对于层次化的设置信息，可以通过在 $option 中使用“/”符号来指定。

例如有一个名为 option_group 的设置项，其中包含三个子项目。现在要查询其中的 my_option 设置项的内容。

// +--- option_group
//   +-- my_option  = this is my_option
//   +-- my_option2 = this is my_option2
//   \-- my_option3 = this is my_option3
 
// 查询 option_group 设置组里面的 my_option 项
// 将会显示 this is my_option
echo Q::ini('option_group/my_option');

要读取更深层次的设置项，可以使用更多的“/”符号，但太多层次会导致读取速度变慢。

如果要获得所有设置项的内容，将 $option 参数指定为 '/' 即可：

// 获取所有设置项的内容
$all = Q::ini('/');

loadDefaultIni() 方法

public static void loadDefaultIni()

changeIni() 方法

public static void changeIni($option, $data)

$option	string\|array	要修改的设置项名称，或包含多个设置项目的数组
$data	mixed	指定设置项的新值
{return}

修改指定设置的内容

当 $option 参数是字符串时，$option 指定了要修改的设置项。 $data 则是要为该设置项指定的新数据。

// 修改一个设置项
Q::changeIni('option_group/my_option2', 'new value');

如果 $option 是一个数组，则假定要修改多个设置项。那么 $option 则是一个由设置项名称和设置值组成的名值对，或者是一个嵌套数组。

// 假设已有的设置为
// +--- option_1 = old value
// +--- option_group
//   +-- option1 = old value
//   +-- option2 = old value
//   \-- option3 = old value
 
// 修改多个设置项
$arr = array(
     'option_1' => 'value 1',
     'option_2' => 'value 2',
     'option_group/option2' => 'new value',
);
Q::changeIni($arr);
 
// 修改后
// +--- option_1 = value 1
// +--- option_2 = value 2
// +--- option_group
//   +-- option1 = old value
//   +-- option2 = new value
//   \-- option3 = old value

上述代码展示了 Q::changeIni() 的一个重要特性：保持已有设置的层次结构。

因此如果要完全替换某个设置项和其子项目，应该使用 Q::replaceIni() 方法。

replaceIni() 方法

public static void replaceIni($option, $data)

$option	string\|array	要修改的设置项名称，或包含多个设置项目的数组
$data	mixed	指定设置项的新值
{return}

替换已有的设置值

Q::replaceIni() 表面上看和 Q::changeIni() 类似。但是 Q::replaceIni() 不会保持已有设置的层次结构，而是直接替换到指定的设置项及其子项目。

// 假设已有的设置为
// +--- option_1 = old value
// +--- option_group
//   +-- option1 = old value
//   +-- option2 = old value
//   \-- option3 = old value
 
// 替换多个设置项
$arr = array(
     'option_1' => 'value 1',
     'option_2' => 'value 2',
     'option_group/option2' => 'new value',
);
Q::replaceIni($arr);
 
// 修改后
// +--- option_1 = value 1
// +--- option_2 = value 2
// +--- option_group
//   +-- option2 = new value

从上述代码的执行结果可以看出 Q::replaceIni() 和 Q::changeIni() 的重要区别。

不过由于 Q::replaceIni() 速度比 Q::changeIni() 快很多，因此应该尽量使用 Q::replaceIni() 来代替 Q::changeIni()。

loadClass() 方法

public static string|boolean loadClass($class_name)

$class_name	string	要载入的类
{return}	string\|boolean	成功返回类名，失败返回 false

载入指定类的定义文件，如果载入失败抛出异常

Q::loadClass('Table_Posts');

import() 方法

public static void import($dir, $case_sensitive)

$dir	string	要添加的搜索路径
$case_sensitive	boolean	在该路径中查找类文件时是否区分文件名大小写
{return}

添加一个类搜索路径

如果要使用 Q::loadClass() 载入非 QeePHP 的类，需要通过 Q::import() 添加类类搜索路径。

要注意，Q::import() 添加的路径和类名称有关系。

例如类的名称为 Vendor_Smarty_Adapter，那么该类的定义文件存储结构就是 vendor/smarty/adapter.php。因此在用 Q::import() 添加 Vendor_Smarty_Adapter 类的搜索路径时，只能添加 vendor/smarty/adapter.php 的父目录。

Q::import('/www/app');
Q::loadClass('Vendor_Smarty_Adapter');
// 实际载入的文件是 /www/app/vendor/smarty/adapter.php

由于 QeePHP 的规范是文件名全小写，因此要载入文件名存在大小写区分的第三方库时，应该指定 import() 方法的第二个参数。

Q::import('/www/app/vendor', true);
Q::loadClass('Zend_Mail');
// 实际载入的文件是 /www/app/vendor/Zend/Mail.php

singleton() 方法

public static object singleton($class_name)

$class_name	string
{return}	object

返回指定 class 的唯一实例

set_obj() 方法

public static object set_obj($obj, $name)

$obj	object
$name	string
{return}	object

用指定名字设置对象

get_obj() 方法

public static object get_obj($name)

$name	string
{return}	object

取得指定名字的对象

has_obj() 方法

public static bool has_obj($name)

$name	string
{return}	bool

确定指定的对象是否存在

cache() 方法

public static mixed cache($id, $policy, $backend_class)

$id	string	缓存的 ID
$policy	array	缓存策略
$backend_class	string	要使用的缓存服务
{return}	mixed	成功返回缓存内容，失败返回 false

读取指定的缓存内容，如果内容不存在或已经失效，则返回 false

在操作缓存数据时，必须指定缓存的 ID。每一个缓存内容都有一个唯一的 ID。例如数据 A 的缓存 ID 是 data-a，而数据 B 的缓存 ID 是 data-b。

在大量使用缓存时，应该采用一定的规则来确定缓存 ID。下面是一个推荐的方案：

首先按照缓存数据的性质确定前缀，例如 page、db 等；
然后按照数据的唯一索引来确定后缀，并和前缀一起组合成完整的缓存 ID。

按照这个规则，缓存 ID 看上去类似 page.news.1、db.members.userid。

Q::cache() 可以指定 $policy 参数来覆盖缓存数据本身带有的策略。具体哪些策略可以使用，请参考不同缓存服务的文档。

$backend_class 用于指定要使用的缓存服务对象类名称。例如 QCache_File、QCache_APC 等。

$data = Q::cache($cache_id);
if ($data === false)
{
    $data = ....
    Q::writeCache($cache_id, $data);
}

writeCache() 方法

public static void writeCache($id, $data, $policy, $backend_class)

$id	string	缓存的 ID
$data	mixed	要缓存的数据
$policy	array	缓存策略
$backend_class	string	要使用的缓存服务
{return}

将变量内容写入缓存，失败抛出异常

$data 参数指定要缓存的内容。如果 $data 参数不是一个字符串，则必须将缓存策略 serialize 设置为 true。 $policy 参数指定了内容的缓存策略，如果没有提供该参数，则使用缓存服务的默认策略。

其他参数同 Q::cache()。

cleanCache() 方法

public static void cleanCache($id, $policy, $backend_class)

$id	string	缓存的 ID
$policy	array	缓存策略
$backend_class	string	要使用的缓存服务
{return}

删除指定的缓存内容

通常，失效的缓存数据无需清理。但有时候，希望在某些操作完成后立即清除缓存。例如更新数据库记录后，希望删除该记录的缓存文件，以便在下一次读取缓存时重新生成缓存文件。

Q::cleanCache($cache_id);

normalize() 方法

public static array normalize($input, $delimiter)

$input	array\|string	要格式化的字符串或数组
$delimiter	string	按照什么字符进行分割
{return}	array	格式化结果

对字符串或数组进行格式化，返回格式化后的数组

$input 参数如果是字符串，则首先以“,”为分隔符，将字符串转换为一个数组。接下来对数组中每一个项目使用 trim() 方法去掉首尾的空白字符。最后过滤掉空字符串项目。

该方法的主要用途是将诸如：“item1, item2, item3” 这样的字符串转换为数组。

$input = 'item1, item2, item3';
$output = Q::normalize($input);
// $output 现在是一个数组，结果如下：
// $output = array(
//   'item1',
//   'item2',
//   'item3',
// );
 
$input = 'item1|item2|item3';
// 指定使用什么字符作为分割符
$output = Q::normalize($input, '|');

control() 方法

public static QUI_Control_Abstract control($type, $id, $attrs)

$type	string	用户界面控件对象的类型
$id	string	控件ID
$attrs	array	要传递给控件的附加属性
{return}	QUI_Control_Abstract	创建的用户界面控件对象

创建一个用户界面控件对象

使用 Q::control() 方法，可以很容易的创建指定类型的用户界面控件对象。

autoload() 方法

public static void autoload($class_name)

$class_name	string
{return}

用于 QeePHP 的类自动载入，不需要由开发者调用

registerAutoload() 方法

public static void registerAutoload($class, $enabled)

$class	string	提供自动载入服务的类
$enabled	boolean	启用或禁用该服务
{return}

注册或取消注册一个自动类载入方法

该方法参考 Zend Framework。

__() 方法

public static $msg __()

QeePHP 内部使用的多语言翻译函数