Instalación

Rapira se distribuye como el binario rapira con libphp al lado: ese es el intérprete de PHP que el servidor carga en su propio proceso. En el artefacto no hay nada más — ni el comando php, ni php-fpm, ni un directorio de ini. No hace falta instalar PHP en la máquina para que Rapira funcione.

¿Qué es libphp y por qué no es «PHP a secas»?

De un mismo código fuente de PHP salen varias interfaces hacia el motor, llamadas SAPI. El motor es siempre el mismo —Zend con sus extensiones—; lo que cambia es la envoltura y quién lleva las riendas del programa:

SAPI	Qué produce	Quién manda
CLI	el comando php	PHP: arranca, ejecuta un script y termina.
FPM	php-fpm	PHP: escucha en el socket y mantiene un pool de workers.
embed	libphp.so	El programa anfitrión: llama al intérprete como a cualquier biblioteca.

Rapira lleva la compilación embed porque quien conduce la petición es el servidor, no PHP. El comando php es otra SAPI para otra tarea, así que ningún artefacto lo incluye.

¿Por qué libphp no se toma del sistema?

Hace falta un PHP compilado con --enable-embed=shared: solo esa compilación produce libphp.so. Las distribuciones casi nunca la empaquetan, y donde sí lo hacen —php-embedded en Fedora y RHEL, php-embed en Arch, libphpX.Y-embed de deb.sury.org en Debian y Ubuntu— la versión menor y el conjunto de extensiones vienen dados; el php de Homebrew ni siquiera trae la SAPI embed. Por eso cada versión de Rapira compila libphp a partir del código fuente oficial de PHP y la coloca junto al binario.

¿Qué significa que «PHP se ejecuta dentro del proceso de Rapira»?

Al arrancar, libphp se carga en el espacio de direcciones del proceso rapira, así que llamar a PHP es una llamada a función en la misma memoria: sin socket, sin FastCGI y sin serializar la petición ni la respuesta. Eso describe cómo se ejecuta el código: como archivo, la biblioteca sigue siendo independiente y vive junto al binario, y por eso el binario no puede salir de su directorio sin ella (consulta Tarballs, en Linux y macOS).

Elegir la versión de PHP

Cada descarga lleva php8.4 o php8.5 en el nombre: esa es la versión de PHP con cuyo código se compiló la libphp que va dentro. Elige la versión menor sobre la que corre tu aplicación y quédate con 8.5 salvo que algo de tu stack exija 8.4.

El PHP que ya tengas en la máquina —el php del sistema, un pool de php-fpm, una compilación de Homebrew— Rapira ni lo usa ni lo toca. Ningún artefacto trae el comando php, así que Composer, bin/console y artisan siguen funcionando con tu propio PHP CLI.

¿Por qué cada versión de PHP tiene su propia compilación de Rapira?

La libphp del artefacto no es una dependencia intercambiable, sino parte de la compilación: el binario rapira está enlazado con una biblioteca concreta, y su ABI cambia de una versión menor de PHP a la siguiente. Por eso una compilación de Rapira funciona con exactamente una rama de PHP, y la versión va en el nombre del archivo. A cambio no hay paso previo de «instala PHP», ni un php-config al que apuntar, ni una versión que mantener sincronizada.

¿Cómo paso de 8.4 a 8.5?

Instala el paquete de la otra versión y el gestor de paquetes hace el cambio por ti. rapira-php8.4 y rapira-php8.5 ocupan exactamente las mismas rutas, así que ambos declaran provides, conflicts y replaces (obsoletes en rpm) sobre un paquete virtual rapira: nunca conviven, el segundo sustituye al primero. Los tarballs sí pueden convivir: cada uno se descomprime en su propio directorio, de modo que un árbol 8.4 y otro 8.5 pueden estar uno al lado del otro y ejecutarse desde rutas distintas.

Artefactos de la versión

Todo está en la página de releases de GitHub. La página de descargas elige el artefacto para tu plataforma —sistema, arquitectura, versión de PHP, formato de paquete— y muestra su SHA-256; cada artefacto php8.5 tiene su gemelo php8.4.

En Linux, coge un paquete si quieres que los archivos queden donde tu distribución los espera y que apt o dnf instalen las bibliotecas compartidas que PHP necesita; coge un tarball si el servidor tiene que caber en un único directorio autocontenido: una imagen de contenedor, un artefacto de despliegue, una máquina donde no tienes root.

