PHP fopen(): abrir, ler e escrever arquivos (modos)

fopen('data.txt', 'r') abre um arquivo e retorna um handle, um recurso de stream que as outras funções de arquivo recebem como primeiro argumento. Leia com fgets() (uma linha) ou fread() (uma quantidade de bytes), escreva com fwrite() e feche com fclose(). O segundo argumento é o modo: 'r' para ler, 'w' para escrever, 'a' para acrescentar.

<?php
$fh = fopen('fruits.txt', 'w');          // create or empty the file
fwrite($fh, "apple\n");
fwrite($fh, "banana\n");
fwrite($fh, "cherry\n");
fclose($fh);

$fh = fopen('fruits.txt', 'r');
if ($fh === false) {
    exit("Cannot open fruits.txt\n");
}

while (($line = fgets($fh)) !== false) {
    echo 'Got: ', rtrim($line), "\n";
}
fclose($fh);

Saída:

Got: apple
Got: banana
Got: cherry

O fopen() retorna false quando não consegue abrir o arquivo (ele não existe no modo r, falta uma pasta, não há permissão), e o PHP imprime um aviso como:

Warning: fopen(missing.txt): Failed to open stream: No such file or directory in /home/index.php on line 2

Então verifique o false antes de usar o handle. Para ler ou escrever um arquivo pequeno inteiro numa chamada, file_get_contents() e file_put_contents() são mais curtos; o fopen() é para arquivos que você lê aos poucos ou mantém abertos.

Modos do fopen

Duas linhas surpreendem. r+ escreve por cima dos bytes existentes no lugar, sem inserir, e a+ sempre escreve no fim, mesmo depois de você mover o ponteiro com fseek() (movê-lo só afeta as leituras):

<?php
file_put_contents('letters.txt', "abc\n");

$fh = fopen('letters.txt', 'r+');
fwrite($fh, 'X');                  // overwrites the "a"
fclose($fh);
echo file_get_contents('letters.txt');

$fh = fopen('letters.txt', 'a+');
fseek($fh, 0);                     // back to the start...
fwrite($fh, "end\n");              // ...but the write still goes to the end
rewind($fh);
echo fgets($fh);                   // reads do start at the beginning
fclose($fh);
echo file_get_contents('letters.txt');

Saída:

Xbc
Xbc
Xbc
end

No Windows você pode ver 'rb' ou 'wb': a flag b significa binário e impede o Windows de traduzir os fins de linha. Ela não faz nada no Linux e no macOS, então adicioná-la é inofensivo e portável.

Ler um arquivo linha por linha com fgets()

O fgets() retorna a próxima linha incluindo o \n, e false no fim do arquivo. Como só uma linha fica na memória por vez, este loop lida com um arquivo de log de qualquer tamanho, e você pode parar cedo com break:

<?php
file_put_contents('app.log', <<<LOG
2026-03-14 09:00:01 INFO  server started
2026-03-14 09:00:05 ERROR database timeout
2026-03-14 09:01:12 INFO  request /home
2026-03-14 09:02:40 ERROR disk full
2026-03-14 09:03:00 INFO  request /about
LOG);

$fh = fopen('app.log', 'r');
$number = 0;
$errors = [];

while (($line = fgets($fh)) !== false) {
    $number++;
    if (str_contains($line, 'ERROR')) {
        $errors[] = "line $number: " . trim(substr($line, 26));
    }
}
fclose($fh);

echo count($errors), " errors in $number lines\n";
echo implode("\n", $errors), "\n";

Saída:

2 errors in 5 lines
line 2: database timeout
line 4: disk full

Compare com false usando !==, não com um simples while ($line = fgets($fh)): uma linha contendo só "0" sem quebra de linha (a última linha de um arquivo pode ser assim) é falsa e encerraria o loop antes da hora.

Escrever e acrescentar com fwrite()

O fwrite() escreve uma string na posição atual e retorna o número de bytes escritos, ou false em caso de falha. O fputs() é a mesma função com outro nome. Abra com 'a' para acrescentar ao fim de um arquivo sem mexer no que está lá:

<?php
$fh = fopen('visits.log', 'a');
foreach (['/home', '/about', '/contact'] as $page) {
    $bytes = fwrite($fh, "visit $page" . PHP_EOL);
    echo "wrote $bytes bytes\n";
}
fclose($fh);

$fh = fopen('visits.log', 'a');      // open again: the old lines stay
fwrite($fh, 'visit /home' . PHP_EOL);
fclose($fh);

echo file_get_contents('visits.log');

Saída:

wrote 12 bytes
wrote 13 bytes
wrote 15 bytes
visit /home
visit /about
visit /contact
visit /home

