PHP file_get_contents(): ler um arquivo numa string

file_get_contents('notes.txt') lê o arquivo inteiro e o retorna como uma string. Se o arquivo não puder ser lido, ele retorna false. Para escrever, use file_put_contents('notes.txt', $text), que cria o arquivo ou substitui o que havia nele.

<?php
file_put_contents('notes.txt', "Buy milk\nCall Ada\nWrite docs\n");

$text = file_get_contents('notes.txt');

echo $text;
echo strlen($text), " bytes\n";
echo substr_count($text, "\n"), " lines\n";

Saída:

Buy milk
Call Ada
Write docs
29 bytes
3 lines

O bloco escreve notes.txt primeiro e depois o lê de volta, para ter um arquivo com que trabalhar. Um caminho como 'notes.txt' é relativo ao diretório de trabalho atual; numa aplicação web, monte o caminho a partir da pasta do próprio script com __DIR__ . '/notes.txt'.

Escrever e acrescentar com file_put_contents()

O file_put_contents() retorna o número de bytes escritos, ou false em caso de falha. Por padrão ele sobrescreve o arquivo. A flag FILE_APPEND acrescenta no fim, que é como logs simples funcionam, e LOCK_EX impede que duas requisições escrevam no mesmo momento:

<?php
$bytes = file_put_contents('log.txt', "started\n");
echo "Wrote $bytes bytes\n";

file_put_contents('log.txt', "step 1 done\n", FILE_APPEND | LOCK_EX);
file_put_contents('log.txt', "step 2 done\n", FILE_APPEND | LOCK_EX);
echo file_get_contents('log.txt'), "\n";

file_put_contents('log.txt', "replaced\n");   // no flag: the old content is gone
echo file_get_contents('log.txt'), "\n";

// An array is written with its elements joined, with nothing between them
file_put_contents('list.txt', ['a', 'b', 'c']);
echo file_get_contents('list.txt'), "\n";
echo file_put_contents('list.txt', implode("\n", ['a', 'b', 'c'])), " bytes\n";

Saída:

Wrote 8 bytes
started
step 1 done
step 2 done

replaced

abc
5 bytes

Para guardar um array e recebê-lo de volta como array, escreva-o como JSON com json_encode() e leia com json_decode().

Ler um arquivo linha por linha com file()

O file() lê um arquivo para um array com uma linha por elemento. Cada linha mantém a quebra de linha no fim, a menos que você passe FILE_IGNORE_NEW_LINES, e FILE_SKIP_EMPTY_LINES descarta as linhas em branco (só funciona junto com FILE_IGNORE_NEW_LINES):

<?php
file_put_contents('todo.txt', "Buy milk\nCall Ada\n\nWrite docs\n");

$lines = file('todo.txt');
var_dump($lines[0]);   // the newline is still there

$lines = file('todo.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
foreach ($lines as $i => $line) {
    echo $i + 1, ". $line\n";
}

echo count($lines), " tasks\n";

Saída:

string(9) "Buy milk
"
1. Buy milk
2. Call Ada
3. Write docs
3 tasks

file() e file_get_contents() carregam o arquivo inteiro na memória. Isso não é problema para arquivos de configuração e logs de alguns megabytes. Para um arquivo de centenas de megabytes, leia uma linha por vez com fopen() e fgets().

Verificar se um arquivo existe antes de lê-lo

Quando o arquivo não existe, o file_get_contents() retorna false e o PHP imprime um aviso:

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

Verifique antes com is_file() (um arquivo que existe e não é diretório) ou file_exists() (um arquivo ou um diretório), e sempre compare o resultado com === false, porque um arquivo vazio retorna "", que também é falso:

<?php
file_put_contents('empty.txt', '');

foreach (['empty.txt', 'missing.txt', '.'] as $path) {
    echo str_pad($path, 12);
    echo file_exists($path) ? 'exists ' : 'missing ';
    echo is_file($path) ? 'file ' : '';
    echo is_dir($path) ? 'directory ' : '';
    echo "\n";
}

$path = 'missing.txt';
if (!is_file($path) || !is_readable($path)) {
    echo "Cannot read $path, using defaults\n";
} else {
    $text = file_get_contents($path);
}

$text = file_get_contents('empty.txt');
var_dump($text === false, $text == false);   // not a failure, just empty
echo filesize('empty.txt'), " bytes\n";

Saída:

empty.txt   exists file 
missing.txt missing 
.           exists directory 
Cannot read missing.txt, using defaults
bool(false)
bool(true)
0 bytes

Não esconda o aviso com @file_get_contents(). Verificar antes, ou tratar o false, mantém o erro visível quando outra coisa der errado.

Ler parte de um arquivo

O quarto e o quinto argumentos são o offset em bytes onde começar e o número de bytes a ler. Um offset negativo conta a partir do fim do arquivo. Argumentos nomeados deixam você pular os dois argumentos do meio:

<?php
file_put_contents('data.txt', "HEADER\nline 2\nline 3\nlast line\n");

echo file_get_contents('data.txt', false, null, 0, 6), "\n";   // first 6 bytes
echo file_get_contents('data.txt', offset: 7, length: 6), "\n";
echo file_get_contents('data.txt', offset: -10);                 // last 10 bytes

Saída:

HEADER
line 2
last line

Offsets contam bytes, não caracteres. Em UTF-8, um caractere japonês tem 3 bytes, então um offset no meio de um o corta ao meio. Para trabalhar com caracteres, leia a string inteira e use mb_substr().

Mostrar um arquivo de texto numa página web

O conteúdo de um arquivo é texto, e texto impresso em HTML precisa ser escapado, senão um < no arquivo vira uma tag. O htmlspecialchars() o escapa e o nl2br() transforma as quebras de linha em tags <br>. Rode e olhe a aba Page:

<?php
file_put_contents('changelog.txt', <<<TXT
v1.2: Fixed <title> encoding
v1.1: Added "export" & "import"
v1.0: First release
TXT);

$text = file_get_contents('changelog.txt');
?>
<h3>Changelog</h3>
<p style="font-family: monospace"><?= nl2br(htmlspecialchars($text)) ?></p>
<p><?= count(file('changelog.txt')) ?> entries, <?= filesize('changelog.txt') ?> bytes</p>

Tire o htmlspecialchars() e rode de novo: a página agora termina em "v1.2: Fixed", porque o navegador lê <title> como uma tag de verdade e engole tudo o que vem depois como título da página. A página sobre htmlspecialchars() explica por que isso importa para tudo o que um usuário pode escrever.

Ler uma URL com file_get_contents()

Com allow_url_fopen habilitado (o padrão no php.ini), o file_get_contents() também lê URLs e retorna o corpo da resposta. Um contexto de stream adiciona um método, cabeçalhos, um corpo e um timeout:

<?php
$html = file_get_contents('https://example.com/');

$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode(['name' => 'Ada']),
        'timeout' => 5,
        'ignore_errors' => true,   // return the body of 4xx/5xx responses too
    ],
]);

$response = file_get_contents('https://api.example.com/users', false, $context);
if ($response === false) {
    // DNS failure, timeout, or a refused connection
}

Para novas tentativas, redirecionamentos com limite e códigos de erro claros, o cURL ou uma biblioteca de cliente HTTP como o Guzzle são a ferramenta melhor.

file_get_contents, file() ou fopen()

As funções de uma chamada abrem, leem ou escrevem e fecham o arquivo para você, então são o padrão certo. Use o fopen() quando o arquivo for grande demais para caber na memória ou você precisar mantê-lo aberto entre operações.