Tienes un proyecto PHP que clonaste de un repositorio, abres la terminal, escribes composer install y la respuesta es un seco «comando no encontrado». O peor: Composer existe, pero se queja de que tu PHP es demasiado viejo o de que falta la extensión mbstring. Casi todos los problemas del primer día con PHP vienen de una instalación a medias. Esta guía te lleva por los tres sistemas operativos más comunes y termina con una lista de comprobación para saber que el entorno quedó bien.
Antes de instalar: qué versión de PHP elegir
PHP sigue una política de soporte publicada en php.net: cada rama recibe dos años de soporte activo (correcciones de errores y de seguridad) y luego dos años más solo con parches de seguridad. Según la tabla oficial de versiones soportadas, a finales de 2026 la situación es esta:
| Rama | Lanzamiento | Soporte activo hasta | Solo seguridad hasta |
|---|---|---|---|
| PHP 8.2 | diciembre de 2022 | 31/12/2024 | 31/12/2026 |
| PHP 8.3 | noviembre de 2023 | 31/12/2025 | 31/12/2027 |
| PHP 8.4 | noviembre de 2024 | 31/12/2026 | 31/12/2028 |
| PHP 8.5 | noviembre de 2025 | 31/12/2027 | 31/12/2029 |
Para un proyecto nuevo, lo razonable es usar PHP 8.4 o 8.5. Si vas a trabajar con un proyecto existente, revisa su composer.json: la clave require.php indica qué versiones acepta (por ejemplo "php": "^8.2"). Instalar justo esa rama en tu máquina evita sorpresas cuando el código llegue al servidor. Como estas fechas cambian con cada lanzamiento, confirma la tabla en la página «Supported Versions» de php.net antes de decidir.
PHP y Composer no son lo mismo
PHP es el intérprete: lee tus archivos .php y los ejecuta. Composer es el gestor de dependencias: descarga librerías de terceros y genera el cargador automático de clases. Composer está escrito en PHP, así que siempre se instala PHP primero. Si inviertes el orden, el instalador de Composer no encontrará con qué ejecutarse.
Instalación en Windows
En Windows tienes dos caminos: instalar PHP «suelto» o usar un paquete que lo incluye todo (XAMPP, Laragon o Laravel Herd, por ejemplo). Los paquetes son cómodos, pero instalar PHP a mano te enseña dónde vive cada pieza y te da control sobre la versión. Este es el método manual.
Paso 1: descargar el binario correcto
Entra en la sección de descargas para Windows de php.net (windows.php.net) y elige la rama que decidiste usar. Verás varias variantes del archivo ZIP:
- x64 Non Thread Safe (NTS): la indicada para usar PHP desde la terminal, con el servidor integrado o detrás de un servidor web vía FastCGI. Es la opción para la mayoría.
- x64 Thread Safe (TS): solo la necesitas si vas a cargar PHP como módulo dentro de Apache.
Los binarios oficiales dependen del paquete redistribuible de Visual C++ de Microsoft. Si al ejecutar php.exe aparece un error sobre un archivo VCRUNTIME faltante, instala la versión más reciente de ese redistribuible (x64) desde la web de Microsoft.
Paso 2: descomprimir y añadir al PATH
- Descomprime el ZIP en una ruta corta y sin espacios, por ejemplo
C:\php. - Abre «Editar las variables de entorno del sistema», entra en «Variables de entorno» y edita la variable
Pathde tu usuario. - Añade una línea con
C:\phpy acepta. - Cierra todas las terminales abiertas y abre una nueva. Las terminales que ya estaban abiertas no ven el cambio.
Paso 3: crear el php.ini
El ZIP trae dos plantillas: php.ini-development y php.ini-production. Para tu equipo de trabajo copia la primera y renómbrala a php.ini dentro de C:\php. Luego ábrela con un editor de texto y ajusta lo siguiente:
; Ruta de las extensiones (en Windows, relativa a la carpeta de PHP)
extension_dir = "ext"
; Extensiones que casi cualquier proyecto moderno necesita.
; Basta con quitar el punto y coma del inicio de cada línea.
extension=curl
extension=fileinfo
extension=mbstring
extension=openssl
extension=pdo_mysql
extension=zip
; Zona horaria por defecto: evita avisos y fechas corridas
date.timezone = America/BogotaCambia la zona horaria por la tuya (America/Mexico_City, America/Lima, America/Argentina/Buenos_Aires, etc.). La extensión openssl es imprescindible: sin ella Composer no puede descargar paquetes por HTTPS.
Paso 4: instalar Composer
Descarga Composer-Setup.exe desde getcomposer.org. El asistente te pide la ruta de php.exe; si el PATH quedó bien, la detecta solo. Al terminar, abre una terminal nueva y escribe composer --version.
Instalación en macOS
macOS ya no incluye PHP de fábrica, así que lo habitual es usar Homebrew, el gestor de paquetes más extendido en ese sistema. Si no lo tienes, instálalo siguiendo las instrucciones de su web oficial (brew.sh).
# Instala la versión más reciente de PHP que ofrece Homebrew
brew install php
# O bien una rama concreta, si tu proyecto la exige
brew install php@8.3
# Las ramas con versión no se enlazan solas; para usarla por defecto:
brew link --overwrite --force php@8.3
# Composer también está disponible como fórmula
brew install composerPara saber qué archivo php.ini está usando tu instalación, ejecuta php --ini. Homebrew lo guarda dentro de su propio directorio, no en /etc. Si además quieres PHP-FPM corriendo en segundo plano (por ejemplo, para usarlo con Nginx), brew services start php lo deja como servicio.
Una alternativa en macOS es Laravel Herd, que instala PHP, Composer y un servidor local con interfaz gráfica. Funciona bien aunque no uses Laravel, pero si prefieres entender cada pieza, Homebrew es más transparente.
Instalación en Linux
En Linux, PHP viene en los repositorios de cada distribución. El matiz importante es que cada distribución congela una versión: Ubuntu 24.04 LTS, por ejemplo, trae PHP 8.3. Si te sirve esa versión, el gestor de paquetes es el camino más limpio.
Ubuntu y Debian
# Actualiza el índice de paquetes
sudo apt update
# PHP de línea de comandos + extensiones frecuentes + unzip (Composer lo usa)
sudo apt install php-cli php-mbstring php-xml php-curl php-zip php-mysql unzip
# Comprueba la versión instalada
php -vSi necesitas una rama más nueva de la que trae tu distribución, el recurso más usado es el repositorio mantenido por Ondřej Surý (el PPA ondrej/php en Ubuntu y su equivalente para Debian). Permite tener varias ramas instaladas a la vez y elegir con update-alternatives. Úsalo sabiendo que es un repositorio externo a tu distribución.
Fedora y derivadas
# Fedora suele traer una rama reciente de PHP y empaqueta Composer
sudo dnf install php-cli php-mbstring php-xml php-pdo php-mysqlnd composerComposer con el instalador oficial
Los repositorios de algunas distribuciones traen versiones de Composer con cierto retraso. Si quieres la última, usa el instalador oficial. La página de descarga de getcomposer.org muestra cuatro comandos; el segundo compara una huella SHA-384 del instalador, y esa huella cambia cada vez que publican uno nuevo. Por eso no la copies de tutoriales: tómala siempre de la página oficial. El resto del proceso es así:
# Después de ejecutar los comandos de getcomposer.org/download
# tendrás un archivo composer.phar en la carpeta actual.
# Muévelo a una carpeta del PATH para usarlo como "composer"
sudo mv composer.phar /usr/local/bin/composer
# Comprueba que responde
composer --versionLista de comprobación final
Con PHP y Composer instalados, conviene confirmar que todo encaja antes de abrir un proyecto real. Ejecuta estos comandos y revisa el resultado de cada uno:
| Comando | Qué deberías ver |
|---|---|
php -v | La rama que elegiste (8.4.x, 8.5.x…) |
php --ini | La ruta de un php.ini cargado, no «(none)» |
php -m | Una lista que incluya curl, mbstring, openssl, pdo_mysql |
composer --version | Composer versión 2.x |
composer diagnose | Todas las pruebas en «OK» |
Si php --ini dice que no hay archivo cargado, PHP está funcionando con valores por defecto y tus cambios no tienen efecto. En Windows suele significar que el php.ini está en otra carpeta o que se quedó con el nombre php.ini-development.
Prueba rápida con el servidor integrado
PHP trae un servidor web pensado para desarrollo. Crea una carpeta con un archivo index.php como este:
<?php
// index.php: muestra la versión y si las extensiones clave están activas
declare(strict_types=1);
$extensiones = ['mbstring', 'pdo_mysql', 'openssl', 'curl'];
echo '<h1>PHP ' . PHP_VERSION . '</h1>';
foreach ($extensiones as $ext) {
// extension_loaded() devuelve true si la extensión está cargada
$estado = extension_loaded($ext) ? 'activa' : 'FALTA';
echo "<p>{$ext}: {$estado}</p>";
}Desde esa carpeta ejecuta php -S localhost:8000 y abre http://localhost:8000 en el navegador. Ese servidor no está pensado para producción: es de un solo proceso y no tiene las protecciones de Apache o Nginx, pero para aprender y probar es perfecto.
Errores frecuentes durante la instalación
- «php no se reconoce como un comando interno o externo». El PATH no incluye la carpeta de PHP o la terminal se abrió antes del cambio. Cierra y vuelve a abrir.
- Composer dice «The openssl extension is required». Falta activar
extension=opensslenphp.ini, o estás editando unphp.inique PHP no está leyendo. Revisa conphp --ini. - «Your requirements could not be resolved» por la versión de PHP. El proyecto pide una rama distinta a la que tienes. Instala la rama requerida o, en Linux y macOS, ten varias y cambia entre ellas.
- En Linux funciona la terminal pero no la web. El paquete
php-clisolo instala la línea de comandos. Para servir páginas necesitasphp-fpm(con Nginx) o el módulo de Apache, y cada uno tiene su propiophp.ini. - Cambié php.ini y no pasa nada. En la terminal el cambio aplica en la siguiente ejecución, pero PHP-FPM o Apache deben reiniciarse para leerlo.
Con el entorno verificado, el siguiente paso natural es crear tu primer proyecto con composer init, definir un espacio de nombres en la sección autoload y empezar a escribir clases sin preocuparte por los require manuales.
1 Comment