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.
There are 4 versioned APIs in Gallery2:
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.
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:
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:
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.
