(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
file_get_contents — Lee todo un fichero en una cadena
$filename
,$use_include_path
= false
,$context
= null
,$offset
= 0,$length
= null
Similar a la función file(), excepto que
file_get_contents() devuelve el fichero
filename
en una cadena, comenzando
desde la posición offset
y hasta
length
bytes.
En caso de error, file_get_contents() devuelve
false
.
file_get_contents() es el método recomendado para leer el contenido de un fichero en una chaîne de caractères. Utilizará un buffer en memoria si este mecanismo es soportado por el sistema, con el fin de mejorar el rendimiento.
Nota:
Si se abre una URI con caracteres especiales, como espacios, es necesario codificar esta URI con la función urlencode().
filename
Nombre del fichero a leer.
use_include_path
Nota:
La constante
FILE_USE_INCLUDE_PATH
puede ser utilizada para activar la búsqueda en el ruta de inclusión. Esto no es posible si strict typing está activado, ya queFILE_USE_INCLUDE_PATH
es un int. Utilicetrue
en su lugar.
context
Un recurso de contexto válido, creado con la función
stream_context_create(). Si no es necesario
utilizar un contexto específico, este parámetro puede ser omitido
asignándole el valor null
.
offset
La posición desde la cual se comienza a leer en el flujo original. Una posición negativa cuenta desde el final del flujo.
El desplazamiento en el fichero (offset
) no es
soportado en ficheros remotos. Si se intenta desplazarse en un fichero
que no es local puede funcionar en pequeños desplazamientos, pero el
comportamiento puede no ser el esperado ya que el proceso utiliza el
flujo del buffer.
length
El tamaño máximo de datos a leer. El comportamiento por defecto es leer hasta el final del fichero. Este parámetro se aplica al flujo procesado por los filtros.
Devuelve los datos leídos o false
en caso de error.
Esta función puede
devolver el valor booleano false
, pero también puede devolver un valor no booleano que se
evalúa como false
. Por favor lea la sección sobre Booleanos para más
información. Use el operador
=== para comprobar el valor devuelto por esta
función.
Genera una advertencia de tipo E_WARNING
si,
filename
no puede ser encontrado, si el
parámetro length
es menor que cero,
o si el desplazamiento a la posición offset
especificado en el flujo falla.
Cuando file_get_contents() es llamado sobre un directorio,
se genera un error de nivel E_WARNING
en Windows,
y a partir de PHP 7.4 en otros sistemas operativos también.
Versión | Descripción |
---|---|
8.0.0 |
length ahora es nullable.
|
7.1.0 |
Se añade soporte para posiciones offset negativas.
|
Ejemplo #1 Lee y muestra el código HTML de un sitio web
<?php
$homepage = file_get_contents('http://www.example.com/');
echo $homepage;
?>
Ejemplo #2 Busca un fichero en el include_path
<?php
// Si el tipado estricto está activado c.à.d. declare(strict_types=1);
$file = file_get_contents('./people.txt', true);
// De lo contrario
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
?>
Ejemplo #3 Lee una sección de un fichero
<?php
// Lee 14 caracteres a partir del 21º carácter
$section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
var_dump($section);
?>
El resultado del ejemplo sería algo similar a:
string(14) "lle Bjori Ro"
Ejemplo #4 Uso de contextos de flujo
<?php
// Creación de un flujo
$opts = [
'http'=> [
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar\r\n",
]
];
$context = stream_context_create($opts);
// Acceso a un fichero HTTP con los encabezados HTTP indicados arriba
$file = file_get_contents('http://www.example.com/', false, $context);
?>
Nota: Esta función es segura binariamente.
Se puede emplear un URL como nombre de fichero con esta función si las envolturas de fopen han sido activadas. Véase fopen() para más información de cómo especificar el nombre de fichero. Véanse las Protocolos y Envolturas soportados; continen enlaces con información sobre las diferentes capacidades que tienen las envolturas, notas sobre su empleo, e información de cualquier variable predefinida que podría proporcionarse.
Cuando se usa SSL,
Microsoft IIS violará el protocolo, cerrando la conexión sin mandar un
indicador close_notify
. PHP avisará de esto con este mensaje "SSL:
Fatal Protocol Error", cuando llegue al final de los datos. Una
solución a este problema es bajar el nivel de aviso de errores del sistema para
que no incluya advertencias.
PHP pueden detectar servidores IIS con este problema cuando se
abre un flujo usando https://
y suprime
la advertencia. Si usáis la función fsockopen() para crear un
socket ssl://
, tendréis que suprimir la advertencia
explicitamente.