En ambos casos, comprueba el archivo contra rapira-v0.6.0-SHA256SUMS.txt antes de instalar; los comandos están en Comprobar las sumas de verificación.

¿Por qué comprobar la suma antes de instalar?

.deb y .rpm ejecutan sus scripts de instalación como root, así que un archivo manipulado consigue root antes incluso de que arranques el servidor. La comprobación es un solo comando y elimina ese riesgo.

Debian y Ubuntu

Descarga el .deb e instálalo con apt, indicando la ruta:

curl -LO https://github.com/rapira-rs/rapira/releases/download/v0.6.0/rapira-php8.5_0.6.0-1_amd64.deb
sudo apt install ./rapira-php8.5_0.6.0-1_amd64.deb
rapira --version

El paquete instala el servidor y nada más: ni unidad de servicio, ni archivo de configuración, ni directorio de ini. Ejecutar Rapira bajo systemd es un paso aparte, descrito en En producción.

Los paquetes se compilan contra glibc 2.34, así que los sistemas más antiguos donde se instalan son Debian 12 y Ubuntu 22.04. Cualquier cosa más reciente funciona.

¿Para qué sirve el ./ delante del nombre del archivo?

Ese ./ inicial es lo que le dice a apt que se trata de un archivo local y no de un nombre de paquete que deba buscar en los repositorios.

¿Qué archivos acaban en el sistema?

Cuatro: el binario /usr/bin/rapira, el intérprete /usr/lib/rapira/libphp.so y, además, la licencia y el README en /usr/share/doc/rapira/. El paquete no cambia nada más.

RHEL, Rocky y Fedora

Lo mismo, con dnf:

curl -LO https://github.com/rapira-rs/rapira/releases/download/v0.6.0/rapira-php8.5-0.6.0-1.x86_64.rpm
sudo dnf install ./rapira-php8.5-0.6.0-1.x86_64.rpm
rapira --version

El mismo suelo de glibc 2.34 marca el mínimo: RHEL 9 y sus recompilaciones —Rocky 9, AlmaLinux 9— más cualquier Fedora actual.

Tarballs, en Linux y macOS

El tarball se descomprime en un único directorio con el servidor entero:

rapira-v0.6.0-php8.5-linux-x86_64/
├── bin/rapira
├── lib/rapira/libphp.so
├── share/php/PHP_VERSION.txt
├── README.md
└── LICENSE

Mueve el directorio a donde vaya a quedarse y añade el binario al PATH mediante un enlace simbólico:

Linux

curl -LO https://github.com/rapira-rs/rapira/releases/download/v0.6.0/rapira-v0.6.0-php8.5-linux-x86_64.tar.gz
tar xzf rapira-v0.6.0-php8.5-linux-x86_64.tar.gz
sudo mv rapira-v0.6.0-php8.5-linux-x86_64 /opt/rapira
sudo ln -s /opt/rapira/bin/rapira /usr/local/bin/rapira
rapira --version

macOS

curl -LO https://github.com/rapira-rs/rapira/releases/download/v0.6.0/rapira-v0.6.0-php8.5-macos-aarch64.tar.gz
tar xzf rapira-v0.6.0-php8.5-macos-aarch64.tar.gz
sudo mv rapira-v0.6.0-php8.5-macos-aarch64 /opt/rapira
sudo ln -s /opt/rapira/bin/rapira /usr/local/bin/rapira
rapira --version

El binario busca su intérprete junto a sí mismo, así que el directorio solo se puede mover entero: cp bin/rapira /usr/local/bin/ rompe el arranque. Para el PATH, usa un enlace simbólico como en los comandos de arriba.

¿Por qué funciona el enlace simbólico y no una copia del binario?

La ruta al intérprete va grabada en el binario como rpath relativo —$ORIGIN/../lib/rapira en Linux y @loader_path/../lib/rapira en macOS—, y se resuelve desde donde el binario está realmente. Junto a /usr/local/bin no hay ningún lib/rapira, así que una copia no encuentra el intérprete. El enlace simbólico lo resuelve el cargador antes de expandir el rpath, de modo que el enlace puede estar en cualquier parte mientras el árbol real permanece intacto.

¿Qué bibliotecas del sistema necesita el tarball?

En macOS, lib/rapira contiene libphp.dylib junto con todas las bibliotecas no propias del sistema de las que depende, así que el árbol es autocontenido. En Linux solo se incluye libphp.so, y las bibliotecas habituales del sistema —OpenSSL 3, libcurl, libxml2, SQLite, Oniguruma, zlib— tienen que estar presentes. En una distribución normal ya lo están; son exactamente las que el deb y el rpm declaran como dependencias, junto con glibc y libgcc.

