编辑“Gallery:API”

= Gallery应用程序编程接口（API） =

与Gallery的最佳程序性交互方式就是使用各类Gallery [http://en.wikipedia.org/wiki/API API]。这些善加定义的接口使你能够以可靠且有效率的方式访问Gallery框架的几乎所有层面。而框架则提供所有的工具，使得向Gallery添加诸多且复杂特点的过程更容易，从而为你免去了繁杂的工作。它还允许你轻松地编写能够在诸多我们所支持的不同操作系统和数据库中使用的特点，而你则无需劳神了解各不同操作平台繁枝末节的信息。

== 不同种类的API ==

在Gallery2中有4类API：

;[http://gallery.menalto.com/apidoc/GalleryCore/Classes/GalleryCoreApi.html GalleryCoreApi]
:这是Gallery2的主要API。它使所有PHP代码都能够与Gallery2框架进行交互并且能够读写我们所有的核心数据。

;[http://gallery.menalto.com/apidoc/GalleryCore/Classes/GalleryModule.html GalleryModuleApi]
:该API定义模块结构或行为特定的所有方面。这包括GalleryModule类别（及其基础类别，即GaglleryPlugin）中定义的方法以及模块层中所有预定义位置或结构，比如生成的SQL文件的位置module.inc的名称/位置。

;[http://gallery.menalto.com/apidoc/GalleryCore/Classes/GalleryTheme.html GalleryThemeApi]
:该API定义外观主题结构或行为特定的所有方面。这包括GalleryTheme类别（及其基础类别，即GaglleryPlugin）的所有方法。

;[http://gallery.menalto.com/apidoc/GalleryCore/Classes/GalleryEmbed.html GalleryEmbedApi]
:该API定义用于将Gallery2嵌入/整合到其他应用程序和脚本中的接口结构或行为特定的所有方面。它使得外部PHP脚本能够与Gallery2框架交互从而能够轻易地将整个Gallery2前端嵌入另一个页面中并作为来自外部脚本的互作的入口点。

以上为我们[http://gallery.menalto.com/apidoc/index.html PHPDoc]的Gallery2完整代码库链接。

Gallery API具有两个部分：主号（major number）和次号（minor number）。主号表示大的，非向后兼容的API改动数；而次号则表示自最近大改动之后的小的，向后兼容的API改动数。API的使用者（你在编写的某个模块或使用GalleryEmbed的外部PHP脚本）能够定义必需的主/次号组合，表示其自Gallery2框架所需的功能级别。为了能够兼容，框架必须提供'''完全'''匹配的主码以及与必需的次号'''对等或较大'''的次号。

== 向后兼容的修改 ==

要说明这点，假设我们目前用的是GalleryCoreApi level '''1.0'''（这里主号为'''1'''而次号为'''0'''）。如果你编写新模块的话，那么你需要的核心api也为1.0版，表明你需要API 1.0版中所有可用的功能而较早的版本则无法使用这些功能。当然你不太可能需要每个方法都使用的，而较早版本''也是有可能''符合你的需要的，但最简单的办法还是依赖最新的API无疑。因此在你的新模块中会有这样一行：

 $this->setRequiredCoreApi(array(1, 0));

当框架载入你的模块时，它会检查主号符号情况（实际是符合的）以及必要的次号小于或等于提供的次号（实际也是）。目前为止一切都很顺利。

现在假设我们扩展了GalleryCoreApi并添加了某个全新的方法（比如我们添加了GalleryCoreApi::sendEmailToUser）。这就是一个''向后兼容（backwards compatible）''的API改动，因为需要API 1.0的仍可工作。因此我们更新API的次版本至'''1.1'''版，意即出现了新的可用特点。而你的模块仍能够正常工作，因为1.1版符合并远远满足1.0。目前为止一切仍很顺利。

现在假定你要在自己的代码中使用此方法。一旦你使用了该方法，就应当更新你的要求以反应某个事实，即你的代码在不具有1.1核心API的Gallery2.0中将无法运作。因此修改你的代码为：

 $this->setRequiredCoreApi(array(1, 1));

这能够比较好地兼容Gallery。然而，如果你把自己所编写的新模块给某个还在使用较旧版本Gallery朋友使用的话，一旦他运行了你的代码，PHP就会报错，因为你的代码会尝试使用新的sendEmailToUser() 函数，但此函数在老版本的Gallery中根本就不存在！但我们的框架会检测到此差池，因此在你朋友进行升级之前是无法安装你所提供的新模块的。

向后兼容改动举例：
* 向API添加新方法
* 在预定位置添加新文件类型（比如我们可以添加一个规则，即如果你在模块目录中放入名为''theme.css''的文件的话，那么它就会被包括到所有模块页面中）
* 向现有方法添加新参数，只要心参数具有一默认值，这样一来，已使用该值得代码就不会发生错误或给出警告提示。

== 非向后兼容的修改 ==

如果Gallery开发者作出的修改'''不是'''向后兼容的话，那么事情就不好办了。一旦发生这种情况，我们就需要确保所有依赖某经更改代码的代码不再被使用才行。在这些情况下，我们修改API的主版本号。所有需要旧主版本号的外观主题和模块会被禁用，直到你对它们进行升级。

我们正尽力减少非向后兼容的修改发生。 它们是具破坏性的，因为它们会将用户分成组，即使用旧版本的用户和使用新版本的用户。这就意味着，用户可能需要不断更新以获取新的特点，并且/或者是模块开发者可能会被强制同时维护两个版本的模块。然而，在我们完善Gallery的工作进程中，这些修改往往是无法避免的。

非向后兼容改动举例：
* 从某个API中移除某方法
* 修改某预定文件的名称或位置（如module.inc或生成的sql文件的位置）
* 修改某API方法的行为 
* 移除或重新排序某API方法的参数，且不让API方法同时接受旧形式
* 从''lib/''中移除一个库

== 跟踪API的相关改动 ==

我们希望你能轻松地追踪到API的更改信息，这样就能保证代码的更新度了。作为模块开发者，一般来说有两个等级的API你应当支持：最近一次较大发布版本的API和源控制中最新的API。为了方便起见，我们按照所发布的版本将API更改进行了分类。

* [[Gallery:API弃用日志]]
* [[Gallery:自Alpha-1到2.0的API改动]]
* [[Gallery:自2.0到2.1的API改动]]
* [[Gallery:自2.0到2.2的API改动]]
* [[Gallery:自最近版本以来的API改动]]

当做出某项更改时，我们会更新相应的页面的。如果你是一个模块或外观主题开发者的话，多关注相应页面对保证工作的更新度是很有帮助的。

[[Category:Gallery 2:Development|API]]