Gallery2:API - Gallery Codex
Personal tools

Gallery2:API

From Gallery Codex

Gallery Application Programming Interfaces

The best way to programmatically interact with Gallery is to use the various Gallery APIs. These are well defined interfaces that allow you to get access to almost all aspects of the Gallery framework in a reliable and efficient manner. The framework is designed to provide you with all the tools that you need to add many useful and sophisticated features to Gallery without having to do all the grunt work yourself. It also lets you easily write features that will work properly on all the different operating systems and databases that we support without you having to know the details of each different platform.

The Different APIs

There are 4 versioned APIs in Gallery2:

GalleryCoreApi
This is the main API for Gallery 2. It provides a means for any PHP code to interact with the Gallery 2 framework and get read and write access to all of our core data.
GalleryModuleApi
This API defines anything specific to the structure or behavior of modules. This includes methods defined in the GalleryModule class (as well as its base class, GalleryPlugin) and any predefined locations or structures in the module hierarchy, such as the location of generated SQL files and the name/location of module.inc.
GalleryThemeApi
This API defines anything specific to the structure or behavior of themes. It includes all methods to the GalleryTheme class (as well as its base class, GalleryPlugin).
GalleryEmbedApi
This API defines anything specific to the structure or behavior of the interface to embedding / integrating Gallery 2 in other applications and scripts. It provides a means for external PHP scrpts to interact with the Gallery 2 framework to easily embed the whole Gallery 2 front-end in another page and serves as an entry point for GalleryCoreApi interactions from external scripts.

The above are links into our PHPDoc for the entire Gallery 2 codebase.

The Gallery APIs have two components: a major number and a minor number. The major number indicates the number of large, non-backwards-compatible changes made to the API. The minor number indicates the number of minor, backwards compatible changes that have been made to the API since the last major change. A consumer of the API (a module you're writing, or maybe an external PHP script that uses GalleryEmbed) can specify a required major/minor number combination indicating the level of functionality it requires from the Gallery 2 framework. In order to be compatible, the framework must provide exactly the same major version number, and a minor number that is equal to or greater than the required minor number.

Backwards Compatible Changes

To illustrate this point, supposing we are at GalleryCoreApi level 1.0 (where the major number is 1 and the minor number is 0). If you write a new module you would say that your required core api is also 1.0 indicating that you need all the functions that are available in the 1.0 version of the API and that earlier versions are unacceptable. Of course, you probably don't use every single method and it's possible that an earlier version might suit your needs but the easiest approach is to rely on the current API. So in your new module you'd have a line like this:

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

When the framework loads up your module it's going to check the the major numbers match (which they do) and that the minor number required is less than or equal to the minor number provided (which it is). So far so good.

Now supposing we extend the GalleryCoreApi and add a brand new method (eg, we add GalleryCoreApi::sendEmailToUser). This is a backwards compatible change to the API because anything that required API 1.0 will still work. So we update the minor version of the API to 1.1 which means that there's a new feature available if you want to use it. Your module will continue to work because 1.1 meets and exceeds the required 1.0. So far so good.

Supposing now you decide to use this method in your code. As soon as you use the method, you should update your requirements to reflect the fact that your code will no longer work on a version of Gallery 2.0 that doesn't have the 1.1 core api. So you change your code to:

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

This works just fine for your Gallery. However, you give a copy of your shiny new module to a friend who is running an older version of Gallery. If he runs your code, PHP will complain because your code is trying to use the new sendEmailToUser() function that doesn't exist in his older copy of Gallery! But before that can happen, our framework will detect this mismatch and not even let your friend install your new module until he upgrades.

Examples of backwards compatible changes:

  • Adding a new method to the API
  • Adding a new file type in a predetermined location (for example we could add a rule that if you put a file called theme.css in your module directory it gets included on every module page)
  • Adding a new argument to an existing method, as long as the new argument has a default value so that code that already uses it doesn't give warnings or errors.

Non Backwards Compatible Changes

Things get a little bit harder if the Gallery developers make a change that is not backwards compatible. When that happens, we have to make sure that all code that is depending on the code that changed is no longer used. In those cases, we change the major version number of the API. Any modules and themes that required the old major version number will get deactivated until you can upgrade them.

We try to make non-backwards compatible changes as infrequently as possible. They're disruptive because they separate our users into groups, those who have the old version and those who have the new one. This means that users may have to upgrade more than they want to in order to get a new feature, and/or module developers may be forced to maintain two versions of their modules. However, sometimes these changes are unavoidable in our quest to continue making Gallery the best possible.

Examples of non-backwards compatible changes:

  • Removing a method from an API
  • Changing the name or a location of a predetermined file (like module.inc or the location of generated sql files)
  • Changing the behavior of an API method
  • Removing or reordering the arguments to an API method without making the API method accept both the old form
  • Removing a library from lib/

Keeping Track of API Changes

We'd like to make it easy for you to keep track of API changes so that you can keep your code up to date. As a module developer there are generally two levels of APIs that you should support: the APIs of the last big release and the latest APIs in source control. In order to make that easy for you we've broken down our API change tracking by releases.

When we make a change, we'll update the appropriate page. If you're a module or theme developer it's a good idea to keep an eye on the appropriate page so that you can keep your work up to date.

advertisements