file()

O que é a Função file()?

A função file() lê um arquivo inteiro em um array, onde cada elemento do array corresponde a uma linha do arquivo. É a forma mais rápida de obter as linhas de um arquivo em um array PHP com uma única chamada — você não precisa abrir um handle, fazer um loop com fgets() nem fechar nada depois.

Use file() quando quiser processar um arquivo linha por linha: contando linhas, filtrando registros, lendo uma lista de valores ou analisando um log pequeno. Para obter uma string única em vez de um array, use file_get_contents(); para escrever em um arquivo com uma única chamada, use file_put_contents().

Sintaxe

file(string $filename, int $flags = 0, ?resource $context = null): array|false

Valor de retorno: um array de linhas ou false em caso de falha (por exemplo, se o arquivo não existir). Por padrão, cada linha mantém sua quebra de linha final (\n).

O Parâmetro flags

$flags permite controlar como as linhas são lidas. Combine-os com |:

<?php
// Lines without trailing "\n", and no blank lines.
$lines = file('myfile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);

Como Usar a Função file()

Um exemplo completo que cria um arquivo, lê seu conteúdo com file() e itera sobre as linhas:

<?php

// Create a small file to read.
file_put_contents('myfile.txt', "First line\nSecond line\nThird line\n");

$lines = file('myfile.txt');

foreach ($lines as $lineNumber => $line) {
    echo "Line #{$lineNumber}: " . trim($line) . "\n";
}

Isso imprime:

Line #0: First line
Line #1: Second line
Line #2: Third line

As chaves do array são números de linha com base zero e os valores são o conteúdo das linhas. Usamos trim() aqui para remover a quebra de linha final que file() mantém por padrão — passar FILE_IGNORE_NEW_LINES faria o mesmo no momento da leitura.

Contando Linhas em um Arquivo

Como file() retorna um array, count() fornece diretamente a contagem de linhas:

<?php

file_put_contents('myfile.txt', "alpha\nbeta\ngamma\n");

$lines = file('myfile.txt', FILE_IGNORE_NEW_LINES);

echo "The file has " . count($lines) . " lines.\n";  // The file has 3 lines.

Tratamento de Erros

Quando o arquivo não pode ser lido, file() retorna false e emite um aviso. Sempre verifique o resultado antes de iterar:

<?php

$lines = @file('does-not-exist.txt');

if ($lines === false) {
    echo "Could not read the file.\n";
} else {
    echo "Read " . count($lines) . " lines.\n";
}

O operador @ suprime o aviso interno para que você possa tratar a falha por conta própria.

Pontos de Atenção

• Arquivo inteiro na memória. file() carrega todas as linhas em um array de uma vez. Para arquivos muito grandes, abra um handle com fopen() e leia linha por linha com fgets().
• Quebras de linha finais são mantidas a menos que você passe FILE_IGNORE_NEW_LINES. Isso causa problemas em comparações exatas de string, por exemplo, $lines[0] === 'value' falha quando o elemento é na verdade "value\n".
• Verifique a existência primeiro se quiser evitar avisos: use file_exists() em conjunto ou suprima com @.

Conclusão

A função file() é a maneira mais simples de ler um arquivo em um array de linhas no PHP. Use os flags FILE_IGNORE_NEW_LINES e FILE_SKIP_EMPTY_LINES para obter linhas limpas, sempre proteja-se contra um retorno false e prefira fgets() para arquivos grandes demais para manter na memória.

Prática