Saltar al contenido principal

Errores comunes al instalar

Instalar el framework por primera vez es donde suelen aparecer problemas. Aquí los más comunes.

"No puedo conectar a la base de datos"​

En api/config.php verifica:

  • Nombre de la base de datos: coincide con la que creaste en phpMyAdmin.
  • Usuario y contraseña de MySQL: en XAMPP suele ser root sin contraseña.
  • Host: localhost para instalaciones locales; en producción puede ser una IP o subdominio distinto.

Prueba conectar manualmente:

mysql -u tu_usuario -p tu_base_de_datos

Si eso falla, el problema es de MySQL, no del framework.

"Composer no encontrado"​

Composer es necesario para instalar dependencias PHP.

Instalación:

  • Mac/Linux: curl -sS https://getcomposer.org/installer | php y mover el binario a /usr/local/bin/composer.
  • Windows: descarga el instalador desde getcomposer.org.

Verifica: composer --version.

"Cannot open file .htaccess" o error 404 al entrar al CMS​

Apache necesita mod_rewrite habilitado.

En Ubuntu/Debian:

sudo a2enmod rewrite
sudo systemctl restart apache2

En XAMPP: edita httpd.conf, descomenta la línea LoadModule rewrite_module modules/mod_rewrite.so y reinicia.

"Permission denied" al escribir archivos​

El servidor web no tiene permisos para escribir en las carpetas donde el framework guarda archivos subidos, páginas generadas o logs.

Solución simple: ejecuta sudo ./setup.sh — ajusta todo.

Manual:

chmod -R 775 cms/views/assets/files/
chmod -R 775 web/pages/
chmod -R 775 logs/
chmod -R 775 api/tmp/
chmod -R 775 packages/

# En Linux con Apache como www-data:
chown -R www-data:www-data cms/views/assets/files/ web/pages/ logs/ api/tmp/ packages/

"The URL you requested was not found" en /cms/​

  • Verifica que apache/nginx sirva desde la carpeta correcta. La raíz debe ser la carpeta del framework, no una carpeta superior.
  • Verifica que exista el archivo cms/index.php.
  • Que Apache tenga AllowOverride All para que los .htaccess funcionen.

Instalador visual pide datos pero no avanza​

  • Verifica que la conexión a la base de datos esté OK (paso 4).
  • Revisa el archivo logs/ — puede haber un error PHP que el instalador silenció.
  • Verifica que la base de datos esté vacía al iniciar el instalador (o al menos que no tenga tablas conflictivas).

"Table already exists" durante la instalación​

Estás intentando instalar en una base de datos que ya tiene tablas del framework (quizás de un intento anterior fallido). Opciones:

  • Vaciar la BD desde phpMyAdmin (drop de todas las tablas) y reinstalar.
  • Usar una BD nueva.

PHP versión incorrecta​

El framework requiere PHP 7.4 o superior. Verifica: php -v.

Si tienes múltiples versiones instaladas, asegúrate de que Apache use la correcta (a veces php --version muestra 8.x pero Apache usa 5.6).

Extensiones PHP faltantes​

Necesarias:

  • pdo y pdo_mysql (conexión a la base de datos).
  • json (viene por defecto en PHP 8+).
  • curl (llamadas HTTP).
  • openssl (JWT, encriptación).
  • mbstring (manejo de strings multibyte).
  • gd o imagick (procesamiento de imágenes).

Verifica: php -m.

Si falta alguna, instálala:

  • Ubuntu: sudo apt install php-mysql php-curl php-mbstring php-gd
  • CentOS: sudo yum install php-mysqlnd php-curl php-mbstring php-gd

setup.sh falla con "Permission denied"​

Ejecútalo con sudo:

sudo ./setup.sh

Si el archivo no es ejecutable:

chmod +x setup.sh
sudo ./setup.sh

Después de instalar, veo "Trying to access array offset on value of type null"​

Suele ser un config.php incompleto o mal formateado. Copia de nuevo desde config.example.php y rellena los valores requeridos.

¿Qué sigue?​