PHP Ler e Escrever Arquivos

Tudo o que um programa guarda em variáveis some quando ele termina. Para lembrar de alguma coisa até a próxima vez (a lista de compras, os recados dos clientes, o registro das vendas do dia), o programa precisa gravar num arquivo. Nesta aula você vai ler e escrever arquivos de texto, criar pastas, listar e apagar arquivos, e entender as mensagens que o PHP mostra quando algo dá errado.

Os exemplos rodam na pasta /home/ana/arq da máquina da Ana. No editor do guia, os arquivos são criados num disco de mentira, na memória do navegador: pode gravar à vontade.

A ideia: um caderno na gaveta

Um arquivo é como um caderno guardado numa gaveta. Para usar, você precisa saber o nome do caderno e em que gaveta (pasta) ele está. Aí pode ler o que está escrito, escrever por cima (apagando o que havia) ou continuar escrevendo na próxima linha em branco. O PHP tem uma função para cada uma dessas ações.

Gravar e ler de uma vez

As duas funções mais usadas fazem tudo numa linha só:

• file_put_contents ("pôr o conteúdo no arquivo"): grava um texto num arquivo. Se o arquivo não existe, ele é criado.
• file_get_contents ("pegar o conteúdo do arquivo"): devolve todo o texto do arquivo, como uma string.

<?php
$bytes = file_put_contents('compras.txt', "arroz\nfeijão\nleite\n");
var_dump($bytes);
echo file_get_contents('compras.txt');

