chown()

La fonction PHP chown()

La fonction chown() modifie le propriétaire d'un fichier ou d'un répertoire. Sur les systèmes de type Unix, chaque fichier possède un utilisateur propriétaire et un groupe propriétaire ; chown() met à jour l'utilisateur. Elle est principalement utilisée par les administrateurs serveur et les scripts de déploiement qui ont besoin qu'un fichier appartienne à un compte système particulier — par exemple, pour confier un fichier uploadé à l'utilisateur du serveur web afin qu'il puisse être servi ou archivé.

Cette page couvre la syntaxe, les paramètres, la valeur de retour, les permissions nécessaires à son fonctionnement, les pièges courants et des exemples prêts à l'emploi.

Le propriétaire est l'utilisateur, pas le groupe. Pour modifier le groupe propriétaire, utilisez chgrp(). Pour modifier les permissions de lecture/écriture/exécution, utilisez chmod(). Ces trois fonctions sont souvent confondues.

Syntaxe

chown(string $filename, string|int $user): bool

• $filename — chemin vers le fichier ou le répertoire dont vous souhaitez changer le propriétaire.
• $user — le nouveau propriétaire, indiqué soit par un nom d'utilisateur en string (ex. "www-data") soit par un identifiant numérique d'utilisateur (UID, ex. 33).

Elle retourne true en cas de succès et false en cas d'échec.

Paramètres

Passer un nom d'utilisateur en string oblige PHP à le résoudre en UID, donc l'utilisateur doit exister dans la base de données d'utilisateurs du système. Passer directement l'UID évite cette résolution.

Valeur de retour

chown() retourne un boolean :

• true — le propriétaire a été modifié avec succès.
• false — la modification a échoué (fichier absent, privilèges insuffisants ou l'utilisateur indiqué n'existe pas). Un avertissement est également émis.

Vérifiez toujours la valeur de retour plutôt que de supposer le succès :

<?php
if (chown("example.txt", "www-data")) {
    echo "Owner changed successfully.";
} else {
    echo "Could not change owner.";
}

Qui peut appeler chown() ?

C'est la raison la plus fréquente pour laquelle chown() « ne fonctionne pas » :

• Sur Unix, seul le superutilisateur (root) peut modifier le propriétaire d'un fichier. Un processus normal non-root ne peut pas transférer un fichier à un autre utilisateur.
• Par conséquent, dans un hébergement mutualisé classique ou une configuration PHP-FPM standard, chown() retournera false à moins que le processus PHP ne s'exécute en root — ce qui ne devrait généralement pas être le cas.
• chown() n'est pas disponible sur Windows au sens traditionnel du terme et se comporte comme une opération sans effet sur ce système.

Si vous avez seulement besoin de contrôler les accès sans modifier la propriété, préférez chmod(), que le propriétaire du fichier peut appeler sans être root.

Exemples

Exemple 1 : Définir le propriétaire avec un nom d'utilisateur

Définir le propriétaire de example.txt à l'utilisateur www-data :

<?php
$file = "example.txt";

if (chown($file, "www-data")) {
    echo "Owner of {$file} set to www-data.";
} else {
    echo "Failed to change owner of {$file}.";
}

Exemple 2 : Définir le propriétaire avec un UID

Si vous connaissez l'identifiant numérique de l'utilisateur, passez-le directement. Ici 1000 est un UID typique pour le premier utilisateur non-système :

<?php
chown("example.txt", 1000);

Exemple 3 : Relire le propriétaire avec fileowner()

Après avoir modifié le propriétaire, vous pouvez confirmer le résultat. fileowner() retourne l'UID, et (sur les systèmes disposant de l'extension POSIX) posix_getpwuid() convertit cet UID en nom :

<?php
$file = "example.txt";

chown($file, "www-data");
clearstatcache(); // owner info is cached — clear it before re-reading

$uid  = fileowner($file);            // e.g. 33
$info = posix_getpwuid($uid);        // ["name" => "www-data", ...]

echo "Owner UID: {$uid}\n";
echo "Owner name: {$info['name']}\n";

clearstatcache() est important ici : PHP met en cache les données de statut des fichiers, donc sans cela vous pourriez lire l'ancien propriétaire. Consultez clearstatcache() pour plus de détails.

Exemple 4 : Changer la propriété d'un répertoire

chown() fonctionne aussi sur les répertoires, mais elle n'est pas récursive — elle n'affecte que l'entrée du répertoire lui-même, pas les fichiers qu'il contient. Pour changer la propriété d'une arborescence entière, parcourez son contenu :

<?php
$dir = "/var/www/uploads";

chown($dir, "www-data"); // the directory only

foreach (new DirectoryIterator($dir) as $item) {
    if (!$item->isDot()) {
        chown($item->getPathname(), "www-data");
    }
}

Pièges courants

• Retourne false pour les processus non-root. C'est voulu — seul root peut réaffecter la propriété.
• Données de propriétaire mises en cache. Appelez clearstatcache() avant de relire les informations de propriété après une modification.
• Les liens symboliques sont suivis. chown() modifie la cible du lien. Pour modifier le lien symbolique lui-même, utilisez lchown().
• Non récursive. Les répertoires nécessitent une itération manuelle (Exemple 4).
• open_basedir / disable_functions. De nombreux hébergeurs désactivent chown() pour des raisons de sécurité ; vérifiez php.ini si la fonction échoue silencieusement.

Fonctions associées

• chgrp() — modifier le groupe propriétaire d'un fichier.
• chmod() — modifier les permissions d'un fichier (lecture/écriture/exécution).
• fileowner() — obtenir l'UID du propriétaire d'un fichier.
• filegroup() — obtenir le GID du groupe d'un fichier.
• lchown() — modifier le propriétaire d'un lien symbolique lui-même.
• clearstatcache() — vider les données de statut de fichier mises en cache par PHP.

Conclusion

La fonction chown() modifie le propriétaire d'un fichier ou d'un répertoire, en acceptant soit un nom d'utilisateur en string soit un UID numérique, et retourne un boolean. L'essentiel à retenir est que modifier la propriété nécessite des privilèges superutilisateur, ce qui explique pourquoi elle retourne si souvent false dans le code web courant. Lorsque vous avez seulement besoin de contrôler les accès, préférez chmod() ; pour changer le groupe, utilisez chgrp().

Pratique