5.2 Entorno de desarrollo para Laravel

5.2.1 Introducción

En este apartado vamos a preparar un entorno profesional de desarrollo pensado para trabajar con Laravel utilizando Docker y Visual Studio Code. El objetivo es que todos los alumnos puedan replicar este entorno en su propio ordenador para asegurar una base común antes de comenzar con la programación de aplicaciones.

Vamos a montar:

  • Contenedores Docker para PHP 8.2-FPM y Nginx.
  • Composer para gestionar dependencias.
  • Xdebug para realizar depuración paso a paso desde Visual Studio Code.
  • Un proyecto base estructurado.

5.2.2 Requisitos previos

Antes de comenzar asegúrate de tener instalado en tu sistema:

5.2.3 Estructura del proyecto base

El proyecto inicial tendrá la siguiente estructura de carpetas:

/ (raíz del proyecto)
├── docker-compose.yml
├── README.md
├── php/
│   └── Dockerfile
│   └── conf.d/
│       └── 99-xdebug.ini
├── nginx/
│   └── default.conf
├── mysql/
│   └── data/
│       └── data.md
│   └── tmp/
│       └── tmp.md
├── src/
│   └── index.php
├── .vscode/
    └── launch.json

Descripción de cada componente

Carpeta/Fichero Descripción
docker-compose.yml Define los servicios Docker: PHP y Nginx.
php/Dockerfile Imagen personalizada de PHP 8.2 con Composer y Xdebug.
php/conf.d/99-xdebug.ini Configuración de Xdebug para depuración.
nginx/default.conf Configuración de Nginx para servir la aplicación.
mysql/data Carpeta donde almacenaremos las bases de datos
mysql/tmp Carpeta temporal para MySQL.
src/ Carpeta donde instalaremos Laravel.
.vscode/launch.json Configuración de depuración en Visual Studio Code.

Descargar el proyecto inicial desde GitHub

Para facilitar el trabajo y asegurar que todos los alumnos partimos del mismo entorno, hemos preparado un repositorio en GitHub con la estructura inicial ya configurada.

El repositorio público está disponible en:

https://github.com/jbeteta-ies/laravelinit.git

Clonar el repositorio

Para descargar el proyecto en tu ordenador debes seguir estos pasos:

  1. Abre una terminal o consola de comandos.
  2. Sitúate en la carpeta donde quieras clonar el proyecto.
  3. Ejecuta el siguiente comando:
git clone https://github.com/jbeteta-ies/laravelinit.git

Esto descargará todo el repositorio en tu ordenador.

¿Qué rama se descarga al clonar?

Cuando clonas el repositorio, Git descarga todo el historial de commits y todas las ramas existentes.
Sin embargo, te deja situado en la rama main por defecto.

Para poder trabajar en el estado inicial preparado para el curso, será necesario cambiarse a la rama correcta.

Cambiar a la rama inicial de trabajo

Después de clonar el repositorio, cambia a la rama entorno-inicial ejecutando:

cd laravelinit
git checkout entorno-inicial

Con esto, estarás trabajando en la versión del proyecto lista para comenzar con Laravel.

Estructura que encontrarás

Una vez hayas cambiado a la rama entorno-inicial, encontrarás la siguiente estructura de carpetas y archivos:

/ (raíz del proyecto)
├── docker-compose.yml
├── README.md
├── php/
│   ├── Dockerfile
│   └── conf.d/
│       └── 99-xdebug.ini
├── nginx/
│   └── default.conf
├── mysql/
│   ├── data/
│   │   └── data.md
│   └── tmp/
│       └── tmp.md
├── src/
│   └── index.php
├── .vscode/
│   └── launch.json

Estructura inicial

Es importante que tu estructura contenga todos estos archivos y carpetas para que el entorno funcione correctamente. Si falta alguna carpeta como mysql/data o mysql/tmp, el entorno no se levantará correctamente. Debes crearlas manualmente si no existen.

Si se han creado correctamente, debes eliminar los archivos data.md y tmp.md de las carpetas mysql/data y mysql/tmp, respectivamente. Estos archivos son solo marcadores para indicar que esas carpetas deben existir, pero no deben contener nada al iniciar el entorno.

Nota importante

Importante

Recuerda siempre cambiarte a la rama correcta (git checkout nombre-rama) antes de empezar a trabajar en cada tema del curso.

Si en algún momento necesitas actualizar tu repositorio local con nuevas ramas que se creen durante el curso, puedes usar:

git fetch origin

Y luego cambiarte a la nueva rama deseada con:

git checkout nombre-de-la-rama

5.2.4 Configuración de Docker

Dockerfile para PHP.

Vamos a crear un archivo Dockerfile para configurar un contenedor de PHP 8.4 con las extensiones necesarias para Laravel, Composer y Xdebug. Este archivo se ubicará en la carpeta php/ del proyecto.

Este archivo crea una imagen de PHP personalizada:

Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
FROM php:8.4-fpm

