umask()

Introducción

En PHP, la función umask() establece los permisos predeterminados para los archivos y directorios recién creados. Es una herramienta útil para gestionar el acceso a archivos en tus scripts. En este artículo, cubriremos todo lo que necesitas saber sobre umask(), incluyendo su sintaxis, parámetros y ejemplos prácticos.

Comprendiendo la función umask()

La umask (máscara de modo de creación de archivos del usuario) es un conjunto de bits de permiso que el sistema operativo elimina de los permisos predeterminados cada vez que un proceso crea un archivo o directorio. La función umask() lee o cambia esa máscara para el proceso PHP actual.

• Acepta un parámetro opcional $mask. Si se llama sin argumentos, devuelve la máscara actual sin cambiar nada.
• Cuando se proporciona una máscara, esta se convierte en la nueva máscara y la función devuelve el valor de la máscara anterior.
• La máscara se aplica a todo el proceso PHP, no solo al script actual; por lo tanto, cambiarla puede afectar operaciones de archivo posteriores en la misma solicitud.

PHP parte de los permisos base del sistema — típicamente 0666 para archivos (lectura + escritura, sin ejecución) y 0777 para directorios — y calcula los permisos finales con un AND bit a bit contra la máscara invertida:

final = base & ~mask

Cómo funciona la matemática de la máscara

La máscara borra los bits que contiene. Cada dígito octal corresponde a propietario, grupo y otros, y cada dígito es la suma de lectura (4), escritura (2) y ejecución (1).

Con umask(022):

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

El 2 en las posiciones de grupo y otros elimina el bit de escritura, por lo que el grupo y los demás pueden leer pero no escribir. Una umask(077) más estricta borraría todos los permisos de grupo y otros, produciendo 0600 para archivos y 0700 para directorios — archivos a los que solo puede acceder el propietario.

Sintaxis de la función umask()

La sintaxis de la función umask() es la siguiente:

umask($mask);

Aquí, $mask es la nueva máscara. Debe especificarse en notación octal, por lo que siempre se escribe con un cero inicial (por ejemplo, 022). Escribir 22 se interpretaría como el valor decimal 22, no la máscara octal que se pretende.

Ejemplos de uso de umask()

Ejemplo 1: Establecer los permisos predeterminados para nuevos archivos

<?php

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

Salida:

File permissions: 644

Esto establece la máscara en 022 y luego crea example.txt. El permiso base del archivo 0666 menos los bits de escritura enmascarados da 0644. La llamada a fileperms() lee los permisos reales, y & 0777 elimina los bits de tipo de archivo para que decoct() imprima solo la parte de acceso.

Ejemplo 2: Leer y restaurar la máscara actual

Dado que la máscara afecta a todo el proceso, una función bien escrita debería restaurarla cuando termine. Llamar a umask() sin argumento devuelve el valor actual sin cambiarlo.

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

Salida:

Dir permissions: 700
Restored mask: 22

Aquí umask(077) borra todos los bits de grupo y otros, por lo que el nuevo directorio obtiene 0777 & ~077 = 0700 — accesible solo por el propietario. Guardar la máscara anterior en $old y pasarla de vuelta a umask() deja el proceso en el estado en que comenzó.

Errores comunes

• umask() es a nivel de proceso. En un contexto de larga ejecución (workers de FPM, daemons CLI), la llamada a umask() de un script se filtra a solicitudes posteriores en el mismo worker. Siempre restaura el valor anterior como en el Ejemplo 2.
• Solo afecta a la creación. Los archivos existentes no cambian; usa chmod() para modificar permisos después de la creación.
• El sistema operativo limita el resultado. umask() solo puede eliminar bits. No puede otorgar el bit de ejecución a un archivo normal, ya que el modo base para archivos ya es 0666.
• Olvidar el cero inicial. umask(22) y umask(022) significan cosas distintas — el primero es decimal, el segundo es octal.

Funciones relacionadas

• chmod() — cambia los permisos en un archivo o directorio existente.
• fileperms() — lee los bits de permisos actuales de un archivo.
• mkdir() — crea un directorio (su argumento de modo también es filtrado por la umask).
• fopen() — abre o crea un archivo.

Conclusión

La función umask() controla qué bits de permiso se eliminan de los archivos y directorios recién creados. Recuerda que funciona eliminando bits (base & ~mask), se aplica a todo el proceso y solo afecta a las nuevas creaciones. Cuando la cambies dentro de una función, guarda y restaura el valor anterior para evitar sorpresas en el código posterior.

Práctica