Conectar PHP con MariaDB en Docker usando db.php

En este tutorial vamos a crear un archivo db.php para que cualquier página de nuestro proyecto PHP pueda conectarse a la base de datos MariaDB que tenemos dentro de Docker.

En este punto no haremos consultas SQL, solo dejaremos la conexión lista para usar más adelante.

Tabla de contenidos

1 1. Arquitectura básica con Docker
2 2. Instalar la extensión mysqli en el contenedor PHP
3 3. Crear el archivo db.php en el proyecto
4 4. Probar que la conexión funciona
5 5. Usar db.php desde otras páginas
6 6. Qué haremos más adelante

1. Arquitectura básica con Docker

Trabajamos con un docker-compose.yml parecido a este:

services:
  web:
    build: .
    container_name: php-web
    ports:
      - "8080:80"
    volumes:
      - ../academia-php:/var/www/html
    depends_on:
      - db

  db:
    image: mariadb:11
    container_name: mariadb
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: academia
      MYSQL_USER: administrador
      MYSQL_PASSWORD: adinistrador123
    volumes:
      - ./db:/var/lib/mysql
    ports:
      - "3306:3306"

Datos que usaremos en db.php:

Host (servidor): db
Base de datos: academia
Usuario: administrador
Contraseña: adinistrador123

2. Instalar la extensión `mysqli` en el contenedor PHP

Si al probar la conexión aparece un error como:

Fatal error: Class "mysqli" not found

es porque a PHP le falta la extensión mysqli.

En el Dockerfile del servicio web añade (o asegúrate de tener) esto:

FROM php:8.2-apache

WORKDIR /var/www/html

# Extensiones necesarias para MariaDB/MySQL
RUN docker-php-ext-install mysqli pdo pdo_mysql

RUN a2enmod rewrite

EXPOSE 80

Después, desde la carpeta donde está el docker-compose.yml:

docker compose down
docker compose up -d --build

Sin este paso, la conexión no funcionará.

3. Crear el archivo `db.php` en el proyecto

Dentro de la carpeta del proyecto PHP (por ejemplo academia-php/) crea un fichero llamado db.php con este contenido:

<?php
// Parámetros de conexión a la base de datos
$serverName = "db";               // Nombre del servicio de base de datos en Docker
$username   = "administrador";    // Usuario configurado en docker-compose
$password   = "adinistrador123";  // Contraseña configurada en docker-compose
$dbName     = "academia";         // Base de datos configurada en docker-compose

// Crear la conexión con MySQL/MariaDB usando mysqli
$conn = new mysqli($serverName, $username, $password, $dbName);

// Comprobar si hay errores en la conexión
if ($conn->connect_error) {
    die("Error de conexión: " . $conn->connect_error);
}

// Si llegamos aquí, la conexión se ha establecido correctamente.
// Más adelante usaremos $conn para trabajar con la base de datos.

Puntos importantes para el alumno:

Todas las variables empiezan por $ ($serverName, $username, etc.).
new mysqli(...) crea el objeto de conexión.
$conn->connect_error contiene el mensaje de error si algo ha ido mal.
die(...) detiene la ejecución y muestra el mensaje.
No hace falta cerrar el archivo con ?>.

4. Probar que la conexión funciona

Levanta los contenedores: docker compose up -d
En el navegador, abre: http://localhost:8080/db.php

Si los datos de conexión son correctos y mysqli está instalado, no verás ningún error (página en blanco).
Si hay algún problema, aparecerá un mensaje del tipo: Error de conexión: ...

Cuando la página no muestra error, consideramos que la conexión está bien hecha.

5. Usar `db.php` desde otras páginas

La idea es no repetir la conexión en cada archivo.
En cualquier página PHP que necesite acceder a la base de datos solo hay que incluir db.php al principio.

Ejemplo mínimo en index.php:

<?php
require __DIR__ . "/db.php";  // Prepara la conexión en $conn
?>
<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <title>Academia</title>
</head>
<body>
    <h1>Página de inicio</h1>
    <p>La base de datos ya está conectada gracias a db.php.</p>
</body>
</html>

Explicación rápida:

require __DIR__ . "/db.php"; ejecuta el código de conexión.
A partir de ese momento, la variable $conn está disponible en esa página y podremos usarla más adelante cuando sepamos SQL.