Skip to content

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:

    .
    ├── docker-compose.yml            # Archivo principal de configuración de Docker
    └── docker/
        ├── nginx/
        │   └── default.conf          # Configuración de Nginx
        ├── php/
        │   ├── Dockerfile            # Dockerfile para el contenedor PHP
        │   ├── entrypoint.sh         # Script de entrada del contenedor PHP
        │   └── xdebug.ini            # Configuración de Xdebug para PHP
        ├── scripts/
        │   └── .gitkeep              # Git keep para mantener la carpeta vacía
        └── mysql/
            └── init/
                └── 01-grants.sql     # Script de inicialización para MySQL
    └── src/
        └── index.php                 # Archivo de entrada de tu proyecto PHP (por ejemplo, Laravel)

Descripción de cada componente

Carpeta/Fichero Descripción
docker/ Carpeta que contiene toda la configuración relacionada con Docker.
docker/nginx/default.conf Configuración de Nginx para servir la aplicación.
docker/php/Dockerfile Dockerfile para configurar el contenedor de PHP.
docker/php/entrypoint.sh Script de entrada para el contenedor PHP (puede contener comandos para iniciar servicios o configurar el entorno).
docker/php/xdebug.ini Configuración de Xdebug para habilitar la depuración en PHP.
docker/scripts/ Carpeta para scripts adicionales que puedas necesitar (por ejemplo, para inicializar la base de datos).
docker/mysql/init/01-grants.sql Script SQL para configurar los permisos de MySQL al iniciar el contenedor.
src/ Carpeta donde se ubicará el código fuente de tu proyecto (por ejemplo, la instalación de Laravel).

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:

    .
    ├── docker-compose.yml            # Archivo principal de configuración de Docker
    └── docker/
        ├── nginx/
        │   └── default.conf          # Configuración de Nginx
        ├── php/
        │   ├── Dockerfile            # Dockerfile para el contenedor PHP
        │   ├── entrypoint.sh         # Script de entrada del contenedor PHP
        │   └── xdebug.ini            # Configuración de Xdebug para PHP
        ├── scripts/
        │   └── .gitkeep              # Git keep para mantener la carpeta vacía
        └── mysql/
            └── init/
                └── 01-grants.sql     # Script de inicialización para MySQL
    └── src/
        └── index.php                 # Archivo de entrada de tu proyecto PHP (por ejemplo, Laravel)

Estructura inicial

Es importante que tu estructura contenga todos estos archivos y carpetas para que el entorno funcione correctamente. Si falta alguna carpeta o ficjhero puede que el entorno no se levante correctamente. Debes crearlas manualmente si no existen.

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
FROM php:8.3-fpm

RUN apt-get update && apt-get install -y \
    git curl unzip zip libzip-dev libpng-dev \
    && docker-php-ext-install pdo_mysql zip gd \
    && pecl install xdebug \
    && docker-php-ext-enable xdebug \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

COPY docker/php/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini
COPY docker/php/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

WORKDIR /var/www
ENTRYPOINT ["/entrypoint.sh"]
CMD ["php-fpm"]

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
52
53
54
55
56
57
58
59
60
61
services:
php:
    build:
    context: .
    dockerfile: docker/php/Dockerfile
    working_dir: /var/www
    volumes:
    - ./src:/var/www
    - ./scripts:/scripts
    environment:
    # Xdebug apagado por defecto; se activa con XDEBUG_MODE=debug
    XDEBUG_CONFIG: "client_host=host.docker.internal client_port=9003"

    # Variables “tipo curso” (PHP puro)
    MYSQL_HOST: mysql
    MYSQL_USER: alumno
    MYSQL_PASSWORD: alumno
    MYSQL_DB: test

    # Variables estándar Laravel (por si las necesitas)
    #DB_CONNECTION: mysql
    #DB_HOST: mysql
    #DB_PORT: 3306
    #DB_DATABASE: test
    #DB_USERNAME: alumno
    #DB_PASSWORD: alumno
    extra_hosts:
    - "host.docker.internal:host-gateway"
    user: "${UID:-1000}:${GID:-1000}"
    depends_on:
    - mysql

nginx:
    image: nginx:alpine
    ports:
    - "8080:80"
    depends_on:
    - php
    volumes:
    - ./src:/var/www:ro
    - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro

mysql:
    image: mysql:8.0
    environment:
    MYSQL_ROOT_PASSWORD: administrador
    MYSQL_DATABASE: test
    MYSQL_USER: alumno
    MYSQL_PASSWORD: alumno
    ports:
    # Evita colisiones con MySQL local del host
    - "3307:3306"
    volumes:
    - dbdata:/var/lib/mysql
    - ./scripts:/scripts
    - ./docker/mysql/init:/docker-entrypoint-initdb.d:ro
    tmpfs:
    - /tmp

volumes:
dbdata:

Configuración de Xdebug

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

1
2
3
4
5
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=host.docker.internal
xdebug.discover_client_host=0

Configuración de Nginx

Archivo nginx/default.conf:

nginx/default.conf

```nginx linenums="1" server { listen 80; server_name _; root /var/www/public;

index index.php index.html;

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

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

location ~ /\.(?!well-known).* {
    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": "${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)