Gallery2:API Changes From 2.0 To 2.1 - Gallery Codex
Personal tools

Gallery2:API Changes From 2.0 To 2.1

From Gallery Codex

This is the history of API changes since the Gallery 2.0 official release.


6.8 => 6.9

Plugin paths relative to the G2 base directory can now only be determined at run time. Use getPluginBaseDir($pluginType, $pluginId) to determine the base directory of the specified plugin, which is generally either the G2 base directory or g2_base_dir/plugins. To get a list of available plugin base directories, use getPluginBaseDirs().

6.9 => 6.10

Added GallerySession::initEmpty() to enable creation of new sessions to give print services access to print images that are not publically accessible.

6.10 => 7.0

  • Added GalleryCoreApi::fetchDescendentAlbumItemIds
  • Added GalleryCoreApi::removeDerivativePreferenceForItemType
  • Added GalleryPlatform::chmod, GalleryPlatform::recursiveFixDirPermissions
  • Removed GalleryPlatform::setFilePermissions
  • Always retrieve GalleryPlatform by reference now:
  $platform =& $gallery->getPlatform();
  • Changed the way that we do error handling. The new pattern is:
  $ret = someOperation();
  /* $ret is null on success or contains a GalleryStatus object on failure */
  if ($ret) {
      return $ret->wrap(__FILE__, __LINE__);


  if ($someErrorCondition) {
      return GalleryCoreApi::error(ERROR_UNKNOWN, __FILE__, __LINE__);

You can use this script to update existing code to the new pattern.

  • Added GalleryCoreApi::error to replace GalleryStatus::error
  • Renamed class DatabaseSqlFragment to GallerySqlFragment
  • Combined userId/groupId columns in GalleryAccessMap into single userOrGroupId column; update any queries involving permission tables.
  • Removed unused permission flag GALLERY_PERMISSION_ITEM_ADMIN
  • Changed parameters to GalleryUrlGenerator::generateUrl()
    • Was: generateUrl($params, $forceSessionId, $baseUrl, $forceFullUrl)
    • Now: generateUrl($params, $options)
    • Options array keys can be:
      • forceSessionId, baseUrl, forceFullUrl
      • forceDirect (was a key of $params --> now in $options)
      • htmlEntities (new option; pass false to use & separator instead of &)
    • The only {g->url} parameter that is affected by this change is "forJavascript". forJavascript=true should be replaced with htmlEntities=false.
  • Changed parameters and return value of GalleryUrlGenerator::init()
    • Was: init($baseUri, $embedPath, $relativeG2Path, $embedSessionString)
    • Now: $ret = init($baseUri, $g2Uri, $embedSessionString)
      • BaseUri is a string and can override all URL parts (from protocol, up to the query string) of URLs that Gallery generates
      • G2Uri is the same as baseUri but just for URLs that go to Gallery 2 directly even when embedded (e.g. core.DownloadItem)
      • Returns now a GalleryStatus object
      • You can use the new config.php parameter baseUri to override Gallery 2 URLs without having to change source code
  • Renamed GallerySession::_getRemoteIdentifier to getRemoteIdentifier (now a public api)
  • Removed GalleryCoreApi::requireOnce
  • Renamed GalleryCoreApi::relativeRequireOnce to GalleryCoreApi::requireOnce (replaces old requireOnce), convert script at (rename to .pl)
  • Map calls to add, update and remove map entries are now in GalleryCoreApi:
 GalleryCoreApi::addMapEntry('FooMap', array(...));
 GalleryCoreApi::updateMapEntry('FooMap', array(...), array(...));
 GalleryCoreApi::removeMapEntry('FooMap', array(...));
  • Changed parameters of GalleryCoreApi::hasPermission from int itemId, array userIds, array groupIds, string/array permissions to int itemId, int/array entityIds, string/array permissions
  • GalleryCoreApi::fetchAllPermissionsForItem now returns only userId OR groupId OR entityId key in each entry. entityId is new (rows may now have ids other than user or group ids), and previously this always returned both userId and groupId keys but one was zero
  • Added GalleryCoreApi::addEntityPermission and GalleryCoreApi::removeEntityPermission
  • Added MULTI_INSERT syntax in GalleryStorage::getFunctionSql
  • Introduced GalleryEmbedApi to track GalleryEmbed changes separately from GalleryCoreApi changes
  • New methods GalleryCoreApi::describeEntity and GalleryCoreApi::describeMap allow you to get information about entities and maps (what members they contain, the type of member, etc).
  • Added GallerySession::start() which sends now the cookie and ensures that we have a session id
  • Changed the behavior of GallerySession::init() / Gallery::initSession() . It only initializes the session now and loads the session data, but doesn't send the cookie. Call init() then start() if you still need the old behavior.
  • The session variable '' was removed. Instead of using GallerySession::put() / get() to set/get the active user id of the session, use GallerySession::setUserId() / getUserId()
  • Removed GallerySession::getCookiePath(). No official module used that function. Make sure to use GalleryUrlGenerator::getCookiePath() instead.
  • Removed GalleryDerivative::createFastDownloadFile()
  • Added GalleryDerivative::createFastDownloadFile(). Creates fast-downloads for derivatives (as-is) and GalleryDataItems
  • Removed GalleryDerivative::deleteFastDownloadFile()
  • Added GalleryCoreApi::deleteFastDownloadFileById()
  • Changed behavior of Gallery::fastDownload(). Parameter relativePath is now relative to the folder and no longer to the cache folder.
  • Removed $template and $securityLevel parameters from GalleryValidationPlugin::loadTemplate. Added $options parameter to both ::loadTemplate and ::performValidation.

7.0 => 7.1

  • GalleryCoreApi::loadPlugin now takes an optional errorOnVersionMismatch parameter which will return an error instead of trying to send you to the upgrader in the case where there's an module or theme incompatibility that can't be fixed (eg, in the case where your primary theme is incompatible with the current APIs)
  • Added GalleryCoreApi::fetchAccessListId
  • Added GalleryUtilities::htmlSafe
  • Added optional $options parameter to GalleryUtilities::convertPathToUrl
  • Added optional $extraHeaders parameter to GalleryCoreApi::fetchWebFile

7.1 => 7.2

  • Added GalleryStorage::isTransactional() and a few other functions to support locking on transactional databases.
  • Added GalleryUtilities::htmlSafe($html) to filter out malicious HTML

--Mindless 16:07, 23 February 2006 (PST)


2.0 => 2.1

Added getModuleEntityTypes so modules can specify types

--Mindless Mon, 2005-10-17 06:55

2.1 => 2.2

Changed the way that we store our per-module generated SQL so that it's all in one single file in classes/GalleryStorage/DatabaseStorage/schema/schema.tpl. For the core module, this reduces ~180 .sql files to one single file, and it won't get any larger when we introduce new databases (like DB2, which just arrived recently).

After you cvs update and run "make" in your classes directory, the new schema.tpl file will appear. Just delete the classes/GalleryStorage/DatabaseStorage/schema/platform directory and you're all set.


2.2 => 2.3

Added $template parameter to GalleryModule::getItemSummaries(), for adding header content or using $template->fetch() to render summary output.

--Bharat 14:51, 13 November 2005 (PST)

2.3 => 2.4

Added a new optional forceFullUrl parameter to GalleryUrlGenerator::generateUrl() so that we can use the full url when it's appropriate (eg, requesting a link via the image block from an external page using readfile). Same optional parameter can be used with {g->url} and {g->image} smarty tags.

--Bharat 02:52, 15 November 2005 (PST)

2.4 => 3.0

  • Removed GalleryModule::loadItemDetails; modules now use blocks.
  • Removed GalleryModule::isRecommendedDuringInstall
  • GalleryModule::autoConfigure now defaults to returning true, so most modules no longer need to override this function.
  • Module constructors may not call translate() anymore. $gallery->i18n() is ok.
  • Schema sql:
    • Old style schema sql files are no longer supported (old style had platform subdir with subdirs for each database type and separate *.sql files for each table).
    • Old style schema xml files with "_" character as version separator are no longer supported. Schema update files now must be like this: A_MyTable_1.0.xml ("." version separator).
    • The directory structure for schema definitions has been flattened. GNUmakefile and schema.tpl now reside in classes/GalleryStorage under a module dir; xml-src for schema updates is a subdir of GalleryStorage.
    • Bottom of entity *.class files now use php include() instead of GalleryCoreApi::requireOnce() to include interfaces/*.inc file.
    • All GNUmakefile files are simplified to a single "include" line.
  • Schema updates now require explicit calls in module upgrade code. Example:
 $storage =& $gallery->getStorage();
 $ret = $storage->configureStore($this->getId(), array('ImageBlockCacheMap:1.0'));
 if ($ret) {
     return $ret->wrap(__FILE__, __LINE__);

New tables are still created automatically. These calls for schema updates gives the upgrade code greater control over table changes and additional SQL statements to move data around.

  • Maps are now defined in classes/Maps.xml; there are no more *Map.class files (or corresponding interfaces). add/update/removeMapEntry functions moved to GalleryCoreApi.
  • GalleryView::_getItem returns an additional value: boolean $wasSpecified; false if no itemId/path parameter was found so default item (root album) was loaded.
  • GalleryView::loadTemplate now requests useFullScreen via a key in returned $results array instead of setting a value directly in the $theme template variable.
  • ItemEditPlugin::handleRequest has an additional return value, a boolean to indicate if a progress bar is needed for this update. Modules that register an ItemEditPlugin must add this return value.
  • Entity interface files are gone which means:
    • modules/*/classes/interfaces dir is gone
    • entity classes are no longer declared with the _core suffix, eg "class FooEntity_core extends BarEntity" is now "class FooEntity extends BarEntity"
    • entity members are now declared public and do not start with an underscore
    • Entities must override GalleryEntity::getClassName() and specify their class name
  • GalleryPersistent::getModifiedFlag() is gone, replaced by GalleryPersistent::isModified()
  • GalleryPersistent::clearModifiedFlags() is replaced by resetOriginalValues()
  • GalleryPersistent::getMemberData() is gone, replaced by an array cast, eg:
$entityData = $entity->getMemberData();

is now:

$entityData = (array)$entity;
  • GalleryPersistent::getPersistentMemberInfo has gone away in favor of GalleryStorage::describeEntity()
  • GalleryPersistent::setModifiedFlag/getModifiedFlag/getModifiedKeys are gone
  • GalleryPersistent::getClassFile added


2.1 => 2.2

GalleryTheme::getSettings now also returns the $params data which is useful for themes overriding this function.

2.2 => 2.3

Added rowHeight and columnWidth as available standard settings.
Added GalleryTheme::preloadBlock().


Gallery 2.0 (no GalleryEmbedApi) => 1.0

  • Changed parameters of GalleryEmbed::init
  • GalleryEmbed::isCompatibleWithEmbedApi() and GalleryEmbed::getApiVersion() have been added effectively introducing the GalleryEmbedApi.

1.0 => 1.1

  • When using GalleryEmbed, you need to set the content-type of your pages yourself. Until now, we have set the content-type in G2 for all pages but this caused problems with php-fastcgi. So this is actually a good change for GalleryEmbed since usually the master application sets the content-type already. Although, note that G2 currently supports only UTF8 as character encoding! Preferably before calling GalleryEmbed::handleRequest() (or init), you should call
 if (!headers_sent()) {
     header('Content-Type: text/html; charset=UTF-8');