file_put_contents(

A função que grava.

'compras.txt',

1º argumento: o nome do arquivo. Sem pasta na frente, ele fica na pasta atual.

"arroz\nfeijão\nleite\n"

2º argumento: o texto. Cada \n é uma quebra de linha (por isso aspas duplas; veja Strings).

$bytes =

A função devolve quantos bytes gravou (ou false se falhou).

file_get_contents('compras.txt')

Lê o arquivo inteiro e devolve o texto, que o echo mostra.

$ cd arq
$ php escrever.php
int(20)            « 20 bytes gravados
arroz
feijão
leite
$ cat compras.txt  « o arquivo ficou no disco, mesmo depois de o PHP terminar
arroz
feijão
leite

Escrever por cima × acrescentar no fim

Cuidado: por padrão, file_put_contents apaga o que havia no arquivo e grava o texto novo. Para acrescentar no fim, passe a "bandeira" (flag) FILE_APPEND ("anexar ao arquivo") como terceiro argumento:

<?php
file_put_contents('compras.txt', "café\n", FILE_APPEND);
file_put_contents('compras.txt', "açúcar\n", FILE_APPEND);
echo file_get_contents('compras.txt');

$ php acrescentar.php
arroz
feijão
leite
café              « acrescentado
açúcar            « acrescentado

E sem o FILE_APPEND:

<?php
file_put_contents('compras.txt', "pão\n");
echo file_get_contents('compras.txt');

$ php sobrescrever.php
pão               « o resto da lista sumiu: o arquivo foi reescrito do zero

<?php
file_put_contents('compras.txt', "arroz\nfeijão\nleite\n");
file_put_contents('compras.txt', "café\n");
file_put_contents('compras.txt', "açúcar\n");
echo file_get_contents('compras.txt');

<?php
file_put_contents('compras.txt', "arroz\nfeijão\nleite\n");
file_put_contents('compras.txt', "café\n", FILE_APPEND);
file_put_contents('compras.txt', "açúcar\n", FILE_APPEND);
echo file_get_contents('compras.txt');

Ler linha por linha com file()

Muitas vezes você não quer o texto inteiro, e sim cada linha separada, para contar, filtrar ou mostrar numa lista. A função file() lê o arquivo e devolve um array, com uma linha em cada posição:

<?php
file_put_contents('compras.txt', "arroz\nfeijão\n\nleite\n");
$linhas = file('compras.txt');
var_dump($linhas);

$ php linhas.php
array(4) {
  [0]=>
  string(6) "arroz
"                       « a quebra de linha veio junto!
  [1]=>
  string(8) "feijão
"
  [2]=>
  string(1) "
"                       « a linha em branco virou um item
  [3]=>
  string(6) "leite
"
}

Duas surpresas: cada item termina com a quebra de linha ("arroz\n", por isso o string(6)), e a linha vazia também entrou. Quase sempre você quer o contrário, e para isso existem duas bandeiras, que se combinam com |:

$limpas = file('compras.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
var_dump($limpas);
echo "Itens: " . count($limpas) . "\n";

« (continuação da saída de php linhas.php)
array(3) {
  [0]=>
  string(5) "arroz"
  [1]=>
  string(7) "feijão"
  [2]=>
  string(5) "leite"
}
Itens: 3

O | entre elas é o "ou" de bits: um jeito de passar várias bandeiras num argumento só. Você não precisa entender a matemática, só a receita: BANDEIRA_1 | BANDEIRA_2.

O jeito passo a passo: fopen, fgets, fwrite, fclose

file_get_contents e file() carregam o arquivo inteiro na memória. Para arquivos pequenos, perfeito. Para um arquivo de registro com 2 GB, o programa estouraria a memória. O jeito "clássico", herdado da linguagem C, abre o arquivo e lê ou escreve um pedaço por vez:

1. fopen (file open, "abrir arquivo"): abre e devolve um identificador (um "marcador de página" do caderno).
2. fgets (file get string, "pegar uma linha"): lê a próxima linha. Ou fwrite (file write, "escrever"): escreve um texto.
3. fclose (file close, "fechar"): fecha o arquivo e libera o identificador.

<?php
$arquivo = fopen('diario.txt', 'w');
fwrite($arquivo, "16/10: vendi 3 bolos\n");
fwrite($arquivo, "17/10: vendi 5 bolos\n");
fclose($arquivo);

$arquivo = fopen('diario.txt', 'r');
$numero = 1;
while (($linha = fgets($arquivo)) !== false) {
    echo $numero . ": " . $linha;
    $numero++;
}
fclose($arquivo);

$ php fopen.php
1: 16/10: vendi 3 bolos
2: 17/10: vendi 5 bolos
$ cat diario.txt
16/10: vendi 3 bolos
17/10: vendi 5 bolos

Os modos do fopen

O segundo argumento do fopen diz o que você pretende fazer com o arquivo:

O modo 'x' é útil para "crie só se ainda não existir", sem risco de apagar nada:

$ php modos.php      « $f = fopen('compras.txt', 'x'); var_dump($f);

Warning: fopen(compras.txt): Failed to open stream: File exists in /home/ana/arq/modos.php on line 2
bool(false)

Qual usar?

<?php
$arquivo = fopen('diario.txt', 'r');
$numero = 0;
// leia as linhas aqui

fclose($arquivo);

16/10: vendi 3 bolos
17/10: vendi 5 bolos
18/10: vendi 2 tortas

<?php
$arquivo = fopen('diario.txt', 'r');
$numero = 0;
while (($linha = fgets($arquivo)) !== false) {
    $numero++;
    echo $numero . ": " . $linha;
}
fclose($arquivo);
echo "Total: $numero dias\n";

Perguntar antes: existe? é pasta?

Ler um arquivo que não existe dá aviso. Antes, você pode perguntar:

<?php
var_dump(file_exists('compras.txt'));
var_dump(file_exists('receitas.txt'));
var_dump(is_file('compras.txt'));
var_dump(is_dir('compras.txt'));
var_dump(is_dir('/home/ana'));
echo filesize('compras.txt'), " bytes\n";

$ php existe.php
bool(true)       « compras.txt existe
bool(false)      « receitas.txt não existe
bool(true)       « compras.txt é um arquivo comum
bool(false)      « …e não é uma pasta
bool(true)       « /home/ana é uma pasta
21 bytes

Pastas: criar, listar, apagar

A Ana quer guardar cada pedido num arquivo, dentro de uma pasta pedidos:

<?php
if (!is_dir('pedidos')) {
    mkdir('pedidos');
    echo "Pasta criada.\n";
}
file_put_contents('pedidos/001.txt', "2 bolos de cenoura\n");
file_put_contents('pedidos/002.txt', "1 torta de limão\n");
print_r(scandir('pedidos'));

$ php pastas.php
Pasta criada.
Array
(
    [0] => .
    [1] => ..
    [2] => 001.txt
    [3] => 002.txt
)

mkdir('pedidos')

make directory, "criar pasta" (o mesmo nome do comando do terminal).

scandir('pedidos')

scan directory, "varrer a pasta": devolve um array com os nomes, em ordem alfabética.

. e ..

Toda pasta tem essas duas entradas especiais: . é a própria pasta e .. é a pasta de cima. Quase sempre você vai querer tirá-las.

Para listar só os arquivos de verdade, tire o . e o .. com array_diff, ou use glob, que aceita curingas como no terminal:

<?php
foreach (array_diff(scandir('pedidos'), ['.', '..']) as $nome) {
    echo "$nome\n";
}
print_r(glob('pedidos/*.txt'));

$ php glob.php
001.txt
002.txt
Array
(
    [0] => pedidos/001.txt         « glob devolve o caminho junto
    [1] => pedidos/002.txt
)

Pastas dentro de pastas

mkdir só cria uma pasta por vez, e reclama se ela já existir:

<?php
mkdir('pedidos');
mkdir('fotos/2026/outubro');
var_dump(mkdir('fotos/2026/outubro', 0755, true));

$ php mkdir-erro.php

Warning: mkdir(): File exists in /home/ana/arq/mkdir-erro.php on line 2

Warning: mkdir(): No such file or directory in /home/ana/arq/mkdir-erro.php on line 3
bool(true)
$ ls -R fotos
fotos:
2026

fotos/2026:
outubro

fotos/2026/outubro:

A linha 2 falhou porque pedidos já existia (File exists). A linha 3 falhou porque fotos e fotos/2026 não existiam (No such file or directory). A linha 4 funcionou graças ao terceiro argumento, true ("recursivo"), que cria todas as pastas do caminho, como o mkdir -p do terminal. O 0755 é a permissão das pastas novas, no mesmo formato do chmod (o 0 na frente é obrigatório: é um número em octal).

Apagar e mover

<?php
unlink('pedidos/001.txt');
print_r(scandir('pedidos'));
unlink('pedidos/001.txt');

$ php apagar.php
Array
(
    [0] => .
    [1] => ..
    [2] => 002.txt          « o 001.txt sumiu
)

Warning: unlink(pedidos/001.txt): No such file or directory in /home/ana/arq/apagar.php on line 4

unlink ("desvincular") é o nome histórico de "apagar arquivo", vindo do Unix. Para apagar uma pasta, use rmdir, que só funciona com a pasta vazia:

$ php rmdir.php      « rmdir('pedidos'); com o 002.txt ainda lá dentro

Warning: rmdir(pedidos): Directory not empty in /home/ana/arq/rmdir.php on line 2

E para copiar, mover e desmontar caminhos:

<?php
copy('diario.txt', 'diario-backup.txt');
rename('diario-backup.txt', 'pedidos/diario-antigo.txt');
print_r(scandir('pedidos'));
$caminho = '/home/ana/arq/pedidos/002.txt';
echo basename($caminho), "\n";
echo dirname($caminho), "\n";
print_r(pathinfo($caminho));
echo realpath('pedidos/../diario.txt'), "\n";

$ php outros.php
Array
(
    [0] => .
    [1] => ..
    [2] => 002.txt
    [3] => diario-antigo.txt       « copiado e depois movido (rename também move)
)
002.txt                            « basename: só o nome
/home/ana/arq/pedidos              « dirname: só a pasta
Array
(
    [dirname] => /home/ana/arq/pedidos
    [basename] => 002.txt
    [extension] => txt
    [filename] => 002
)
/home/ana/arq/diario.txt           « realpath: o caminho completo, sem ".."

Caminhos: relativos a quê?

Um nome como 'compras.txt' ou 'pedidos/001.txt' é um caminho relativo: o PHP o procura a partir da pasta atual do programa, que é a pasta de onde ele foi chamado, e não a pasta onde o arquivo .php está. Veja:

<?php
echo getcwd(), "\n";
echo __DIR__, "\n";
file_put_contents(__DIR__ . '/registro.txt', "ok\n");
var_dump(file_exists(__DIR__ . '/registro.txt'));

$ cd ~
$ php arq/dir.php
/home/ana             « getcwd(): a pasta atual (de onde a Ana chamou)
/home/ana/arq         « __DIR__: a pasta do arquivo dir.php
bool(true)

Se o programa tivesse gravado só 'registro.txt', o arquivo iria parar em /home/ana, e não ao lado do script. Num site, a "pasta atual" depende do servidor. Por isso, a regra é a mesma da aula include e require: para arquivos que acompanham o seu programa, monte o caminho com __DIR__ . '/nome.txt'.

Um mural de recados (modo web)

Juntando tudo: uma página com um formulário onde os clientes deixam recados, guardados num arquivo de texto, um por linha. Cada vez que alguém envia, a página acrescenta uma linha e mostra todas.

<?php
$arquivo = __DIR__ . '/recados.txt';

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $nome = trim($_POST['nome'] ?? '');
    $recado = trim($_POST['recado'] ?? '');
    if ($nome !== '' && $recado !== '') {
        $linha = str_replace("\n", ' ', "$nome: $recado") . "\n";
        file_put_contents($arquivo, $linha, FILE_APPEND | LOCK_EX);
    }
}

$recados = file_exists($arquivo)
    ? file($arquivo, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES)
    : [];
?>
<h1>Mural de recados da Lojinha</h1>
<form method="post">
  <input name="nome" placeholder="Seu nome">
  <input name="recado" placeholder="Seu recado">
  <button>Enviar</button>
</form>
<ul>
<?php foreach ($recados as $r): ?>
  <li><?= htmlspecialchars($r) ?></li>
<?php endforeach; ?>
</ul>
<p><?= count($recados) ?> recado(s).</p>

A Ana testou com o servidor embutido e o curl, mandando dois recados (o primeiro com HTML de propósito):

$ curl -s -X POST --data "nome=Bia&recado=Adorei o bolo de <b>cenoura</b>!" localhost:8000/
<h1>Mural de recados da Lojinha</h1>
<form method="post">
  <input name="nome" placeholder="Seu nome">
  <input name="recado" placeholder="Seu recado">
  <button>Enviar</button>
</form>
<ul>
  <li>Bia: Adorei o bolo de &lt;b&gt;cenoura&lt;/b&gt;!</li>       « o HTML virou texto inofensivo
</ul>
<p>1 recado(s).</p>
$ curl -s -X POST --data "nome=Caio&recado=Quero encomendar" localhost:8000/ | tail -6
</form>
<ul>
  <li>Bia: Adorei o bolo de &lt;b&gt;cenoura&lt;/b&gt;!</li>
  <li>Caio: Quero encomendar</li>
</ul>
<p>2 recado(s).</p>
$ cat recados.txt
Bia: Adorei o bolo de <b>cenoura</b>!            « no arquivo, o texto fica original
Caio: Quero encomendar

<?php
$arquivo = __DIR__ . '/recados.txt';

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $nome = trim($_POST['nome'] ?? '');
    $recado = trim($_POST['recado'] ?? '');
    if ($nome !== '' && $recado !== '') {
        $linha = str_replace("\n", ' ', "$nome: $recado") . "\n";
        file_put_contents($arquivo, $linha);
    }
}

