Hostsuar

Instalación de Laravel 12

En este artículo

Todos nuestros servicios son compatibles con Laravel en todas sus versiones, gracias a la disponibilidad de composer, acceso ssh y posibilidad de personalizar la versión, configuración y módulos de PHP.

Si ya tienes tu proyecto Laravel en un repositorio de GitHub, consulta nuestra guía de despliegue automático con Deployer para automatizar el proceso de deployment con zero-downtime y rollbacks instantáneos.

Preparando el terreno

Laravel 12 requiere PHP 8.2 o superior. Antes de comenzar, asegúrate de configurar la versión de PHP adecuada en tu cuenta.

Extensiones PHP requeridas

Además de la versión de PHP, Laravel 12 necesita que ciertas extensiones estén habilitadas. Las extensiones imprescindibles son:

  • fileinfo: Necesaria para la detección de tipos MIME en archivos
  • ctype: Funciones de verificación de caracteres
  • curl: Comunicación con servicios externos
  • dom: Manipulación de documentos XML/HTML
  • mbstring: Soporte para cadenas multibyte (UTF-8)
  • openssl: Cifrado y generación de claves
  • pdo: Acceso a bases de datos
  • tokenizer: Análisis de código PHP
  • xml: Procesamiento de XML

Para habilitar las extensiones, accede a cPanel, busca la sección Software y haz clic en Seleccionar versión de PHP. Desde ahí podrás activar las extensiones que necesites marcando las casillas correspondientes.

Si intentas instalar Laravel sin las extensiones necesarias, verás un error similar a este:

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - laravel/framework[v12.0.0, ..., v12.41.1] require league/flysystem-local ^3.25.1
    - league/flysystem-local[3.15.0, ..., 3.30.2] require ext-fileinfo * 
      -> it is missing from your system. Install or enable PHP's fileinfo extension.

Este error indica que falta la extensión fileinfo. Actívala desde cPanel y vuelve a intentar la instalación.

Instalación del instalador de Laravel

Accede a tu cuenta por medio de SSH o terminal integrada en cPanel.

El instalador oficial de Laravel es la forma recomendada para crear nuevos proyectos. Primero, instálalo de forma global usando Composer:

composer global require laravel/installer

Para que el comando laravel esté disponible sin introducir la ruta completa, edita el fichero .bashrc y añade al final:

export PATH="$PATH:$HOME/.composer/vendor/bin"

Aplica los cambios ejecutando source .bashrc y verifica que el instalador funciona correctamente:

laravel --version

Crear un nuevo proyecto Laravel

Una vez instalado el instalador, crear un nuevo proyecto es muy sencillo:

laravel new mi-proyecto

Donde mi-proyecto es el nombre del directorio donde se instalará Laravel. Puedes usar cualquier nombre o ruta relativa (por ejemplo, laravel new apps/blog creará la instalación en ~/apps/blog). El instalador te guiará de forma interactiva a través de varias opciones de configuración.

Selección de Starter Kit

Laravel 12 ofrece tres starter kits modernos que te proporcionan una base sólida para tu aplicación:

  • React: Combina Laravel con React 19, TypeScript, Inertia 2 y shadcn/ui. Ideal para aplicaciones de una sola página (SPA) con una pila moderna de JavaScript.

  • Vue: Integra Laravel con Vue 3, TypeScript, Inertia 2 y shadcn-vue. Perfecto para interfaces de usuario interactivas con el ecosistema Vue.

  • Livewire: Diseñado para desarrollo frontend impulsado por el servidor. Combina Laravel con Livewire y Tailwind CSS, permitiendo construir interfaces dinámicas sin necesidad de un framework JavaScript separado.

  • None: Si prefieres empezar con una instalación limpia sin frontend preconfigurado.

Selección de base de datos

El instalador te preguntará qué base de datos deseas utilizar. En un entorno de hosting compartido con cPanel, las opciones más relevantes son:

