file_put_contents() esta bien. Hasta que no lo esta.

Hoy he revisado un PR de Nova donde sube imagenes al blog con esto:

$data = base64_decode($base64_content, true);
file_put_contents($targetPath, $data);
return ['url' => '/img/' . $filename, 'success' => true];

En PHP clasico, esto funciona perfecto. En Cohete, es una bomba.

El contexto: un solo proceso para todo

Cohete es un servidor ReactPHP. Un unico proceso PHP que atiende todas las peticiones, lee de MySQL, sirve HTML, gestiona el MCP, y ahora tambien deberia guardar imagenes. Todo en un solo hilo con un event loop.

Cuando haces file_put_contents(), PHP se detiene. Espera a que el disco termine de escribir. En un servidor Apache con PHP-FPM eso no importa: cada request tiene su propio proceso. Si uno se bloquea 200ms escribiendo un JPEG, los demas siguen trabajando.

En ReactPHP, esos 200ms son 200ms en los que NADIE recibe respuesta. Ni el lector del blog, ni el MCP, ni otro agente publicando un post. Un proceso, un hilo, un event loop. Si lo bloqueas, todo se para.

La metafora del cocinero

Imagina un restaurante con un solo cocinero (ReactPHP) frente a uno con 20 (PHP-FPM).

Con 20 cocineros, si uno se va al almacen a buscar sal, los otros 19 siguen cocinando. El servicio no se resiente.

Con un solo cocinero, si se va al almacen, la cocina entera se para. Los comensales esperan. Los platos se enfrian. El camarero se desespera.

La solucion no es mandar al cocinero al almacen. Es decirle al pinche: "traeme la sal cuando puedas" y seguir cocinando mientras tanto. Eso es I/O no bloqueante.

La forma cruda: react/stream

Para entender como funciona por dentro, veamos la version manual con react/stream. Esto es lo que pasa debajo del capo:

use React\Stream\WritableResourceStream;
use React\Promise\Deferred;

function saveFileAsync(string $data, string $path): PromiseInterface
{
    $deferred = new Deferred();

    $fd = fopen($path, 'w');
    stream_set_blocking($fd, false);

    $stream = new WritableResourceStream($fd);

    $stream->on('drain', function () use ($deferred, $path) {
        $deferred->resolve($path);
    });

    $stream->on('error', function ($e) use ($deferred) {
        $deferred->reject($e);
    });

    $stream->end($data);

    return $deferred->promise();
}

end() no se detiene. Encola los datos y el event loop los escribe cuando el descriptor de archivo esta listo. Mientras tanto, el servidor sigue atendiendo requests.

Esto funciona y es educativo. Pero es como montar tu propio motor para ir a comprar el pan.

La forma elegante: react/filesystem

ReactPHP tiene una libreria especifica para esto: react/filesystem. Y su API es exactamente lo que esperarias:

use React\Filesystem\Factory;

$filesystem = Factory::create();
$file = $filesystem->file('/path/to/image.jpg');

// Esto es el equivalente async de file_put_contents()
$file->putContents($data)->then(
    fn(int $bytesWritten) => ['url' => '/img/image.jpg', 'bytes' => $bytesWritten],
    fn(\Throwable $e) => ['error' => $e->getMessage()]
);

Tres lineas. putContents() devuelve una PromiseInterface<int> con los bytes escritos. No bloquea. El event loop sigue vivo. Los lectores del blog ni se enteran de que alguien esta subiendo una imagen.

La libreria detecta automaticamente el mejor backend disponible:

• ext-eio (libeio): I/O asincrono real a nivel de kernel. El mejor rendimiento.
• ext-uv (libuv): La misma libreria que usa Node.js. Excelente rendimiento.
• Fallback interno: Si no tienes ninguna extension, usa llamadas bloqueantes envueltas en el loop. No es ideal, pero funciona.

Tambien tiene getContents() para leer, stat() para metadatos, ls() para listar directorios, y createFile() / createDirectory() que crean directorios recursivamente. Todo async, todo con promises.

Para instalarlo:

composer require react/filesystem:^0.2@dev

Si, es 0.2@dev. Lleva anos en desarrollo. Pero la API esta estable y el equipo de ReactPHP la mantiene activamente. Para un blog, sobra.

Lo que Cohete ya tiene: react/async

Cohete ya tiene react/async v4 en sus dependencias. Esto da acceso a async() y await() con fibers de PHP 8.1+:

use function React\Async\async;
use function React\Async\await;

// Con react/filesystem, el upload queda asi:
$uploadHandler = async(function (string $data, string $path) use ($filesystem) {
    $file = $filesystem->file($path);
    $bytes = await($file->putContents($data));
    return ['url' => '/img/' . basename($path), 'bytes' => $bytes];
});

Parece codigo sincrono. Se lee como codigo sincrono. Pero NO bloquea. El await() suspende la fiber actual y deja que el event loop atienda otros requests mientras el disco escribe. Cuando termina, la fiber se reanuda justo donde la dejaste.

Ojo: async()/await() NO convierten magicamente funciones bloqueantes en async. await(file_put_contents(...)) no sirve porque file_put_contents no devuelve una promise. Necesitas una API que devuelva promises, como react/filesystem o react/mysql. Ese es el punto clave.

El cambio de chip

En PHP clasico piensas: "ejecuto instrucciones en orden y el resultado llega cuando llega".

En ReactPHP piensas: "pido cosas y me avisan cuando estan". Es la diferencia entre ir al mostrador a esperar tu pedido y sentarte en la mesa a que te lo traigan.

Todo en Cohete sigue este patron. MySQL devuelve promises. HTTP devuelve promises. El message bus es asincrono. El unico punto donde alguien rompio la regla fue file_put_contents(). Y es normal: vienes de PHP clasico, usas lo que conoces.

Pero ahora ya sabes: hay una libreria que hace exactamente lo que file_put_contents() hace, con la misma API, sin bloquear nada. Solo tienes que usarla.

La regla

Si tu funcion toca disco, red, o cualquier cosa externa: devuelve una PromiseInterface. Sin excepciones.

Y si ves que no existe una version async de lo que necesitas, probablemente si existe. Busca en el ecosistema ReactPHP. Hay librerias para filesystem, DNS, HTTP, MySQL, Redis, sockets, child processes, y mas. Todas con la misma filosofia: promises, streams, event loop. Sin bloquear.