# Instalar las dependencias necesarias 
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    curl \
    libzip-dev \
    libpng-dev \
    libxml2-dev \
    libonig-dev \
    libssl-dev \
    libmongoc-1.0-0 \
    libjemalloc2 \
    && rm -rf /var/lib/apt/lists/*

# Instalar extensiones de PHP necesarias (como PDO y MySQL)
RUN docker-php-ext-install pdo pdo_mysql xml ctype zip 

# Instalamos Composer, gestor de dependencias de PHP
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# Instalamos Xdebug
# RUN pecl install xdebug \
#    && docker-php-ext-enable xdebug

# Opcional: Definir directorio de trabajo
WORKDIR /var/www/html


# Configuración de PHP
RUN cp /usr/local/etc/php/php.ini-development /usr/local/etc/php/php.ini

# Instalación opcional de MongoDB
# RUN pecl install mongodb \
#    && docker-php-ext-enable mongodb

# Establecer la ruta de trabajo
WORKDIR /var/www/html

docker-compose.yml

Archivo para definir y levantar los servicios:

docker-compose.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
services:
php:
    image: php:8.4-fpm
    build: ./php
    container_name: dk_php
    volumes:
    - ./src:/var/www/html
    - ./php/conf.d/99-xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini
    environment:
    - MYSQL_HOST=mysql
    - MYSQL_USER=alumno
    - MYSQL_PASSWORD=alumno
    - MYSQL_DB=test
    - MONGODB_HOST=host.docker.internal
    - MONGODB_USER=alumno
    - MONGODB_PASSWORD=alumno
    - MONGODB_DB=test
    - MONGODB_PORT=27017
    depends_on:
    - mysql

nginx:
    image: nginx:latest
    container_name: dk_nginx
    ports:
    - "8080:80"
    volumes:
    - ./src:/var/www/html
    - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
    - php

mysql:
    image: mysql:8
    container_name: dk_mysql
    environment:
    MYSQL_ROOT_PASSWORD: administrador
    MYSQL_USER: alumno
    MYSQL_PASSWORD: alumno
    MYSQL_DATABASE: test
    volumes:
    - ./mysql/data:/var/lib/mysql
    - ./mysql/tmp:/tmp
    ports:
    - "3306:3306"
    networks:
    - default

networks:
default:
    driver: bridge

Configuración de Xdebug

Archivo php/conf.d/99-xdebug.ini:

1
2
3
4
5
6
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log_level=0

Configuración de Nginx

Archivo nginx/default.conf:

nginx/default.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
server {
    listen 80;
    server_name localhost;

    root /var/www/html;
    index index.php index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$$fastcgi_script_name;
    }

    location ~ /\.ht {
        deny all;
    }
}

Importante

Nota: Posteriormente, cuando instalemos Laravel, se modificará el root para apuntar a /var/www/html/public.

5.2.5 Configuración de Visual Studio Code

A continuación, configuraremos Visual Studio Code para que funcione con Xdebug. Crea la carpeta .vscode en la raíz del proyecto para añadir el archivo de configuración. Es importante que la carpeta comience con un punto (.) para que sea oculta.

Archivo .vscode/launch.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}/src"
            }
        }
    ]
}

5.2.6 Levantar el entorno

Carpeta ./mysql/data

Esta carpeta debe estar vacía antes de levantar el entorno por primera vez. Si contiene el archivo data.md, significa que aún no se ha inicializado la base de datos de MySQL. Elimina ese archivo antes de continuar. La carpeta ./mysql/data es donde se almacenarán las bases de datos de MySQL. Asegúrate de que existe y tiene los permisos adecuados para que MySQL pueda escribir en ella.

Desde la terminal, en la carpeta del proyecto, la primera vez que levantes el entorno, ejecuta:

docker-compose up -d --build
Esto construirá las imágenes y levantará los contenedores. En futuras ocasiones, puedes usar simplemente:

docker-compose up -d

Accede a http://localhost:8080 y deberías ver el phpinfo() funcionando.

Para detener el entorno, puedes usar:

docker-compose down

5.2.7 Probar la instalación

Verificar el Debug

  1. Coloca un breakpoint en src/index.php.
  2. Inicia la depuración en VSCode (F5).
  3. Accede de nuevo a http://localhost:8080.
  4. VSCode debería detenerse en el breakpoint.

Problemas frecuentes

  • Error de conexión a Xdebug: Asegurarse que el puerto 9003 está libre.
  • No se detiene en breakpoints: Verificar pathMappings en launch.json.
  • Problemas en la instalación de extensiones PHP: Limpiar contenedores e imagenes (docker system prune).

5.2.8 Otras extensiones recomendadas para Visual Studio Code

Extensión Descripción
Laravel Blade Snippets Snippets para Laravel Blade.
PHP Intelephense Autocompletado y análisis de código para PHP.
Laravel intellisense Autocompletado para Laravel.
Laravel Docs Acceso rápido a la documentación de Laravel.
Laravel Blade Formatter Formateador de Blade.
PHP Debug Depuración de PHP. (PHP Debug Adapter)