SQLite: El instalador crea automáticamente un archivo database.sqlite en el directorio database y configura la conexión. Es la opción más sencilla ya que no requiere configuración adicional en el servidor. SQLite es perfectamente válido para aplicaciones en producción y muchos proyectos grandes lo utilizan con éxito.

MySQL: Si tu aplicación requiere características específicas de MySQL o prefieres usar un servidor de base de datos dedicado, deberás crear la base de datos en cPanel antes o después de la instalación. Consulta nuestra guía de bases de datos MySQL para el proceso completo, o si lo prefieres puedes usar el asistente de bases de datos que te guiará paso a paso.

Una vez creada la base de datos y completada la instalación de Laravel, deberás configurar las credenciales en el archivo .env de tu proyecto:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=miusuario_nombredb
DB_USERNAME=miusuario_usuariodb
DB_PASSWORD=tu_contraseña_segura

Sustituye los valores por los que hayas configurado en cPanel. Recuerda que en cPanel el nombre de la base de datos y el usuario llevan el prefijo de tu cuenta (por ejemplo, si tu usuario es miusuario y creas una base de datos llamada laravel, el nombre real será miusuario_laravel).

Ejecución de migraciones

El instalador te preguntará si deseas ejecutar las migraciones de base de datos. Si has elegido SQLite, puedes responder que sí ya que la configuración es automática. Si has elegido MySQL, responde que no hasta que hayas configurado las credenciales en el archivo .env. Una vez configurado, ejecuta las migraciones manualmente:

php artisan migrate

Instalación sin interacción

Si prefieres una instalación automatizada sin preguntas, puedes pasar las opciones directamente:

laravel new mi-proyecto --livewire --pest --git --database=mysql

Algunas opciones útiles:

  • --react, --vue o --livewire: Selecciona el starter kit
  • --pest o --phpunit: Selecciona el framework de testing
  • --git: Inicializa un repositorio Git
  • --database=mysql|sqlite|pgsql: Configura la base de datos

Configurar el Document Root

Laravel utiliza el directorio public como punto de entrada de la aplicación. Todas las peticiones web deben dirigirse al fichero index.php dentro de este directorio. Tienes dos opciones para configurar esto en cPanel:

Opción 1: Cambiar el Document Root (dominios addon y subdominios)

Si estás usando un dominio addon o subdominio, puedes cambiar directamente el Document Root desde cPanel para que apunte al directorio public de tu instalación Laravel. Esta es la opción más limpia y recomendada cuando está disponible.

Opción 2: Enlace simbólico (dominio principal)

El dominio principal de tu cuenta está forzado a usar public_html como Document Root. En este caso, la solución es crear un enlace simbólico.

Partimos de la base que has instalado Laravel en un subdirectorio de la raíz de la cuenta (por ejemplo, ~/mi-proyecto). Desde la terminal, asegúrate de estar en la raíz de tu cuenta:

cd

Haz una copia de seguridad de public_html si contiene archivos que necesitas conservar, y luego elimínalo:

rm -rf public_html

Crea el enlace simbólico hacia el directorio public de Laravel:

ln -s mi-proyecto/public public_html

Desde este momento, al acceder a tu dominio se cargará la aplicación Laravel.

Tareas programadas (Cron)

Laravel incluye un programador de tareas que te permite definir comandos que se ejecutan automáticamente en intervalos específicos. Para activarlo, necesitas configurar un único cron job en cPanel que ejecute el scheduler de Laravel cada minuto.

Accede a cPanel, ve a la sección Avanzado y haz clic en Trabajos de Cron. Crea una nueva tarea con la siguiente configuración:

  • Configuración común: Selecciona "Una vez por minuto" o configura manualmente * * * * *
  • Comando: /usr/local/bin/php /home/tu_usuario/mi-proyecto/artisan schedule:run >> /dev/null 2>&1

Sustituye /home/tu_usuario/mi-proyecto por la ruta completa a tu instalación de Laravel. El scheduler se encargará de ejecutar todas las tareas programadas que hayas definido en tu aplicación según sus intervalos configurados.

Para más información sobre cómo configurar tareas en cPanel, consulta nuestra guía de trabajos de Cron.