PHP Stream

PHP Streams

Um stream em PHP é uma forma genérica de ler ou gravar em um fluxo de dados, independentemente de onde esses dados estejam. Um arquivo no disco, um bloco de memória, um socket de rede e o corpo de uma resposta HTTP são coisas muito diferentes, mas o PHP permite que você os manipule com o mesmo conjunto de funções. Essa uniformidade é exatamente o ponto: assim que você sabe como ler um arquivo com fopen()/fgets(), já sabe como ler uma página web ou um buffer de memória.

Esta página aborda o que são streams, as funções que os controlam, os wrappers que identificam a origem de um stream e como trabalhar com eles de forma segura.

Qual problema os streams resolvem?

Sem streams, você precisaria de uma API diferente para cada fonte de dados — uma para arquivos, outra para HTTP, outra para sockets. Os streams fornecem uma única abstração:

• Wrapper — um prefixo como file://, php://, http:// ou php://memory que diz ao PHP que tipo de recurso você está acessando.
• Handle de recurso — o valor retornado por fopen(); você o passa para todas as outras funções de stream.
• Filtros e contextos — camadas opcionais que transformam os dados (ex.: gzip) ou configuram a conexão (ex.: cabeçalhos HTTP, timeouts).

Por causa desse design, você pode trocar um caminho local por uma URL remota e a maior parte do seu código permanece igual.

Funções principais de stream

Estas funções formam a base da API de Streams:

O $mode controla o acesso: 'r' (leitura), 'w' (escrita, com truncamento), 'a' (acréscimo) e as variantes com '+' para leitura e escrita.

Para leituras e gravações únicas, geralmente não é preciso gerenciar um handle — os helpers de alto nível file_get_contents() e file_put_contents() abrem, transferem e fecham um stream em uma única chamada.

Wrappers e tipos de stream

O wrapper no início da string de destino determina o tipo de stream:

• Streams de arquivo (file://, ou simplesmente um caminho simples) — leem e gravam dados no sistema de arquivos. Veja Manipulação de Arquivos em PHP e Abrir e Ler um Arquivo.
• Streams de memória (php://memory, php://temp) — um buffer de leitura/escrita que fica na RAM; ótimo para construir dados em testes sem tocar o disco.
• Streams de I/O (php://stdin, php://stdout, php://input) — entrada/saída padrão e o corpo bruto da requisição.
• Streams de rede/socket (tcp://, ssl://) — leem e gravam em uma conexão de rede.
• Streams HTTP/FTP (http://, https://, ftp://) — buscam documentos remotos como se fossem arquivos (requer que allow_url_fopen esteja habilitado).

Lendo um arquivo linha por linha

Este exemplo mínimo e autocontido grava um pequeno arquivo, o lê de volta por um stream linha a linha e depois faz a limpeza:

<?php

$path = sys_get_temp_dir() . '/stream-demo.txt';

// Write three lines using the high-level helper.
file_put_contents($path, "alpha\nbeta\ngamma\n");

// Read them back through a stream handle.
$handle = fopen($path, 'r');
if ($handle === false) {
    exit("Could not open the stream.\n");
}

while (!feof($handle)) {
    $line = fgets($handle);
    if ($line !== false) {
        echo "Line: " . trim($line) . PHP_EOL;
    }
}

fclose($handle);
unlink($path);

Saída:

Line: alpha
Line: beta
Line: gamma

Abrimos o arquivo em modo de leitura, percorremos em loop até que feof() indique o fim e lemos cada linha com fgets(). Sempre verifique se fopen() não retornou false antes de usar o handle e chame fclose() ao terminar.

Usando um stream de memória

Streams de memória se comportam como arquivos, mas nunca acessam o disco — úteis para montar saídas ou para testes unitários:

<?php

$handle = fopen('php://memory', 'r+');

fwrite($handle, "buffered data");

// Rewind to the start before reading what we wrote.
rewind($handle);

echo fread($handle, 1024);

fclose($handle);

Saída:

buffered data

Após gravar, você deve usar rewind() para voltar o ponteiro ao início antes de ler, pois a posição interna fica no final do que acabou de ser gravado.

Lendo um stream remoto

Como HTTP é apenas mais um wrapper, o mesmo loop funciona com uma URL quando allow_url_fopen está habilitado:

<?php

$handle = fopen('https://www.example.com', 'r');
if ($handle === false) {
    exit("Failed to open the remote stream.\n");
}

while (!feof($handle)) {
    echo fgets($handle);
}

fclose($handle);

Este exemplo requer acesso à rede e a configuração allow_url_fopen ativada, portanto não funcionará em um sandbox offline. Para aplicações reais, um cliente HTTP dedicado como cURL oferece melhor controle sobre cabeçalhos, timeouts e erros.

Tratamento de erros

As funções de stream sinalizam falha retornando false em vez de lançar exceções, então proteja cada chamada:

• Verifique o valor de retorno de fopen() antes de ler ou gravar.
• Envolva operações arriscadas em try/catch se você converter avisos em exceções — veja Exceções em PHP.
• Sempre use fclose() nos handles que você abre para liberar recursos.

Conclusão

Os streams fornecem ao PHP uma interface única e consistente para todo tipo de fluxo de dados — arquivos, buffers de memória, sockets e respostas HTTP. Aprenda o pequeno conjunto de funções principais (fopen, fread/fgets, fwrite, feof, fclose), entenda os wrappers como file:// e php://memory e utilize os helpers de alto nível file_get_contents()/file_put_contents() para casos simples. Para aprofundar, explore criação e gravação de arquivos e o tratamento de erros adequado.

Prática