SafeStream: Seguridad para los archivos
***************************************

.[perex]
Nette SafeStream garantiza que cada lectura y escritura en un archivo está aislada. Esto significa que ningún subproceso comenzará a leer un archivo que aún no esté completamente escrito, o que varios subprocesos no sobrescribirán el mismo archivo.

Instalación:

```shell
composer require nette/safe-stream
```


¿Para qué sirve? .[#toc-what-is-it-good-for]
--------------------------------------------

¿Para qué sirven realmente las operaciones aisladas? Comencemos con un ejemplo simple que escribe repetidamente en un archivo y luego lee la misma cadena de él:

```php
$s = str_repeat('Cadena larga', 10000);

$counter = 1000;
while ($counter--) {
	file_put_contents('fichero', $s); // escribirlo
	$readed = file_get_contents('fichero'); // leerlo
	if ($s !== $readed) { // comprobarlo
		echo '¡las cadenas son diferentes!
	}
}
```

Puede parecer que `echo 'strings differ!'` no puede ocurrir nunca. Lo cierto es lo contrario. Intente ejecutar este script en dos pestañas del navegador al mismo tiempo. El error se producirá casi inmediatamente.

Una de las pestañas leerá el archivo en un momento en que la otra no ha tenido oportunidad de escribirlo todo, por lo que el contenido no estará completo.

Por lo tanto, el código no es seguro si se ejecuta varias veces al mismo tiempo (es decir, en varios hilos). Lo cual no es raro en Internet, a menudo un servidor está respondiendo a un gran número de usuarios a la vez. Así que es muy importante asegurarse de que su aplicación funciona de forma fiable incluso cuando se ejecuta en múltiples hilos (thread-safe). De lo contrario, se perderán datos y se producirán errores difíciles de detectar.

Pero como puede ver, las funciones nativas de lectura y escritura de archivos de PHP no son aisladas y atómicas.


¿Cómo usar SafeStream? .[#toc-how-to-use-safestream]
----------------------------------------------------

SafeStream crea un protocolo seguro para leer y escribir archivos de forma aislada utilizando funciones estándar de PHP. Todo lo que necesitas hacer es especificar `nette.safe://` antes del nombre del archivo:

```php
file_put_contents('nette.safe://file', $s);
$s = file_get_contents('nette.safe://file');
```

SafeStream asegura que sólo un hilo puede escribir en el archivo a la vez. Los demás subprocesos esperan en la cola. Si ningún hilo está escribiendo, cualquier número de hilos puede leer el archivo en paralelo.

Todas las funciones comunes de PHP pueden ser usadas con el protocolo, por ejemplo:

```php
// 'r' significa abrir sólo lectura
$handle = fopen('nette.safe://file.txt', 'r');

$ini = parse_ini_file('nette.safe://translations.neon');
```

{{leftbar: nette:@menu-topics}}