编辑“Gallery:编码指引”

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

该文档不会涉及[[Gallery:Coding_Standards|Gallery2的编码标准]]，即编码风格会另辟话题。

__TOC__

== 数据库 ==

* 请勿使用依赖DBMS的SQL片断。某些依赖DBMS的SQL 在<tt>$storage->getFunctionSql()</tt>中是抽象化的，如<tt>BIT_OR, BIT_AND</tt>等。

* 请勿直接呼叫数据库相关的方法（如<tt>mysql_connect</tt>），而是使用Gallery2的方法。
<pre><nowiki>
global $gallery;
list ($ret, $results) = $gallery->search('SELECT * FROM [GalleryPhotoItem]');
</nowiki></pre>

* 请勿直接修改Map表格。而是使用<tt>GalleryCoreApi::addMapEntry($mapName, ..), ::removeMapEntry, ..</tt>。
:: '''注：''' 在G2.0中，此为<tt>MapNameMap::addMapEntry()</tt>等

* 除非必要，不要创建自己的数据库查询，而应使用Gallery2的API方法。

* 不要使用{{H:title|Data Definition Language|DDL}}（SQL 语言的<tt>CREATE TABLE, ALTER TABLE, ...</tt>子集）。而是使用Entity类别以及包含有XML描述的Maps.xml来新建或修改现有的表格。接下来，一旦你在<tt>classes/</tt>目录中运行<tt>make</tt>，Gallery2就会为所有支持的DBMS生成SQL代码。

* '''Locking：''' 当你需要更新永续性数据（存储于数据库中的数据）时，使用读/写lock。记得在完成更新后，释放这些lock。
:: '''提示：''' lockIds与itemIds不同。 

=== 大型数据集 ===

* 当处理大型数据集时，可以考虑使用进度条和<tt>$storage->checkPoint</tt>来最大限度地限制可能出现的致命超时/错误的作用。

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

== PHP ==

* 请勿在代码中呼叫<tt>die / exit / header('Location: ...')</tt>，而应在你的视图/控制器中返回一个合适的状态/重新导向url。这样Gallery2就有机会执行/回滚开启事务（open transactions），进行清除（cleanup），并未bug打上修复补丁（如<tt>header('Location:')</tt>在某些平台上有bug，而我们在请求结尾将其修复了）。

* 对于列在<tt>modules/core/classes/GalleryPhpVm.class</tt>中的PHP函数，使用
<pre><nowiki>
global $gallery;
$phpVm =& $gallery->getPhpVm();
$phpVm->functionName();
</nowiki></pre>

* '''引用：''' 参见[http://gallery.menalto.com/node/33076 如何处理PHP 4.4.0中的引用]。作为常识，除非这么做有意义，否则的话不要使用PHP引用。而且使用引用时的性能欠佳。参见：[http://www.blueshoes.org/phpBench.php PHP Benchmark的相关测试]

* '''兼容性：''' G2代码必须使用PHP4和5才能运行，即PHP 4.1.0+ (对G2.2则是4.3.0+)和 PHP 5.0.4+。请勿使用任何"PHP 5"-only的OO代码，也不要使用于PHP4.1.0中不可用的方法，除非你能够提供某种回退方案。
<pre><nowiki>
if (function_exists('foo_bar')) {
	foo_bar($data);
} else {
	myFooBar($data);
}
</nowiki></pre>

== 文件系统/平台==

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

== 字串/文本和翻译 ==

* 对于所有显示给最终用户的字串/文本，使用
<pre><nowiki>
$plugin->translate('Some text')
</nowiki></pre>
<nowiki>
</nowiki>如果文本进入数据库，并且在自数据库进行取回时<tt>translate()</tt>被呼叫的话，使用
<pre><nowiki>
$gallery->i18n('Some text')
</nowiki></pre>
<nowiki>
</nowiki>在smarty模板中：
<pre><nowiki>
{g->text text="Some text"}
</nowiki></pre>
:: '''注：''' 例外情况就是GalleryStatus对象中的可选消息，以及不使用<tt>translate()</tt>的单位测试失败的消息。

* 如果你在字串中使用HTML，请使用翻译方法进行编写。
<pre><nowiki>
/* 不好的写法 */
$plugin->translate('Do <b>NOT</b> do this!');

/* 好的写法 */
$plugin->translate(array('text' => 'Do %sNOT%s do this!', 'arg1' => '<b>', 'arg2' => '</b>'));
</nowiki></pre>

* 当字串包括变量时还是使用translate参数。
<pre><nowiki>
/*不好的写法*/
$plugin->translate("Next, please read chapter '$chapter'");

/*好的写法*/
$plugin->translate(array('text' => "Next, please read '%s'", 'arg1' => $chapter));
</nowiki></pre>
<nowiki>
</nowiki>在smarty模板中：
<pre><nowiki>
{g->text text="Next, please read '%s'" arg1=$chapter}
</nowiki></pre>

== 杂项 ==

* '''URL生成：''' 使用Gallery提供的方法生成所有的URL。<br /><nowiki>
</nowiki>In PHP:
<pre><nowiki>
global $gallery;
$urlGenerator =& $gallery->getUrlGenerator();
$url = $urlGenerator->generateUrl($params, $options);
</nowiki></pre>
<nowiki>
</nowiki>在smarty模板中：
<pre><nowiki>
{g->url arg1= ....}
</nowiki></pre>

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

[[Category:Gallery 2:Development|Coding Guidelines]]