Documents Directory : qu'est-ce que c'est, objectif et accès aux fichiers

Qu'est-ce que Documents Directory sous iOS ?

Documents Directory est un répertoire dans le sandbox d'une application iOS conçu pour stocker les données utilisateur qui doivent persister entre les lancements et être accessibles à l'utilisateur. Chaque application reçoit son propre sandbox isolé, et Documents est l'un des répertoires clés aux côtés de Caches, tmp et Library.

iOS utilise un sandbox strict : une application n'a pas accès au système de fichiers des autres applications ni aux répertoires système sans autorisations spéciales. Documents Directory est le seul répertoire dont l'utilisateur peut visualiser le contenu via iTunes File Sharing (lorsque la clé UIFileSharingEnabled est activée dans Info.plist).

Selon Apple WWDC 2023, plus de 85% des applications de l'App Store utilisent Documents Directory pour stocker au moins un type de données utilisateur — des PDF exportés aux fichiers de jeu sauvegardés et images exportées.

Il est important que le développeur comprenne : les fichiers dans Documents sont automatiquement inclus dans les sauvegardes iCloud et iTunes. Si une application stocke de gros volumes de données récupérables dans Documents (par exemple, le cache d'images ou des fichiers temporaires), cela entraîne une consommation inutile de l'espace de stockage iCloud de l'utilisateur.

Comment obtenir le chemin vers Documents Directory

En Swift, le chemin vers Documents Directory est obtenu via FileManager. Apple recommande d'utiliser l'API basée sur URL plutôt que celle basée sur les chaînes pour une meilleure compatibilité avec les fonctionnalités modernes d'iOS.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// Créer un fichier dans Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C utilise NSSearchPathForDirectoriesInDomains — une approche plus ancienne mais toujours prise en charge qui renvoie un chemin de chaîne au lieu d'une URL.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

Les projets modernes en Swift doivent utiliser FileManager.urls, car cette méthode renvoie une URL plutôt qu'une chaîne, ce qui réduit le risque d'erreurs d'encodage de chemin et rend le code plus sûr au niveau des types.

Quelles données stocker dans Documents

Documents Directory est destiné aux données créées par l'utilisateur ou explicitement nécessaires à l'utilisateur. Apple met en évidence plusieurs catégories appropriées pour ce répertoire.

Documents et fichiers utilisateur

Fichiers que l'utilisateur crée ou importe — documents texte, PDF, images, rapports exportés, fichiers de sauvegarde. Ces données ont une valeur directe pour l'utilisateur et leur perte serait critique.

Sauvegardes de jeux et état de l'application

Sauvegardes de jeux, fichiers d'état de l'application, projets exportés — tout ce que l'utilisateur s'attend à restaurer après la réinstallation de l'application. Cependant, pour les données critiques, il est recommandé d'utiliser en complément iCloud Key-Value Storage ou Core Data avec synchronisation iCloud.

Le critère clé : si les données peuvent être téléchargées à nouveau depuis le réseau ou recréées — elles ont leur place dans Caches, pas dans Documents. Chaque gigaoctet dans Documents est un gigaoctet dans la sauvegarde iCloud de l'utilisateur.

Sauvegarde et synchronisation

iOS inclut automatiquement le contenu de Documents Directory dans les sauvegardes lorsque l'appareil est connecté à iTunes ou lors de la synchronisation avec iCloud. Ce comportement ne peut pas être désactivé au niveau du répertoire — seulement par fichier via l'attribut NSURLIsExcludedFromBackupKey.

À partir d'iOS 5.0, Apple a commencé à rejeter les applications qui stockent de gros volumes de données récupérables dans Documents. La recommandation d'Apple : les fichiers qui peuvent être téléchargés à nouveau doivent être stockés dans Caches Directory avec le drapeau d'exclusion de sauvegarde.

import Foundation

let documentsURL = FileManager.default
    .urls(for: .documentDirectory, in: .userDomainMask)
    .first!

// Exclure le fichier de la sauvegarde iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

La synchronisation iCloud fonctionne via NSUbiquitousContainer si l'application utilise iCloud Documents. Dans ce cas, les fichiers de Documents Directory sont automatiquement synchronisés entre les appareils de l'utilisateur. Pour les applications sans iCloud, la synchronisation est limitée à la sauvegarde.

Documents Directory vs Caches Directory

La différence entre Documents et Caches est l'une des idées fausses les plus courantes parmi les développeurs iOS débutants. La principale différence : le système peut supprimer des fichiers de Caches à tout moment pour libérer de l'espace, mais il ne touche jamais à Documents sans l'accord de l'utilisateur.

Selon la Documentation Apple Developer (2024), l'utilisation inappropriée de Documents Directory est l'une des raisons courantes de rejet des applications lors de la révision : si une application stocke plus de quelques mégaoctets de données récupérables dans Documents, Apple recommande de les déplacer vers Caches ou d'appliquer NSURLIsExcludedFromBackupKey.

Une règle pratique : si l'utilisateur serait contrarié de perdre le fichier — stockez-le dans Documents. Si le fichier peut être téléchargé à nouveau ou régénéré — stockez-le dans Caches.

Bonnes pratiques pour travailler avec Documents

Les développeurs iOS expérimentés ont élaboré plusieurs règles qui aident à éviter les problèmes avec Documents Directory à toutes les étapes du cycle de vie de l'application — du développement à la publication sur l'App Store.

Surveillance de la taille du répertoire

Régulièrement vérifiez la taille de Documents Directory via FileManager.enumerator(at:includingPropertiesForKeys:). Si la taille dépasse 100 Mo pour des données non utilisateur — c'est une raison de reconsidérer l'architecture de stockage.

Exclusion des fichiers récupérables de la sauvegarde

Pour tous les fichiers qui peuvent être téléchargés à nouveau, définissez isExcludedFromBackup = true. Cela réduit la charge sur le stockage iCloud de l'utilisateur et diminue le risque de rejet par l'App Review.

Migration lors des mises à jour

Lorsque vous modifiez le format des données dans Documents, prévoyez une migration : ne supprimez pas les anciens fichiers tant que vous n'êtes pas sûr que les nouveaux sont correctement créés. Utilisez des sous-répertoires spécifiques à la version.

import Foundation

let documentsURL = FileManager.default
    .urls(for: .documentDirectory, in: .userDomainMask)
    .first!

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

Suivre ces bonnes pratiques réduit le risque de perte de données utilisateur, diminue la taille de la sauvegarde iCloud et simplifie la révision sur l'App Store.