$recados = [];   // leia as linhas do arquivo aqui
?>
<h1>Mural de recados da Lojinha</h1>
<form method="post">
  <input name="nome" placeholder="Seu nome">
  <input name="recado" placeholder="Seu recado">
  <button>Enviar</button>
</form>
<ul>
<?php foreach ($recados as $r): ?>
  <li><?= htmlspecialchars($r) ?></li>
<?php endforeach; ?>
</ul>
<p><?= count($recados) ?> recado(s).</p>

Ana: Bem-vindos ao mural!

<?php
$arquivo = __DIR__ . '/recados.txt';

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $nome = trim($_POST['nome'] ?? '');
    $recado = trim($_POST['recado'] ?? '');
    if ($nome !== '' && $recado !== '') {
        $linha = str_replace("\n", ' ', "$nome: $recado") . "\n";
        file_put_contents($arquivo, $linha, FILE_APPEND | LOCK_EX);
    }
}

$recados = file_exists($arquivo)
    ? file($arquivo, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES)
    : [];
?>
<h1>Mural de recados da Lojinha</h1>
<form method="post">
  <input name="nome" placeholder="Seu nome">
  <input name="recado" placeholder="Seu recado">
  <button>Enviar</button>
</form>
<ul>
<?php foreach ($recados as $r): ?>
  <li><?= htmlspecialchars($r) ?></li>
