Importante (actualización 2024-11): PHP 8.4 separó ext-imap del núcleo. La extensión pasó a PECL y está prácticamente obsoleta -- la biblioteca de C subyacente (libc-client) no se actualiza desde 2018. Si estás empezando un proyecto nuevo o usas PHP 8.4+, salta a ¿Realmente necesitas ext-imap? para ver alternativas modernas. Si usas PHP 8.3 o anterior y necesitas la extensión nativa, esta guía sigue funcionando.
La solución rápida
Si solo quieres los comandos y el porqué te da igual -- aquí está todo en orden. Necesitas tener Homebrew y phpenv ya instalados.
# 1. Install all required libraries
brew install tidy-html5 openssl@3 zlib bzip2 libedit readline \
gettext libiconv libsodium krb5 imap-uw curl
# 2. Set build configuration (add to ~/.zshrc or run before install)
export PHP_BUILD_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl@3) \
--with-zlib=$(brew --prefix zlib) \
--with-bz2=$(brew --prefix bzip2) \
--with-curl \
--with-libedit \
--with-readline=$(brew --prefix readline) \
--with-gettext=$(brew --prefix gettext) \
--with-iconv=$(brew --prefix libiconv) \
--with-sodium=$(brew --prefix libsodium) \
--with-kerberos=$(brew --prefix krb5) \
--with-imap=$(brew --prefix imap-uw) \
--with-imap-ssl=$(brew --prefix openssl@3) \
--with-tidy=$(brew --prefix tidy-html5) \
--enable-mbstring \
--enable-intl"
# 3. Help the compiler find headers
export CPPFLAGS="-I$(brew --prefix openssl@3)/include -I$(brew --prefix imap-uw)/include $CPPFLAGS"
# 4. Build and install
phpenv install 8.3.6
phpenv global 8.3.6
# 5. Verify
php -v
php -m | grep imapSi imap aparece en la salida, ya está. Si no, sigue leyendo.
¿Realmente necesitas ext-imap?
Va en serio. Antes de pelearte con bibliotecas de C y banderas del compilador, plantéate si de verdad necesitas la extensión nativa de IMAP.
PHP 8.4 eliminó ext-imap del núcleo. Pasó a PECL, y la biblioteca de C subyacente (libc-client / UW-IMAP) no recibe una actualización desde 2018. Tiene problemas de seguridad en hilos, le falta soporte para XAUTH y tiene errores con POP. No va a volver.
La alternativa moderna es Webklex/php-imap -- una implementación de IMAP en PHP puro:
composer require webklex/php-imapEso es todo. Sin dependencias de brew, sin banderas del compilador, sin búsquedas de archivos de cabecera. Funciona en PHP 8.0.2+ (incluidos 8.4 y 8.5), admite IMAP IDLE y OAuth, y tiene más de 5 millones de instalaciones en Packagist. También hay una integración con Laravel si ese es tu stack.
Usa ext-imap solo si mantienes un código heredado en PHP 8.3 o anterior que ya depende de las funciones imap_* y todavía no puedes migrar.
Qué hace cada paso
Si la solución rápida funcionó, puedes dejar de leer. Si no -- o si quieres entender qué está pasando -- aquí tienes el desglose.
Las dependencias de brew
brew install tidy-html5 openssl@3 zlib bzip2 libedit readline \
gettext libiconv libsodium krb5 imap-uw curlmacOS incluye algunas de estas, pero phpenv necesita las versiones de Homebrew con las cabeceras y los archivos de pkg-config adecuados. La crítica es imap-uw -- esa es la biblioteca UW-IMAP que proporciona libc-client.
PHP_BUILD_CONFIGURE_OPTS
phpenv usa php-build por debajo, que ejecuta ./configure sobre el código fuente de PHP. La variable PHP_BUILD_CONFIGURE_OPTS pasa las banderas directamente a configure. Cada bandera --with-* le indica a PHP dónde encontrar una biblioteca concreta.
Las más importantes para IMAP:
--with-imap=$(brew --prefix imap-uw)-- apunta a la biblioteca de IMAP--with-imap-ssl=$(brew --prefix openssl@3)-- habilita IMAP sobre SSL--with-kerberos=$(brew --prefix krb5)-- necesaria para la autenticación de IMAP
El arreglo de CPPFLAGS
export CPPFLAGS="-I$(brew --prefix openssl@3)/include -I$(brew --prefix imap-uw)/include $CPPFLAGS"Incluso con las banderas de configure, a veces el preprocesador de C no encuentra los archivos de cabecera. Esto pasa porque macOS no coloca las cabeceras de Homebrew en la ruta de búsqueda por defecto. Las dos cabeceras que fallan con más frecuencia:
openssl/ssl.h-- de OpenSSLimap/imap.h-- de imap-uw
El arreglo de PATH
Si php -v muestra la versión equivocada después de instalar, los shims de phpenv no están en tu PATH (o algo más los está tapando). Añade esto a ~/.zshrc:
export PHPENV_ROOT="$HOME/.phpenv"
if [ -d "${PHPENV_ROOT}" ]; then
export PATH="${PHPENV_ROOT}/shims:${PHPENV_ROOT}/bin:$PATH"
eval "$(phpenv init -)"
fiLuego ejecuta source ~/.zshrc e inténtalo de nuevo.
El error utf8_mime2text
Si ves esto:
configure: error: utf8_mime2text() has new signature, but U8T_CANONICAL is missing.
This should not happen.Tu biblioteca imap-uw está desactualizada o estropeada. Arréglalo con:
brew upgrade imap-uwLuego vuelve a ejecutar la instalación.
El futuro de PHP + IMAP
El final está cantado. ext-imap está obsoleta, la biblioteca de C subyacente está abandonada y PHP 8.4 ya la quitó del núcleo. Si estás leyendo esto porque necesitas IMAP en un proyecto de PHP, empieza a planear tu migración a webklex/php-imap. La extensión nativa tiene los días contados.
Para quienes mantenemos código heredado -- esta guía seguirá funcionando para PHP 8.3 y anteriores. Pero no empieces proyectos nuevos sobre ext-imap. No hay razón para pelearse con la compilación de bibliotecas de C cuando existe una solución en PHP puro.
Referencias
- PHP 8.4: IMAP Extension Unbundled -- Documentación de PHP.Watch sobre la eliminación de ext-imap.
- Webklex/php-imap en GitHub -- Implementación de IMAP en PHP puro (más de 5 millones de instalaciones en Packagist).
- Manual de PHP: extensión IMAP -- Documentación oficial con avisos de obsolescencia.
- shivammathur/extensions: IMAP para PHP 8.3+ -- Tap de Homebrew para extensiones de PHP, incluida IMAP.
Publicaciones relacionadas
- PHP 8.5: un recorrido por las funciones que llegan -- lo que viene a continuación en PHP.
- Guía para desarrolladores: cambios de clases y namespaces en Shopware 6.5/6.6 -- otra guía de migración de PHP para desarrolladores de Shopware.
- Laravel Sail vs Laradock -- cómo elegir la configuración de Docker adecuada para el desarrollo en PHP.
Comentarios