umask()

Introduction

En PHP, la fonction umask() définit les permissions par défaut pour les fichiers et répertoires nouvellement créés. C'est un outil utile pour gérer les accès aux fichiers dans vos scripts. Dans cet article, nous abordons tout ce que vous devez savoir sur umask(), notamment sa syntaxe, ses paramètres et des exemples pratiques.

Comprendre la fonction umask()

Le umask (masque de mode de création de fichiers utilisateur) est un ensemble de bits de permissions que le système d'exploitation supprime des permissions par défaut chaque fois qu'un processus crée un fichier ou un répertoire. La fonction umask() lit ou modifie ce masque pour le processus PHP en cours.

• Elle accepte un paramètre optionnel $mask. Si elle est appelée sans argument, elle retourne le masque actuel sans rien modifier.
• Lorsqu'un masque est fourni, il devient le nouveau masque et la fonction retourne la valeur précédente du masque.
• Le masque s'applique à l'ensemble du processus PHP, pas seulement au script en cours — le modifier peut donc affecter les opérations sur les fichiers ultérieures dans la même requête.

PHP part des permissions de base du système — généralement 0666 pour les fichiers (lecture + écriture, pas d'exécution) et 0777 pour les répertoires — et calcule les permissions finales par un ET binaire avec le masque inversé :

final = base & ~mask

Comment fonctionne le calcul du masque

Le masque efface les bits qu'il contient. Chaque chiffre octal correspond au propriétaire, au groupe et aux autres, et chaque chiffre est la somme de lecture (4), écriture (2) et exécution (1).

Avec umask(022) :

files:        0666 & ~022 = 0666 & 0755 = 0644   (rw-r--r--)
directories:  0777 & ~022 = 0777 & 0755 = 0755   (rwxr-xr-x)

Le 2 aux positions du groupe et des autres supprime le bit d'écriture, de sorte que le groupe et les autres peuvent lire mais pas écrire. Un umask(077) plus strict efface toutes les permissions du groupe et des autres, donnant 0600 pour les fichiers et 0700 pour les répertoires — des fichiers accessibles uniquement par le propriétaire.

Syntaxe de la fonction umask()

La syntaxe de la fonction umask() est la suivante :

umask($mask);

Ici, $mask est le nouveau masque. Il doit être spécifié en notation octale, donc écrivez-le toujours avec un zéro initial (par exemple, 022). Écrire 22 serait interprété comme la valeur décimale 22, et non le masque octal souhaité.

Exemples d'utilisation de umask()

Exemple 1 : Définir les permissions par défaut pour les nouveaux fichiers

<?php

umask(022);
$file_handle = fopen('example.txt', 'w');
fclose($file_handle);
echo 'File permissions: ' . decoct(fileperms('example.txt') & 0777);
unlink('example.txt');

Résultat :

File permissions: 644

Ce code définit le masque à 022, puis crée example.txt. La permission de base du fichier 0666 moins les bits d'écriture masqués donne 0644. L'appel à fileperms() lit les permissions réelles, et & 0777 supprime les bits de type de fichier pour que decoct() n'affiche que la partie d'accès.

Exemple 2 : Lire et restaurer le masque actuel

Le masque affectant l'ensemble du processus, une fonction bien conçue doit le restaurer une fois terminée. Appeler umask() sans argument retourne la valeur actuelle sans la modifier.

<?php

// Save the current mask, then apply a strict one
$old = umask(077);

$dir = sys_get_temp_dir() . '/private';
mkdir($dir);
echo 'Dir permissions: ' . decoct(fileperms($dir) & 0777) . "\n";

// Restore the original mask
umask($old);
echo 'Restored mask: ' . decoct(umask()) . "\n";

rmdir($dir);

Résultat :

Dir permissions: 700
Restored mask: 22

Ici, umask(077) efface tous les bits du groupe et des autres, donc le nouveau répertoire obtient 0777 & ~077 = 0700 — accessible uniquement par le propriétaire. Sauvegarder le masque précédent dans $old et le repasser à umask() laisse le processus dans l'état initial.

Erreurs courantes

• umask() est à portée du processus entier. Dans un contexte à longue durée de vie (workers FPM, démons CLI), l'appel à umask() d'un script se propage aux requêtes suivantes sur le même worker. Restaurez toujours la valeur précédente comme dans l'Exemple 2.
• Il ne s'applique qu'à la création. Les fichiers existants ne sont pas modifiés ; utilisez chmod() pour changer les permissions après coup.
• Le système d'exploitation limite le résultat. umask() peut uniquement supprimer des bits. Il ne peut pas accorder le bit d'exécution à un fichier ordinaire, car le mode de base pour les fichiers est déjà 0666.
• Oublier le zéro initial. umask(22) et umask(022) n'ont pas la même signification — le premier est décimal, le second est octal.

Fonctions associées

• chmod() — modifier les permissions d'un fichier ou répertoire existant.
• fileperms() — lire les bits de permissions actuels d'un fichier.
• mkdir() — créer un répertoire (son argument mode est également filtré par le umask).
• fopen() — ouvrir ou créer un fichier.

Conclusion

La fonction umask() contrôle les bits de permissions supprimés des fichiers et répertoires nouvellement créés. Rappelez-vous qu'elle fonctionne en supprimant des bits (base & ~mask), s'applique à l'ensemble du processus et n'affecte que les nouvelles créations. Lorsque vous la modifiez à l'intérieur d'une fonction, sauvegardez et restaurez la valeur précédente pour éviter des effets indésirables sur le code suivant.

Pratique