<?php endforeach; ?>
</ul>
<p><?= count($recados) ?> recado(s).</p>

Quando dá errado

$ php nao-existe.php     « $texto = file_get_contents('receitas.txt'); var_dump($texto); …

Warning: file_get_contents(receitas.txt): Failed to open stream: No such file or directory in /home/ana/arq/nao-existe.php on line 2
bool(false)

Warning: fopen(receitas.txt): Failed to open stream: No such file or directory in /home/ana/arq/nao-existe.php on line 4
bool(false)

$ php fgets-false.php    « $f = fopen('receitas.txt', 'r'); echo fgets($f);

Warning: fopen(receitas.txt): Failed to open stream: No such file or directory in /home/ana/arq/fgets-false.php on line 2

Fatal error: Uncaught TypeError: fgets(): Argument #1 ($stream) must be of type resource, false given in /home/ana/arq/fgets-false.php:3
Stack trace:
#0 /home/ana/arq/fgets-false.php(3): fgets(false)
#1 {main}
  thrown in /home/ana/arq/fgets-false.php on line 3

$ chmod 444 trancado.txt
$ ls -l trancado.txt
-r--r--r-- 1 ana ana 9 out 16 20:47 trancado.txt
$ php permissao.php      « $ok = file_put_contents('trancado.txt', "novo texto\n"); var_dump($ok);

