Gallery:编码指引

来自站长百科
（重定向自Gallery:Coding Guidelines）
跳转至： 导航、​ 搜索

此知道描述为Gallery2框架进行编码的方法，以保证它能够在所有的平台上尽可能地稳定运行，并且能够符合Gallery2的要求。

该文档不会涉及Gallery2的编码标准，即编码风格会另辟话题。

数据库[ ]

  • 请勿使用依赖DBMS的SQL片断。某些依赖DBMS的SQL 在$storage->getFunctionSql()中是抽象化的，如BIT_OR, BIT_AND等。
  • 请勿直接呼叫数据库相关的方法（如mysql_connect），而是使用Gallery2的方法。
global $gallery;
list ($ret, $results) = $gallery->search('SELECT * FROM [GalleryPhotoItem]');
  • 请勿直接修改Map表格。而是使用GalleryCoreApi::addMapEntry($mapName, ..), ::removeMapEntry, ..。
注： 在G2.0中，此为MapNameMap::addMapEntry()等
  • 除非必要，不要创建自己的数据库查询，而应使用Gallery2的API方法。
  • 不要使用DDL（SQL 语言的CREATE TABLE, ALTER TABLE, ...子集）。而是使用Entity类别以及包含有XML描述的Maps.xml来新建或修改现有的表格。接下来，一旦你在classes/目录中运行make，Gallery2就会为所有支持的DBMS生成SQL代码。
  • Locking： 当你需要更新永续性数据（存储于数据库中的数据）时，使用读/写lock。记得在完成更新后，释放这些lock。
提示： lockIds与itemIds不同。

大型数据集[ ]

  • 当处理大型数据集时，可以考虑使用进度条和$storage->checkPoint来最大限度地限制可能出现的致命超时/错误的作用。
  • 不要使用WHERE / UPDATE字句进行查询，而按较小的批次进行会比较好。 举一个WHERE / UPDATE字句较差情况的例子，假设$allItemIds为一个含有1000+id的列表：
$gallery->search("SELECT * FROM [GalleryItem] WHERE [GalleryItem::id] IN ($markers)", $allItemIds);
注： GalleryCoreApi::loadEntitiesById()和GalleryCoreApi::acquire*Lock()均尚未修复。这就意味着你需要按较小的批次来呼叫这些方法了。就算它们被修整为可以进行批量操作，你还是要面对服务器（不是php）的超时问题。我们无法在API深层使用进度条，因为我们不确定当前视图是否支持进度条。

PHP[ ]

  • 请勿在代码中呼叫die / exit / header('Location: ...')，而应在你的视图/控制器中返回一个合适的状态/重新导向url。这样Gallery2就有机会执行/回滚开启事务（open transactions），进行清除（cleanup），并未bug打上修复补丁（如header('Location:')在某些平台上有bug，而我们在请求结尾将其修复了）。
  • 对于列在modules/core/classes/GalleryPhpVm.class中的PHP函数，使用
global $gallery;
$phpVm =& $gallery->getPhpVm();
$phpVm->functionName();
  • 兼容性： G2代码必须使用PHP4和5才能运行，即PHP 4.1.0+ (对G2.2则是4.3.0+)和 PHP 5.0.4+。请勿使用任何"PHP 5"-only的OO代码，也不要使用于PHP4.1.0中不可用的方法，除非你能够提供某种回退方案。
if (function_exists('foo_bar')) {
	foo_bar($data);
} else {
	myFooBar($data);
}

文件系统/平台[ ]

  • 请勿直接呼叫任何文件系统/平台函数（如fopen，fsockopen，exec，chmod, ...)，而是使用Gallery2方法。
global $gallery;
$platform =& $gallery->getPlatform();
$platform->fopen($path);

字串/文本和翻译[ ]

  • 对于所有显示给最终用户的字串/文本，使用
$plugin->translate('Some text')

如果文本进入数据库，并且在自数据库进行取回时translate()被呼叫的话，使用 

$gallery->i18n('Some text')

在smarty模板中： 

{g->text text="Some text"}
注： 例外情况就是GalleryStatus对象中的可选消息，以及不使用translate()的单位测试失败的消息。
  • 如果你在字串中使用HTML，请使用翻译方法进行编写。
/* 不好的写法 */
$plugin->translate('Do <b>NOT</b> do this!');

/* 好的写法 */
$plugin->translate(array('text' => 'Do %sNOT%s do this!', 'arg1' => '<b>', 'arg2' => '</b>'));
  • 当字串包括变量时还是使用translate参数。
/*不好的写法*/
$plugin->translate("Next, please read chapter '$chapter'");

/*好的写法*/
$plugin->translate(array('text' => "Next, please read '%s'", 'arg1' => $chapter));

在smarty模板中： 

{g->text text="Next, please read '%s'" arg1=$chapter}

杂项[ ]

  • URL生成： 使用Gallery提供的方法生成所有的URL。
    In PHP:
global $gallery;
$urlGenerator =& $gallery->getUrlGenerator();
$url = $urlGenerator->generateUrl($params, $options);

在smarty模板中： 

{g->url arg1= ....}
  • 代码的修改： 请勿修改现有模块的代码，而应使用额外模块扩展Gallery2的特点集。原因：用户应能使用简单的web界面管理Gallery2。新特点的添加应当是轻点加下鼠标那么简单。我们不希望看到类似"打开文件X，找到第Y行，将A替换为B ..."这样的修改类型的安装指导。如果你需要在现有模块中进行修改，请联系模块编写者，询问一下做出改动是否会导致现有模块的不兼容，最好是以某种模块化的方式，（Factory Registrations），如某模块会检查G2 factory看看是否有针对该模块的插件，而你的新模块可以为另外的模块启用一个插件，从而以模块化的方式对功能进行扩展。
取自“https://www.zzbaike.com/wiki/Gallery:编码指引?oldid=14973”