API

You have created your own theme or your own plugin and would like to take advantage of Photo Engine to make everything even better. If you need something specific, or more information, don’t hesitate to ask on the WordPress forums, here.

Introduction

The Photo Engine API is a set of PHP functions you can call, plus WordPress actions and filters you can hook into.

Photo Engine also has a small public REST API under /wp-json/wplr/v1, with the routes /auth, /hierarchy and /gallery/{id}. It is off by default: turn on Public API in Meow Apps → Photo Engine → Basics.

Functions

There is one global you should be aware of.

global $wplr;

It gives you access to the functions below. The running version is in the WPLR_SYNC_VERSION constant.

Typically, a plugin or a theme willing to take advantage of WP/LR Sync will use the get_hierarchy function and the get_media_from_collection functions.

Hierarchy

  • get_hierarchy(): retrieves the whole hierarchy of LR folders and LR collections.
  • get_keywords_hierarchy(): retrieves the whole hierarchy of LR keywords.

Media entries

  • get_media_from_collection( $lrCollectionId ): retrieve all the Media entries (IDs) for a LR collection.
  • get_media_from_tag( $lrTagId ): retrieve all the Media entries (IDs) for a LR keyword.

Collections

  • get_collection( $lrCollectionId ): retrieve information about a specific LR collection
  • get_collections_from_folder( $lrfolderId ): retrieve all the LR collections (IDs) available in the specified LR folder.
  • get_collections_from_media( $mediaId ): retrieve all the LR collections (IDs) a Media entry is attached to.
  • get_collection_from_slug( $slug ): retrieve a LR collection from its slug.
  • get_gallery( $id ): retrieve the Media entries of a LR collection, with extra information for galleries.

Folders

  • get_folder( $id ): retrieve information about a specific LR folder.
  • get_folder_from_slug( $slug ): retrieve a LR folder from its slug.
  • get_folders_from_folder( $folderId ): retrieve all the LR folders available in the specified LR folder (or at the root, without a folder ID).

Tags

There aren’t many functions for tags yet. If you need something specific, don’t hesitate to add a feature request here.

  • get_tags_from_media( $mediaId ): retrieve all the LR keywords (IDs) attached to a specific Media entry.

Other

There are many other functions, but it is not recommended to use them as they should only be used for internal operations.

  • get_sync_info( $mediaId ): get sync information for a Media entry. If the Media entry is synchronized with LR, you will also get the lrId, which is the ID of the image in Lightroom.

Actions

If you would like to hook on events happening within WP/LR Sync, you can use the WordPress actions. The free WP/LR Theme Assistant extension is built only on those actions.

Media entries

  • wplr_add_media ⇢ $mediaId
  • wplr_update_media ⇢ $mediaId, $collectionIds
  • wplr_remove_media ⇢ $mediaId
  • wplr_add_media_to_collection ⇢ $mediaId, $collectionId
  • wplr_remove_media_from_collection ⇢ $mediaId, $collectionId
  • wplr_presync_media ⇢ $lrInfo, $tmpPath
  • wplr_sync_media ⇢ $sync

Collections & Folders

  • wplr_create_collection ⇢ $collectionId, $inFolderId, $collection
  • wplr_update_collection ⇢ $collectionId, $collection
  • wplr_move_collection ⇢ $collectionId, $folderId, $previousFolderId
  • wplr_remove_collection ⇢ $collectionId

Folders

  • wplr_create_folder ⇢ $folderId, $inFolderId, $folder
  • wplr_update_folder ⇢ $folderId, $folder
  • wplr_move_folder ⇢ $folderId, $inFolderId, $previousFolderId
  • wplr_remove_folder ⇢ $folderId

Tags

  • wplr_add_tag ⇢ $tagId, $name, $parentId
  • wplr_update_tag ⇢ $tagId, $name, $parentId
  • wplr_move_tag ⇢ $tagId, $parentId, $previousParentId
  • wplr_remove_tag ⇢ $tagId
  • wplr_add_media_tag ⇢ $mediaId, $tag
  • wplr_remove_media_tag ⇢ $mediaId, $tag

Others

  • wplr_order_collection ⇢ $mediaIds, $collectionId
  • wplr_reset
  • wplr_clean

Filters

There are only a few filters, since Photo Engine’s data shouldn’t be modified by other processes. The one you might need:

  • wplr_calculate_pHash ⇢ null, $path

This filter allows you to bypass the very slow process of calculating the perceptual hash normally performed by WP/LR Sync, when you use the Total Synchronization module. If you have your own way to match files, return your own hash here. Since this filter is only used once, I can make it work a bit differently if you need. Don’t hesitate to contact me about it.