fopen() conecta um recurso nomeado, especificado em filename para um stream. Se filename está na forma "protocolo://...", é assumido que seja uma URL e o PHP irá procurar por um manipulador de protocolo (também conhecido como wrapper) conforme o prefixo. Se nenhum wrapper para o protocolo estiver registrado, o PHP irá emitir um alerta para ajudá-lo a rastrear problemas potenciais em seu script, presumindo que filename é um nome de arquivo comum.
Se o PHP decidir que filename se refere a um arquivo local, então ele tentará abrir o stream para aquele arquivo. Esse arquivo precisa ser acessível pelo PHP, então você precisa certificar-se que as permissões de acesso que garantam esse acesso. Se você está com safe mode ativado ou open_basedir, essas restrições serão aplicadas.
Se o PHP decidir que filename se refere a um protocolo registrado, e que o protocolo está registrado como um URL de rede, o PHP irá verificar se allow_url_fopen está ativado. Se ele estiver desligado, o PHP irá emitir um alerta e a chamada a fopen irá falhar.
Nota: A lista de protocolos registrados pode ser encontrada em Apêndice L. Alguns protocolos (também conhecidos como wrappers) suportam opções de context e/ou php.ini. Veja na página específica do protocolo em uso para uma lista de opções possíveis. (por exemplo, o valor php.ini user_agent utilizado pelo wrapper http) Para uma descrição de contexts e o parâmetro zcontext, veja Referência CXX, Stream Functions.
O parâmetro mode configura o tipo de acesso que você precisa no stream. Pode ser um dos seguintes:
Tabela 1. Lista dos possíveis modos de fopen() para o parâmetro mode
mode | Descrição |
---|---|
'r' | Abre somente leitura; coloca o ponteiro do arquico no começo do arquivo. |
'r+' | Abre para leitura e escrita; coloca o ponteiro do arquivo no começo do arquivo. |
'w' | Abre para escrita somente; coloca o ponteiro do arquivo no começo do arquivo e diminui (trunca) o tamanho do arquivo para zero. Se o arquivo não existe, tenta criá-lo. |
'w+' | Abre o arquivo para leitura e escrita; coloca o ponteiro do arquivo no começo e diminui (trunca) o tamanho do arquivo para zero. Se o arquivo não existe, tenta criá-lo. |
'a' | Abre para escrita somente; coloca o ponteiro do arquivo no final. Se o arquivo não existe, tenta criá-lo. |
'a+' | Abre o arquivo para leitura e escrita; coloca o ponteiro do arquivo no final. Se o arquivo não existe, tenta criá-lo. |
'x' | Cria e abre o arquivo para escrita somente; coloca o ponteiro no início do arquivo. Se o arquivo já existe, a chamada a fopen() irá falhar, retornando FALSE e gerando um erro nível E_WARNING. Se o arquivo não existe, tenta criá-lo. Isto é o equivalente a informar as flags O_EXCL|O_CREAT numa chamada a open(2). Esta opção é suportada no PHP 4.3.2 e posteriores, e somente funciona em arquivos locais. |
'x+' | Cria e abre um arquivo para escrita e leitura; coloca o ponteiro do arquivo no início. Se o arquivo já existe, a chamada a fopen() irá falhar, retornando FALSE e gerando um erro nível E_WARNING. Se o arquivo não existe, tenta criá-lo. Isto é o equivalente a informar as flags O_EXCL|O_CREAT numa chamada a open(2). Esta opção é suportada no PHP 4.3.2 e posteriores, e somente funciona em arquivos locais. |
Nota: Sistemas operacionais diferentes tem convenções de delimitação de linhas diferentes. Quando você escreve num arquivo e deseja inserir uma quebra de linha, você precisa utilizar o(s) caractere(s) de fim de linha adequado(s) em seu sistema operacional. Sistemas baseados no Unix utilizam \n como final de linha, sistemas baseados no Windows usam \r\n e sistemas baseados no Macintosh usam \r.
Se escrever caracteres de fim de linha inadequados em seus arquivos, eles deverão "parecer engraçados" quando você os abrir em outras aplicações.
O Windows oferece uma flag de tradução do modo texto ('t') que traduz, transparentemente, \n para \r\n quando trabalhando no arquivo. Em contraste, você também pode utilizar 'b' para forçar o modo binário, que não irá traduzir o arquivo. Para usar essas flags, informe ou 'b' ou 't' como o último caracter no parâmetro mode.
O modo do sistema de tradução default depende da versao da SAPI sob o qual você está usando o PHP, então é encorajado a sempre utilizar a flag apropriada por razões de portabilidade. Você deve usar o modo 't' se estiver trabalhando em arquivos texto simples e utilizar \n para delimitar as linhas em seu script, de forma que você pode esperar que eles sejam lidos em outras aplicações como o Notepad. Você deve usar 'b' em todos os outros casos.
Se você não especificar a flag 'b' quando trabalhando com arquivos binários, você pode experimentar problemas estranhos com seus dados, incluindo arquivos de imagens danificados e problemas estranhos com os caracteres \r\n.
Para portabilidade, é estremamente recomendado que você sempre utilize a flag 'b' quando abrindo arquivos com fopen().
Novamente, por portabilidade, é estremamente recomendável que você re-escreva seu código nas situações em que o modo 't' deva ser utilizado para corrigir os fim de linha, onde o modo 'b' não deva ser utilizado.
A partir do PHP 4.3.2, o modo padrão é configurado para binário em todas as plataformas que distinguem entre modo texto e binário. Se você está tendo problemas em seus scripts depois de um upgrade, tente acrescentar a flag't' como um paliativo até que você tenha tornado seus scripts portáveis como mencionado acima.
Você pode usar o terceiro pparâmetro opcional como "1", se você quiser procurar pelo arquivo no include_path também.
Se a abertura falhar, a função retorna FALSE e um erro nível E_WARNING é gerado. Você pode utilizar @ para suprimir esse alerta.
Se você está tendo problemas com a leitura e gravação para arquivos e você está usando a versão de modulo de servidor do PHP, lembre-se de que os arquivos e diretórios que você está usando precisam ser acessíveis ao processo do servidor HTTP.
Na plataforma Windows, tenha cuidado para usar uma segunda barra invertida (escape) nos caminhos de arquivos, ou usar a barra normal.
Veja também: Apêndice L, fclose(), fgets(), fread(), fwrite(), fsockopen(), file(), file_exists(), is_readable(), stream_set_timeout() e popen().