Comprobar las sumas de verificación

Cada release trae un único archivo de sumas para todos sus artefactos, así que al comprobar hay que seleccionar solo los que has descargado. En Linux lo hace la opción --ignore-missing; en macOS, grep le pasa a shasum la única línea que necesita:

Linux

curl -LO https://github.com/rapira-rs/rapira/releases/download/v0.6.0/rapira-v0.6.0-SHA256SUMS.txt
sha256sum -c --ignore-missing rapira-v0.6.0-SHA256SUMS.txt

macOS

curl -LO https://github.com/rapira-rs/rapira/releases/download/v0.6.0/rapira-v0.6.0-SHA256SUMS.txt
grep rapira-v0.6.0-php8.5-macos-aarch64.tar.gz rapira-v0.6.0-SHA256SUMS.txt | shasum -a 256 -c

La compilación de libphp

libphp se compila con --disable-all y luego se vuelve a activar un conjunto fijo de extensiones:

• Base del runtime: session, filter, mbstring, iconv, ctype, tokenizer, fileinfo, phar.
• OPcache y PCRE con JIT activado.
• Red y compresión: openssl, curl, zlib.
• XML: libxml, dom, xml, simplexml, xmlreader, xmlwriter.
• Bases de datos: PDO con pdo_sqlite, y el propio sqlite3.
• Todo lo que PHP compila siempre: Core, standard, SPL, date, json, hash, random, Reflection.

Lo que no lleva: pdo_mysql, pgsql, redis, apcu, imagick y demás. Si tu aplicación necesita una de esas extensiones, compila libphp con ella y compila Rapira contra esa biblioteca; Compilar desde el código explica cómo.

Cada release toma la última versión de parche de la rama que compila. En el tarball la versión exacta está en share/php/PHP_VERSION.txt, y en un servidor en marcha la informan PHP_VERSION y phpinfo().

¿Por qué PHP_SAPI devuelve fastcgi en PHP 8.4?

En PHP 8.4, OPcache solo arranca para una lista fija de nombres de SAPI, y un nombre fuera de esa lista significa quedarse sin caché de opcodes compartida; por eso ahí la SAPI se registra como fastcgi. PHP 8.5 eliminó la lista, así que PHP_SAPI y php_sapi_name() devuelven rapira. La línea Server API de phpinfo() muestra Rapira en ambos casos. El código que se ramifica según PHP_SAPI tiene que contemplar los dos valores.

php.ini

Ni los paquetes ni los tarballs incluyen un php.ini, y Rapira tampoco lo crea, así que una instalación intacta funciona con los valores por defecto de PHP. Apunta PHPRC a un archivo real o al directorio donde buscarlo:

PHPRC=/etc/rapira/php.ini rapira serve --config /etc/rapira/rapira.toml

¿Dónde busca PHP el php.ini por su cuenta?

Como siempre: primero mira PHPRC, luego el directorio de trabajo actual y por último la ruta grabada en la compilación, que apunta dentro del directorio donde se compiló PHP y, por tanto, no lleva a ninguna parte en tu máquina.

¿Por qué el archivo se llama php.ini y no php-rapira.ini?

PHP busca primero php-<nombre-de-sapi>.ini y solo después el php.ini normal, y el nombre de la SAPI depende de la versión: fastcgi en 8.4 y rapira en 8.5. Un php.ini normal sirve para las dos.

Distribución

Las compilaciones se publican en GitHub Releases y en ningún otro sitio. Todavía no hay repositorio para apt ni para yum, así que actualizar consiste en descargar el nuevo artefacto e instalarlo sobre el anterior, no en ejecutar apt upgrade. El paquete sustituye al instalado en su sitio; con el tarball, descomprime el nuevo directorio junto al viejo y cambia el enlace simbólico: el árbol anterior sigue donde estaba y volver atrás es un solo comando.

La compilación de macOS es solo para Apple Silicon, apunta a macOS 14 o superior y va firmada ad hoc: sin Developer ID y sin notarización, así que puede que macOS te pida confirmar la primera ejecución. No hay compilación para Intel. Las compilaciones para Windows se publican aparte, en rapira-rs/rapira-windows, y están pensadas solo para desarrollo local: en producción, Rapira funciona en Linux o macOS.

Inicio rápido explica cómo atender la primera petición cuando ya tienes el binario en su sitio.