chown()

La función chown() de PHP

La función chown() cambia el propietario de un archivo o directorio. En sistemas tipo Unix, cada archivo tiene un usuario propietario y un grupo propietario; chown() actualiza el usuario. Se utiliza principalmente por administradores de servidores y scripts de despliegue que necesitan que un archivo pertenezca a una cuenta de sistema concreta — por ejemplo, entregar un archivo subido al usuario del servidor web para que pueda ser servido o rotado.

Esta página cubre la sintaxis, los parámetros, el valor de retorno, los permisos necesarios para que funcione, los errores comunes y ejemplos ejecutables.

El propietario es el usuario, no el grupo. Para cambiar el grupo propietario, usa chgrp(). Para cambiar los permisos de lectura, escritura y ejecución, usa chmod(). Estas tres funciones se confunden frecuentemente.

Sintaxis

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

• $filename — ruta al archivo o directorio cuyo propietario deseas cambiar.
• $user — el nuevo propietario, especificado como un string con el nombre de usuario (p. ej. "www-data") o como un ID de usuario numérico (UID, p. ej. 33).

Devuelve true en caso de éxito y false en caso de fallo.

Parámetros

Pasar un string con el nombre de usuario requiere que PHP lo resuelva a un UID, por lo que el usuario debe existir en la base de datos de usuarios del sistema. Pasar el UID directamente omite esa búsqueda.

Valor de retorno

chown() devuelve un boolean:

• true — el propietario se cambió correctamente.
• false — el cambio falló (archivo no encontrado, privilegios insuficientes o el usuario indicado no existe). También se emite una advertencia.

Comprueba siempre el valor de retorno en lugar de asumir que tuvo éxito:

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

¿Quién puede llamar a chown()?

Esta es la razón más común por la que chown() "no funciona":

• En Unix, solo el superusuario (root) puede cambiar el propietario de un archivo. Un proceso normal sin privilegios de root no puede ceder un archivo a otro usuario.
• Por tanto, en un entorno de hosting compartido típico o en una configuración estándar de PHP-FPM, chown() devolverá false a menos que el proceso PHP se ejecute como root — lo cual generalmente no debería ocurrir.
• chown() no está disponible en Windows en el sentido tradicional y actúa como una operación sin efecto allí.

Si solo necesitas controlar el acceso en lugar de la propiedad, prefiere chmod(), que el propietario del archivo puede llamar sin ser root.

Ejemplos

Ejemplo 1: Establecer el propietario mediante un nombre de usuario

Establece el propietario de example.txt al usuario 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}.";
}

Ejemplo 2: Establecer el propietario mediante un UID

Si conoces el ID de usuario numérico, pásalo directamente. Aquí 1000 es un UID típico para el primer usuario no del sistema:

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

Ejemplo 3: Leer el propietario con fileowner()

Después de cambiar el propietario, puedes confirmar el resultado. fileowner() devuelve el UID, y (en sistemas con la extensión POSIX) posix_getpwuid() convierte ese UID en un nombre:

<?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() es importante aquí: PHP almacena en caché los datos de estado del archivo, por lo que sin esta llamada podrías leer el propietario anterior. Consulta clearstatcache() para más detalles.

Ejemplo 4: Cambiar la propiedad de un directorio

chown() también funciona en directorios, pero no es recursivo — solo afecta a la entrada del directorio, no a los archivos que contiene. Para cambiar la propiedad de todo un árbol, itera sobre su contenido:

<?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");
    }
}

Errores comunes

• Devuelve false en procesos sin root. Esto es por diseño — solo root puede reasignar la propiedad.
• Datos de propietario en caché. Llama a clearstatcache() antes de volver a leer la información del propietario tras un cambio.
• Se siguen los enlaces simbólicos. chown() cambia el destino del enlace. Para cambiar el propio enlace simbólico, usa lchown().
• No es recursivo. Los directorios requieren iteración manual (Ejemplo 4).
• open_basedir / disable_functions. Muchos servidores deshabilitan chown() por seguridad; comprueba php.ini si falla silenciosamente.

Funciones relacionadas

• chgrp() — cambia el grupo propietario de un archivo.
• chmod() — cambia los permisos de un archivo (lectura/escritura/ejecución).
• fileowner() — obtiene el UID del propietario de un archivo.
• filegroup() — obtiene el GID del grupo de un archivo.
• lchown() — cambia el propietario de un enlace simbólico en sí.
• clearstatcache() — limpia los datos de estado de archivo en caché de PHP.

Conclusión

La función chown() cambia el propietario de un archivo o directorio, aceptando un string con el nombre de usuario o un UID numérico y devolviendo un boolean. Lo más importante a recordar es que cambiar la propiedad requiere privilegios de superusuario, razón por la que tan frecuentemente devuelve false en el código web cotidiano. Cuando solo necesites controlar el acceso, recurre a chmod(); para cambiar el grupo, usa chgrp().

Práctica