Class

PHPhotoLibrary

A shared object that manages access to and changes in the user’s Photos library.

Overview

The shared PHPhotoLibrary object represents the entire set of assets and collections managed by the Photos app, including both assets stored on the local device and (if enabled) those stored in iCloud Photos. You use this object to perform changes to sets of objects in the Photos library—for example, editing asset metadata or content, inserting new assets, or rearranging the members of a collection. You also use the photo library object to register for messages that Photos sends whenever changes occur to the content or metadata of assets and collections, and to verify that the user has authorized your app to access Photos content.

Requesting Changes to the Photo Library

PHAsset, PHAssetCollection, and PHCollectionList instances are immutable objects. Therefore, to modify the Photos assets or collections these objects represent, you use the shared photo library to execute a change block. Inside the change block, you create change request objects. You apply a change block with one of the methods listed in Applying Changes to the Photo Library. The changes you request in the block take effect after Photos runs the block and calls your completion handler.

Each of the change request classes—PHAssetChangeRequest, PHAssetCollectionChangeRequest, and PHCollectionListChangeRequest—corresponds to an asset or collection class. Use these classes to perform the following edit operations:

  • Creating items. Each change request class provides methods for requesting to create a new item of the corresponding asset or collection class. For example, use the creationRequestForAssetCollection(withTitle:) method to create an asset collection.

    To reference a newly created request within the change block—for example, to add a new asset to a collection—use the PHObjectPlaceholder object provided by the change request. After the change block completes, use the placeholder object’s localIdentifier property to fetch the created object.

  • Deleting items. Each change request class provides methods for requesting to delete one or more items of the corresponding asset or collection class. For example, use the deleteCollectionLists(_:) method to delete collection lists.

  • Modifying items. You modify an existing asset or collection by creating a change request from a PHAsset, PHAssetCollection, or PHCollectionList object representing it. For example, the init(for:) method creates a change request you can use for modifying an asset.

    After creating a change request, use its properties and instance methods to modify the corresponding features of the asset or collection it represents. For example, to set an asset’s isFavorite property, set the isFavorite property of a change request created from that asset. To add to an asset collection, call the addAssets(_:) method on an asset collection change request.

Use a change block to combine several changes to the photo library into a single atomic update. Listing 1 illustrates using a change block to create an asset from an image and add that asset to an album.

Listing 1

Creating an asset and adding it to an album

func addAsset(image: UIImage, to album: PHAssetCollection) {
    PHPhotoLibrary.shared().performChanges({
        // Request creating an asset from the image.
        let creationRequest = PHAssetChangeRequest.creationRequestForAsset(from: image)
        // Request editing the album.
        guard let addAssetRequest = PHAssetCollectionChangeRequest(for: album)
            else { return }
        // Get a placeholder for the new asset and add it to the album editing request.
        addAssetRequest.addAssets([creationRequest.placeholderForCreatedAsset!] as NSArray)
    }, completionHandler: { success, error in
        if !success { NSLog("error creating asset: \(error)") }
    })
}

Observing Changes

To be notified of changes to the photo library, use the register(_:) method to designate an observer object. Whenever you use a fetch method (such as fetchAssets(with:)) to retrieve assets or collections, Photos automatically registers your interest in observing changes to those items. After you perform a fetch, Photos sends messages to your observer whenever the items in the resulting fetch request change—including when changes happen that add to, remove items, or reorder the list of items in the fetch result.

For details on handling changes, see the PHPhotoLibraryChangeObserver protocol.

Topics

Verifying Authorization

class func authorizationStatus()

Returns information about your app’s authorization for accessing the user’s Photos library.

class func requestAuthorization((PHAuthorizationStatus) -> Void)

Requests the user’s permission, if needed, for accessing the Photos library.

enum PHAuthorizationStatus

Information about your app’s authorization to access the user’s Photos library, used by the authorizationStatus() and requestAuthorization(_:) methods.

Getting the Shared Photo Library Object

class func shared()

Retrieves the shared photo library object.

Applying Changes to the Photo Library

func performChanges(() -> Void, completionHandler: ((Bool, Error?) -> Void)? = nil)

Asynchronously runs a block that requests changes to be performed in the Photos library.

func performChangesAndWait(() -> Void)

Synchronously runs a block that requests changes to be performed in the Photos library.

Observing Changes in the Photo Library

func register(PHPhotoLibraryChangeObserver)

Registers an object to receive messages when objects in the photo library change.

func unregisterChangeObserver(PHPhotoLibraryChangeObserver)

Unregisters an object so that it no longer receives change messages.

Relationships

Inherits From

Conforms To

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software