iOS Developer Library — Prerelease

Developer

Photos Framework Reference

Introduction

Classes   Protocols   Other Reference  

In iOS and OS X, the Photos framework provides classes that support building photo editing extensions for the Photos app. In iOS, the Photos framework also provides direct access to the photo and video assets managed by the Photos app, including the iCloud Photo Library. Use this framework to retrieve assets for display and playback, edit their image or video content, or work with collections of assets such as albums, moments, and iCloud Shared Albums.

Features & Concepts

In iOS, the Photos framework includes a number of features for working directly with a user’s Photos library.

  • Fetching entities and requesting changes. Instances of the Photos framework model classes (PHAsset, PHAssetCollection, and PHCollectionList) represent the entities a user works with in the Photos app: assets (images or videos), collections of assets (such as albums or moments), and lists of collections (such as album folders or moment clusters). These objects, also called photo entities, are read-only, immutable, and contain only metadata.

    You work with assets and collections by fetching the photo entities you’re interested in and then using those objects to fetch the data you need to work with. To make changes to photo entities, you create change request objects and explicitly commit them to the shared PHPhotoLibrary object. This architecture makes it easy, safe, and efficient to work with the same assets from multiple threads or multiple apps and app extensions.

  • Change observing. Use the shared PHPhotoLibrary object to register a change handler for the photo entities you fetch. Photos tells your app whenever another app or device changes the content or metadata of an asset or the list of assets in a collection. PHChange objects provide information about object state before and after each change with semantics that make it easy to update a collection view or similar interface.

  • Support for Photos app features. Use the PHCollectionList class to find assets corresponding to the Moments hierarchy in the Photos App. Use the PHAsset class to identify burst photos, panoramic photos, and high-frame-rate videos. When the iCloud Photo Library is enabled, assets and collections in the Photos framework reflect content available across all devices on the same iCloud account.

  • Asset and thumbnail loading and caching. Use the PHImageManager class to request images of assets at a specified size, or AV Foundation objects to work with video assets. The Photos framework automatically downloads or generates images to your specification, caching them for quick reuse. For faster performance with large numbers of assets—for example, when populating a collection view with thumbnails—the PHCachingImageManager subclass adds bulk preloading.

  • Asset content editing. The PHAsset and PHAssetChangeRequest classes define methods to request photo or video content for editing and to commit your edits to the photo library. To support continuity of editing between different apps and extensions, Photos keeps the current and previous versions of each asset, along a with PHAdjustmentData object that describes the last edit. If your app supports the adjustment data from a previous edit, you can allow the user to revert or alter the edit.

In both iOS and OS X, the Photos framework provides classes for use in developing photo editing extensions for use in the Photos app; however, the principal class of an extension must adopt the PHContentEditingController protocol defined by the PhotosUI framework. For details on Photos app extensions, see App Extension Programming Guide and PhotosUI Framework Reference.

Classes

NSObject

NSObject is the root class of most Objective-C class hierarchies.

PHAdjustmentData

When a user edits an asset, Photos saves a PHAdjustmentData object along with the modified image or video data.

PHAssetChangeRequest

You create and use PHAssetChangeRequest objects within a photo library change block to create, delete, or modify PHAsset objects.

PHAssetCreationRequest

PHAssetCollectionChangeRequest

You create and use PHAssetCollectionChangeRequest objects within a photo library change block to create, delete, or modify PHAssetCollection objects.

PHAssetResource

PHAssetResourceCreationOptions

PHAssetResourceManager

PHAssetResourceRequestOptions

PHChange

Photos provides PHChange objects to notify your app of changes to the assets and collections managed by the Photos app.

PHCollectionListChangeRequest

You create and use PHCollectionListChangeRequest objects within a photo library change block to create, delete, or modify PHCollectionList objects.

PHContentEditingInput

A PHContentEditingInput object describes an asset to be used for editing.

PHContentEditingInputRequestOptions

You use a PHContentEditingInputRequestOptions object to specify options when requesting to edit the image or video content of a PHAsset object.

PHContentEditingOutput

A PHContentEditingOutput object represents the results of editing the photo or video content of a Photos asset.

PHFetchOptions

You use a PHFetchOptions object to specify options when using class methods on the PHAsset, PHCollection, PHAssetCollection, and PHCollectionList classes to retrieve photo entities.

PHFetchResult

A PHFetchResult object is a container for an ordered list of photo entity objects.

PHFetchResultChangeDetails

A PHFetchResultChangeDetails object provides detailed information about the differences between two fetch results—one that you previously obtained and an updated one that would result if you performed the same fetch again.

PHImageManager

The shared PHImageManager object provides methods for loading image or video data associated with a PHAsset object.

PHCachingImageManager

A PHCachingImageManager object fetches or generates image data for photo or video assets.

PHImageRequestOptions

You use a PHImageRequestOptions object to specify options when requesting image representations of photo assets from a PHImageManager object.

PHObject

The PHObject class is the abstract base class for photo entity objects.

PHAsset

A PHAsset object represents an image or video file that appears in the Photos app, including iCloud Photos content.

PHCollection

The PHCollection class is an abstract class that defines behavior shared between Photos collection classes.

PHAssetCollection

A PHAssetCollection object represents a collection of photo or video assets.

PHCollectionList

A PHCollectionList object represents a group of asset collections.

PHObjectPlaceholder

A PHObjectPlaceholder object is a read-only proxy representing an object yet to be created.

PHObjectChangeDetails

A PHObjectChangeDetails object provides detailed information about differences between two states of a photo entity—one that you previously obtained and an updated state that would result if you fetched that entity again.

PHPhotoLibrary

The shared PHPhotoLibrary object represents the user’s Photos library—the entire set of assets and collections managed by the Photos app, including objects stored on the local device and (if enabled) in iCloud Photos.

PHVideoRequestOptions

You use a PHVideoRequestOptions object to specify options when requesting video assets from a PHImageManager object.

Protocols

PHPhotoLibraryChangeObserver

The PHPhotoLibraryChangeObserver protocol notifies you of changes that occur in the Photos library, regardless of whether those changes are made by your app, by a user in the Photos app, or by another app that uses the Photos framework.

Other Reference

Photos Constants Reference