Warning: file_put_contents(trancado.txt): Failed to open stream: Permission denied in /home/ana/arq/permissao.php on line 2
bool(false)

Warning: mkdir(): File exists in /home/ana/arq/mkdir-erro.php on line 2

Referência

Exercícios

<?php
$pasta = __DIR__ . '/pedidos';

<?php
$pasta = __DIR__ . '/pedidos';
if (!is_dir($pasta)) {
    mkdir($pasta);
}
file_put_contents("$pasta/001.txt", "2 bolos de cenoura\n");
file_put_contents("$pasta/002.txt", "1 torta de limão\n");
file_put_contents("$pasta/003.txt", "12 brigadeiros\n");

$nomes = array_diff(scandir($pasta), ['.', '..']);
foreach ($nomes as $nome) {
    echo "$nome\n";
}
echo count($nomes) . " pedidos\n";

Resumo

• file_put_contents grava (por cima!) e file_get_contents lê o arquivo inteiro. FILE_APPEND acrescenta no fim.
• file() devolve as linhas num array; use FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES.
• Para arquivos grandes: fopen → fgets/fwrite → fclose, com while (($linha = fgets($f)) !== false).
• Pergunte antes com file_exists/is_dir; crie pastas com mkdir (true para o caminho todo), liste com scandir/glob, apague com unlink/rmdir.
• Falhas viram Warning + false: confira o retorno antes de usar.
• Caminhos relativos partem da pasta atual; use __DIR__.
• Texto de visitante gravado em arquivo: escape com htmlspecialchars na hora de mostrar.

Próxima aula: CSV, o formato das planilhas, lido e gravado linha a linha.