PHP_EOL é o fim de linha do sistema em que o PHP roda (\n no Linux e no macOS, \r\n no Windows). Para arquivos que outros programas leem, escolha um explicitamente, normalmente "\n".

Ler e escrever arquivos CSV com fgetcsv() e fputcsv()

O fputcsv() escreve um array como uma linha CSV e coloca entre aspas os campos que contêm vírgulas, aspas ou quebras de linha. O fgetcsv() lê uma linha de volta como array. Passe explicitamente o separador, o delimitador de texto e um caractere de escape vazio: isso dá CSV padrão, e o PHP 8.4 imprime um aviso de depreciação quando o argumento de escape é omitido.

<?php
$rows = [
    ['name', 'city', 'note'],
    ['Ada', 'London', 'likes "math", a lot'],
    ['Linus', 'Helsinki', 'kernel'],
];

$fh = fopen('people.csv', 'w');
foreach ($rows as $row) {
    fputcsv($fh, $row, ',', '"', '');
}
fclose($fh);
echo file_get_contents('people.csv'), "\n";

// Read it back, using the first row as keys
$fh = fopen('people.csv', 'r');
$header = fgetcsv($fh, null, ',', '"', '');
while (($fields = fgetcsv($fh, null, ',', '"', '')) !== false) {
    $person = array_combine($header, $fields);
    echo "{$person['name']} lives in {$person['city']}: {$person['note']}\n";
}
fclose($fh);

Saída:

name,city,note
Ada,London,"likes ""math"", a lot"
Linus,Helsinki,kernel

Ada lives in London: likes "math", a lot
Linus lives in Helsinki: kernel

Dividir linhas com explode(',', $line) quebra assim que um campo contém uma vírgula; o fgetcsv() trata as aspas para você. Para um arquivo separado por ponto e vírgula (comum em exportações do Excel na Europa), passe ';' como separador.

Mover-se num arquivo com fseek(), ftell() e rewind()

Um arquivo aberto tem uma posição. Leituras e escritas começam ali e a movem para a frente. O ftell() diz onde ela está, o fseek() a move para um offset em bytes, e o rewind() volta ao início. Com w+ você pode escrever um arquivo e lê-lo de volta pelo mesmo handle:

<?php
$fh = fopen('message.txt', 'w+');
fwrite($fh, 'hello world');
echo ftell($fh), "\n";             // after the last byte written

fseek($fh, 6);
echo fread($fh, 5), "\n";          // 5 bytes from offset 6

rewind($fh);
echo stream_get_contents($fh), "\n";  // everything from the position to the end
fclose($fh);

Saída:

11
world
hello world

Travar um arquivo com flock()

Duas requisições que leem um contador, somam um e o escrevem de volta ao mesmo tempo podem as duas ler 41 e as duas escrever 42. O flock() com LOCK_EX faz a segunda esperar até a primeira liberar o lock. O modo c+ é o certo aqui: ele cria o arquivo se necessário e, ao contrário do w+, não o esvazia antes de você ter o lock.

<?php
function increment(string $path): int
{
    $fh = fopen($path, 'c+');
    flock($fh, LOCK_EX);               // wait for exclusive access

    $count = (int) stream_get_contents($fh);
    $count++;

    ftruncate($fh, 0);                 // empty the file
    rewind($fh);
    fwrite($fh, (string) $count);
    fflush($fh);

    flock($fh, LOCK_UN);
    fclose($fh);
    return $count;
}

for ($i = 0; $i < 3; $i++) {
    echo 'Visitor number ', increment('counter.txt'), "\n";
}

Saída:

Visitor number 1
Visitor number 2
Visitor number 3

Os locks são consultivos: só impedem outro código que também chama flock(). Para acrescentar uma linha, file_put_contents($path, $line, FILE_APPEND | LOCK_EX) faz o mesmo numa chamada.

Erro comum: while (!feof($fh))

Muitos tutoriais antigos fazem o loop com feof(). Ele só retorna true depois que uma leitura já chegou ao fim, então o loop roda uma vez a mais do que há linhas e o último fgets() retorna false:

<?php
file_put_contents('abc.txt', "a\nb\nc\n");

$fh = fopen('abc.txt', 'r');
$rounds = 0;
while (!feof($fh)) {
    $line = fgets($fh);
    $rounds++;
    var_dump($line);
}
fclose($fh);
echo "$rounds rounds for 3 lines\n";

Saída:

string(2) "a
"
string(2) "b
"
string(2) "c
"
bool(false)
4 rounds for 3 lines

Esse false extra vira uma linha vazia num relatório ou um elemento vazio num array. Faça o loop na própria leitura, while (($line = fgets($fh)) !== false), como todos os outros exemplos desta página.