umask()

Introduzione

In PHP, la funzione umask() imposta i permessi predefiniti per i file e le directory appena creati. È uno strumento utile per gestire l'accesso ai file nei tuoi script. In questo articolo, tratteremo tutto ciò che devi sapere su umask(), inclusa la sua sintassi, i parametri e gli esempi pratici.

Comprendere la funzione umask()

La umask (user file-creation mode mask) è un insieme di bit di permesso che il sistema operativo rimuove dai permessi predefiniti ogni volta che un processo crea un file o una directory. La funzione umask() legge o modifica quella maschera per il processo PHP corrente.

• Accetta un parametro opzionale $mask. Se chiamata senza argomenti, restituisce la maschera corrente senza modificare nulla.
• Quando viene fornita una maschera, essa diventa la nuova maschera e la funzione restituisce il valore della maschera precedente.
• La maschera si applica all'intero processo PHP, non solo allo script corrente — quindi modificarla può influire sulle operazioni sui file successive nella stessa richiesta.

PHP parte dai permessi base del sistema — tipicamente 0666 per i file (lettura + scrittura, nessuna esecuzione) e 0777 per le directory — e calcola i permessi finali con un AND bit a bit contro la maschera invertita:

final = base & ~mask

Come funziona il calcolo della maschera

La maschera azzera i bit che contiene. Ogni cifra ottale corrisponde a proprietario, gruppo e altri, e ogni cifra è la somma di lettura (4), scrittura (2) ed esecuzione (1).

Con umask(022):

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

Il 2 nelle posizioni di gruppo e altri rimuove il bit di scrittura, quindi gruppo e altri possono leggere ma non scrivere. Una umask(077) più restrittiva azzererebbe tutti i permessi di gruppo/altri, producendo 0600 per i file e 0700 per le directory — file accessibili solo dal proprietario.

Sintassi della funzione umask()

La sintassi della funzione umask() è la seguente:

umask($mask);

Qui, $mask è la nuova maschera. Deve essere specificata in notazione ottale, quindi scrivila sempre con uno zero iniziale (es. 022). Scrivere 22 verrebbe interpretato come il valore decimale 22, non la maschera ottale che intendevi.

Esempi di utilizzo di umask()

Esempio 1: Impostare i permessi predefiniti per i nuovi file

<?php

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

Output:

File permissions: 644

Questo imposta la maschera a 022, poi crea example.txt. Il permesso base del file 0666 meno i bit di scrittura mascherati dà 0644. La chiamata a fileperms() legge i permessi effettivi, e & 0777 rimuove i bit del tipo di file in modo che decoct() stampi solo la parte di accesso.

Esempio 2: Leggere e ripristinare la maschera corrente

Poiché la maschera influisce sull'intero processo, una funzione ben scritta dovrebbe ripristinarla al termine. Chiamare umask() senza argomenti restituisce il valore corrente senza modificarlo.

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

Output:

Dir permissions: 700
Restored mask: 22

Qui umask(077) azzera ogni bit di gruppo e altri, quindi la nuova directory ottiene 0777 & ~077 = 0700 — accessibile solo dal proprietario. Salvare la maschera precedente in $old e passarla di nuovo a umask() lascia il processo nello stato in cui si trovava all'inizio.

Errori comuni

• umask() è a livello di processo. In un contesto a lunga esecuzione (worker FPM, daemon CLI) la chiamata umask() di uno script si propaga alle richieste successive sullo stesso worker. Ripristina sempre il valore precedente come nell'Esempio 2.
• Influisce solo sulla creazione. I file esistenti non vengono modificati; usa chmod() per alterare i permessi in un secondo momento.
• Il sistema operativo limita il risultato. umask() può solo rimuovere bit. Non può concedere il bit di esecuzione a un file ordinario, poiché la modalità base per i file è già 0666.
• Dimenticare lo zero iniziale. umask(22) e umask(022) significano cose diverse — il primo è decimale, il secondo è ottale.

Funzioni correlate

• chmod() — modifica i permessi su un file o una directory esistente.
• fileperms() — legge i bit di permesso correnti di un file.
• mkdir() — crea una directory (anche il suo argomento mode è filtrato dalla umask).
• fopen() — apre o crea un file.

Conclusione

La funzione umask() controlla quali bit di permesso vengono rimossi dai file e dalle directory appena creati. Ricorda che funziona rimuovendo bit (base & ~mask), si applica a livello di processo e influisce solo sulle nuove creazioni. Quando la modifichi all'interno di una funzione, salva e ripristina il valore precedente per evitare sorprese nel codice successivo.

Pratica