Retorna uma string com até length - 1 bytes lidos do arquivo apontado por handle. A leitura acaba quando length - 1 bytes foram lidos, encontra-se um fim de linha (newline) (que é incluido no valor retornado) ou no fim de arquivo (EOF) (o que acontecer primeiro). Se nenhum length for informado, o default é 1Kb, ou 1024 bytes.
Se um erro ocorrer, retorna FALSE.
Equívocos comuns:
Pessoas acostumadas a semântica do fgets em 'C' devem notar a diferenca em como o fim do arquivo (EOF) é retornado.
O ponteiro para o arquivo deve ser válido e deve apontar para um arquivo aberto com sucesso por fopen(), popen() ou fsockopen().
Um simples exemplo segue:
Nota: O parâmetro length se tornou opcional a partir do PHP 4.2.0, e se omitido, tem default para 1024 bytes para o comprimento da linha. A partir do PHP 4.3, omitindo length fará continuar a leitura a partir do stream até encontrar o fim da linha. Se a maioria das linhas no arquivo forem todar maiores que 8 Kb, haverá mais eficiência de recursos se seus scripts informarem o comprimento máximo das linhas.
Nota: Esta função é binary safe a partir do PHP 4.3. Versões anteriores não são seguras para dados binários.
Nota: Se você está tendo problemas com o PHP no reconhecimento do final de linha quando criando ou lendo arquivos num computador Macintosh, você pode habilitar a opção auto_detect_line_endings.
Veja também fread(), fgetc(), stream_get_line(), fopen(), popen(), fsockopen() e socket_set_timeout().