Apuntes sobre Php

PHP: Porque a veces necesitas un poco de caos en tu vida.

Incluyendo archivos en PHP: Modularidad y reutilización de código

La capacidad de reutilizar código es una de las características más poderosas de PHP. Las sentencias include y require te permiten insertar y evaluar archivos externos, como scripts PHP, HTML o plantillas. Esta funcionalidad es la base para crear código modular, reutilizable y fácil de mantener.

Una práctica muy común es "trocear" la estructura de un sitio web en partes: un archivo para la cabecera (header.php), otro para el pie de página (footer.php) y un tercero para la navegación (nav.php) etc. Si necesitas cambiar un enlace, lo harás en un solo lugar, no en todos los archivos de tu sitio.

include vs. require. La diferencia clave

La principal distinción entre estas dos sentencias radica en cómo manejan los errores cuando el archivo no se encuentra.

include

La sentencia include inserta y evalúa un archivo. Si el archivo no existe, o no se encuentra en la ruta facilitada, PHP emite una advertencia de tipo E_WARNING y el script continúa su ejecución. Es la opción ideal para incluir archivos que no son críticos para el funcionamiento principal de tu aplicación.

<?php
// Si 'anuncio.php' no existe, se muestra una advertencia, pero el script sigue funcionando
include 'anuncio.php';
echo "El resto de la página se ha cargado correctamente.";
?>

require

La sentencia require es similar, pero si el archivo no existe, produce un error fatal (E_COMPILE_ERROR) y detiene la ejecución del script. Esta es la opción más segura y recomendada para archivos que son esenciales para el correcto funcionamiento de la aplicación.

<?php
// Si 'config.php' no existe, el script se detiene y no se ejecuta nada más
require 'config.php';
echo "Este mensaje no se mostrará si el archivo de configuración no se encuentra.";
?>

Regla general: usa require para archivos esenciales como la configuración de la base de datos o librerías de funciones, y include para elementos opcionales como anuncios o widgets.

include_once y require_once: Evita duplicados

Las variantes _once garantizan que un archivo se incluya solo una vez durante la ejecución del script. Esto es crucial para evitar errores de redefinición de funciones, clases o constantes, ya que PHP no permite declarar el mismo elemento más de una vez.

<?php
// En funciones.php
function saludar(): string {
    return "¡Hola, mundo!";
}

// En el archivo principal
include_once 'funciones.php';
// La siguiente línea se ignorará porque el archivo ya ha sido incluido
include_once 'funciones.php';

echo saludar(); // Imprime: ¡Hola, mundo!
?>

Recomendación: Usa las variantes _once por defecto para cualquier archivo que defina funciones, clases o constantes.

Gestión de rutas: El uso de DIR

Este es un tema crucial para evitar errores comunes. La regla de oro es:

Las rutas relativas se resuelven desde el directorio del script principal que se está ejecutando (incluyente), no desde el archivo que se está cargando con include.

Esto puede causar problemas si un archivo incluido intenta a su vez incluir otro archivo. Para solucionar este problema, usamos rutas absolutas construidas con la constante mágica __DIR__.

¿Qué es DIR y por qué es tan útil?

__DIR__ devuelve la ruta completa del directorio donde se encuentra el archivo en el que se utiliza.

Su principal utilidad es que te proporciona un punto de referencia constante y fiable para construir rutas absolutas. Su valor es diferente para cada archivo, lo que te permite navegar de forma segura por la estructura de tu proyecto sin importar desde dónde se haya llamado a un script.

Ejemplo práctico

Supongamos la siguiente estructura de carpetas:

proyecto/
├── index.php
├── docs/
│   └── estudios/
│       └── importante.php
└── partials/
    └── sidebar.php

Si desde index.php llamas a importante.php y este a su vez intenta incluir sidebar.php, la ruta relativa '../../partials/sidebar.php' fallará, ya que se resolverá desde el directorio de index.php.

La solución es usar __DIR__ en importante.php para construir una ruta absoluta:

<?php
// En /docs/estudios/importante.php
// __DIR__ aquí es '/proyecto/docs/estudios'
// Construimos la ruta absoluta hacia sidebar.php:
include __DIR__ . '/../../partials/sidebar.php';
// Esto se resuelve a: '/proyecto/docs/estudios/../../partials/sidebar.php'
// Y PHP lo simplifica automáticamente a: '/proyecto/partials/sidebar.php'
// Esta ruta siempre será correcta, sin importar desde dónde se haya llamado a importante.php
?>

Ejemplo adicional con múltiples niveles

<?php
// En cualquier archivo del proyecto, estas rutas siempre funcionarán:
require_once __DIR__ . '/../config/database.php';     // Subir un nivel y entrar a config
require_once __DIR__ . '/../../vendor/autoload.php';  // Subir dos niveles y entrar a vendor
include __DIR__ . '/templates/header.php';            // Mismo nivel, carpeta templates
?>

Valor de retorno y variables compartidas

Cuando incluyes un archivo con include o require, tienes dos formas de obtener datos del archivo incluido:

1. Variables compartidas (enfoque tradicional)

El archivo incluido puede declarar variables que estarán disponibles en el archivo que lo incluye:

<?php
// En el archivo 'config_variables.php':
$db_host = 'localhost';
$db_user = 'admin';
$db_password = 'secreto123';
$db_name = 'mi_aplicacion';

// En el archivo principal:
require 'config_variables.php';
// Las variables están directamente disponibles
echo $db_host; // Imprime: localhost
echo $db_user; // Imprime: admin
?>

2. Usando return (enfoque más moderno y recomendado)

El archivo incluido puede devolver un valor usando return, que puedes capturar asignando el resultado de include/require a una variable:

<?php
// En el archivo 'config_return.php':
return [
    'db_host' => 'localhost',
    'db_user' => 'admin',
    'db_password' => 'secreto123',
    'db_name' => 'mi_aplicacion'
];

// En el archivo principal:
$config = require 'config_return.php';
echo $config['db_host']; // Imprime: localhost
echo $config['db_user']; // Imprime: admin

/*
La variable $config contendrá:
Array
(
    [db_host] => localhost
    [db_user] => admin
    [db_password] => secreto123
    [db_name] => mi_aplicacion
)
*/
?>

¿Por qué usar return es mejor práctica?

  1. Evita contaminación del espacio global: Las variables no se crean en el ámbito global
  2. Más limpio y explícito: Es claro qué datos proporciona el archivo
  3. Evita conflictos de nombres: No hay riesgo de sobrescribir variables existentes
  4. Más fácil de testear: Puedes capturar y verificar fácilmente los valores devueltos
<?php
// Problema con variables compartidas:
$nombre = "Juan";
require 'archivo_que_tambien_define_nombre.php';
// ¿Qué valor tiene $nombre ahora? ¡Puede haber sido sobrescrito!

// Solución con return:
$nombre = "Juan";
$datos = require 'archivo_con_return.php';
// $nombre sigue siendo "Juan", $datos contiene lo que necesitas
?>

La clave está en entender que cuando usas return en un archivo incluido, debes capturar expresamente ese valor asignando el resultado de require/include a una variable. Si no lo haces, el valor se pierde.

¿Qué pasa realmente con return?

<?php
// En config.php - Lo que realmente pasa paso a paso:

// 1. PHP ejecuta el archivo línea por línea
// 2. Cuando encuentra 'return [...]', DETIENE la ejecución del archivo
// 3. El array se convierte en el "resultado" de toda la operación include/require

return [
    'db_host' => 'localhost',
    'db_user' => 'admin'
];

// CUALQUIER CÓDIGO DESPUÉS DE return NUNCA SE EJECUTA
echo "Este mensaje nunca se verá"; // Esta línea es inalcanzable

// En el archivo principal:
$config = require 'config.php';
// PHP ejecuta config.php, encuentra el return, y asigna el array a $config

// Si NO capturas el valor:
require 'config.php'; // El array se crea y se pierde inmediatamente
?>

Demostración práctica de la diferencia

<?php
// archivo1_con_variables.php
$mensaje = "Hola desde archivo1";
$numero = 42;

// archivo2_con_return.php
return [
    'mensaje' => 'Hola desde archivo2',
    'numero' => 42
];

// En el script principal:
require 'archivo1_con_variables.php';
echo $mensaje; // Funciona: "Hola desde archivo1"
echo $numero;  // Funciona: 42

// Pero con return:
require 'archivo2_con_return.php';  // El array se crea y se pierde
echo $mensaje; // Error: variable no definida

// Forma correcta con return:
$datos = require 'archivo2_con_return.php'; // Capturamos el array
echo $datos['mensaje']; // Funciona: "Hola desde archivo2"
?>

return es una instrucción especial que dice "termina la ejecución de este archivo y devuelve este valor como resultado de la operación include/require".

Ejemplo avanzado con configuración condicional

<?php
// En 'config.php' - Configuración más avanzada
$environment = $_SERVER['SERVER_NAME'] === 'localhost' ? 'development' : 'production';

return [
    'environment' => $environment,
    'database' => [
        'host' => $environment === 'development' ? 'localhost' : 'prod-server.com',
        'name' => $environment === 'development' ? 'test_db' : 'production_db',
    ],
    'debug' => $environment === 'development'
];

// En el archivo principal:
$config = require_once __DIR__ . '/config/config.php';
if ($config['debug']) {
    error_reporting(E_ALL);
}
?>

Explicacion:

1. Detecta el entorno: $_SERVER['SERVER_NAME'] es una variable generada automáticamente por el sistema, y contiene el nombre del servidor (ej: 'localhost', 'miweb.com').

Si es 'localhost' quiere decir que estamos en desarrollo local. Si NO es 'localhost' , estamos en producción.

El operador ternario determina que $environment contenga el valor "development" si estamos en localhost, o production en caso contrario.

return devuelve un array con valores distintos si estamos en desarrollo (Base de datos local, activar debug etc) mientras que si estamos en producción devuelve los valores necesarios para nuestro hosting.

Es una forma de tener una sola configuración que se adapta automáticamente según dónde esté ejecutándose el código. No tienes que cambiar nada cuando subes el código a producción - se adapta solo.

Seguridad y buenas prácticas

1. Evita inclusiones remotas

Desactiva allow_url_include en tu archivo php.ini. Incluir archivos desde una URL externa es un grave riesgo de seguridad que puede permitir la inyección de código remoto.

; En php.ini
allow_url_include = Off

2. Controla inclusiones dinámicas

Nunca incluyas archivos directamente basándote en variables no validadas, como los datos de la URL ($_GET). Un atacante podría manipular la URL para inyectar un archivo malicioso.

<?php
// CÓDIGO INSEGURO
// Un atacante podría acceder a: http://tu-sitio.com/?pagina=../../etc/passwd
include $_GET['pagina'];

// CÓDIGO SEGURO: valida las opciones permitidas
$pagina = $_GET['pagina'] ?? 'inicio';
$paginas_permitidas = ['inicio', 'contacto', 'acerca', 'servicios'];

if (in_array($pagina, $paginas_permitidas)) {
    include __DIR__ . '/pages/' . $pagina . '.php';
} else {
    include __DIR__ . '/pages/error404.php';
}
?>

3. Protege variables y sanitiza salida

Cuando incluyas archivos que usen variables del script principal, asegúrate de que esas variables estén sanitizadas. Si el archivo header.php muestra el título de la página, sanitiza la variable con htmlspecialchars() para prevenir ataques de Cross-Site Scripting (XSS).

<?php
// En el script principal
$titulo_pagina = $_GET['titulo'] ?? 'Mi Sitio Web';
$titulo_seguro = htmlspecialchars($titulo_pagina, ENT_QUOTES, 'UTF-8');

// En header.php
echo "<title>" . $titulo_seguro . "</title>";
?>

Resumen de mejores prácticas

  1. Usa require_once para archivos críticos (configuración, funciones, clases)
  2. Usa include solo para contenido opcional que no afecte la funcionalidad
  3. Siempre usa __DIR__ para construir rutas absolutas
  4. Valida siempre las inclusiones dinámicas con una lista blanca
  5. Sanitiza variables que se pasen a archivos incluidos
  6. Organiza tu código en una estructura de carpetas lógica
  7. Desactiva inclusiones remotas en la configuración de PHP

Paréntesis: Modo HTML vs. Modo PHP en archivos incluidos

Cuando incluyes un archivo, PHP inserta literalmente su contenido en el punto donde se hace la llamada. Si el archivo incluido contiene código PHP, debe estar dentro de las etiquetas <?php ?>, ya que PHP pasa automáticamente a "modo HTML" fuera de estas etiquetas.

<!-- En header.php -->
<!DOCTYPE html>
<html>
<head>
    <title><?php echo $titulo_pagina; ?></title>
    <meta charset="UTF-8">
</head>
<body>
    <header>
        <h1>Mi Sitio Web</h1>
        <?php if ($usuario_logueado): ?>
            <p>Bienvenido, <?php echo htmlspecialchars($nombre_usuario); ?></p>
        <?php else: ?>
            <p><a href="login.php">Iniciar sesión</a></p>
        <?php endif; ?>
    </header>

<!-- En el archivo principal -->
<?php
$titulo_pagina = "Página de inicio";
$usuario_logueado = true;
$nombre_usuario = "Juan";

include 'header.php'; // El HTML se renderiza, el PHP se ejecuta
?>

<main>
    <p>Contenido principal de la página...</p>
</main>

Si olvidas las etiquetas PHP en el archivo incluido, el código se mostrará como texto plano en lugar de ejecutarse:

<!-- INCORRECTO - sin etiquetas PHP en header.php -->
<!DOCTYPE html>
<html>
<head>
    <title>echo $titulo_pagina;</title> <!-- Se muestra literalmente -->
</head>

<!-- CORRECTO - con etiquetas PHP -->
<!DOCTYPE html>
<html>
<head>
    <title><?php echo $titulo_pagina; ?></title> <!-- Se ejecuta y muestra el valor -->
</head>

Bonus: ¿Cuándo usar la etiqueta de cierre ?>?

Esta es una pregunta muy común que genera confusión. La regla es simple pero tiene matices importantes:

Archivos que mezclan HTML y PHP (templates, vistas)

SÍ debes usar ?> para cerrar cuando el archivo contiene tanto código PHP como HTML, y necesitas salir del modo PHP para escribir HTML:

<?php
$usuario = "María";
$fecha = date('Y-m-d');
?>
<!DOCTYPE html>
<html>
<head>
    <title>Mi Sitio</title>
</head>
<body>
    <h1>Bienvenida <?php echo $usuario; ?></h1>
    <p>Fecha: <?php echo $fecha; ?></p>
</body>
</html>

Archivos que son SOLO PHP (clases, funciones, configuración)

Es mejor práctica OMITIR ?> cuando el archivo contiene únicamente código PHP sin HTML al final:

<?php
// RECOMENDADO - Sin etiqueta de cierre
class Usuario {
    private $nombre;

    public function __construct($nombre) {
        $this->nombre = $nombre;
    }

    public function saludar() {
        return "Hola, " . $this->nombre;
    }
}

// config.php
return [
    'db_host' => 'localhost',
    'db_user' => 'admin'
];

// funciones.php
function calcular($a, $b) {
    return $a + $b;
}
// NO pongas ?> aquí

¿Por qué omitir ?> es mejor práctica?

El problema son los espacios en blanco accidentales:

<?php
echo "Hola mundo";
?>
    <!-- ¡Hay espacios o saltos de línea aquí! -->

Esos espacios invisibles después de ?> pueden causar:

  • Headers already sent: Error al intentar usar header() o setcookie()
  • Problemas con JSON/XML: Espacios extra que corrompen la salida
  • Problemas con includes: Espacios inesperados en la página final
<?php
// archivo1.php
echo "Primera parte";
?>
   <!-- espacios accidentales -->

<?php
// archivo2.php
echo "Segunda parte";
?>


<?php
// main.php
include 'archivo1.php';
include 'archivo2.php';
header('Content-Type: application/json'); // Error: headers already sent
?>

La regla simplificada

En realidad La clave no es si el archivo es "mixto", sino qué hay AL FINAL del archivo:

  • Si el archivo termina con HTML → Ya habrás usado ?> para salir del modo PHP (porque si no, daría error de sintaxis)
  • Si el archivo termina con PHP → Omite ?> para evitar espacios problemáticos

En realidad, NUNCA es "necesario" poner ?> al final, porque:

<?php
echo "Código PHP";
echo "Más PHP";
?>
<p>HTML aquí</p>
<!-- Si termina con HTML, el ?> ya estaba antes por obligación -->

<?php
echo "Solo PHP";
function miFuncion() {
    return "algo";
}
// Si termina con PHP, el ?> es opcional y mejor omitirlo

Resumen ultra-simple:

  • ¿Termina el archivo con PHP? → No pongas ?>
  • ¿Termina con HTML? → El ?> ya estará ahí por necesidad, no por elección

Esta práctica está recomendada por el PSR-2 (PHP Standards Recommendations) y es ampliamente adoptada en frameworks modernos como Laravel, Symfony, etc.

Paréntesis final: coste de rendimiento. Entradas y salidas constantes de modo PHP

Cada vez que PHP encuentra <?php y ?>, debe cambiar de contexto (de modo HTML a modo PHP y viceversa). Esto tiene un pequeño coste computacional que puede acumularse:

<!-- INEFICIENTE - Muchos cambios de contexto -->
<h1>Bienvenida <?php echo $usuario; ?></h1>
<p>Fecha: <?php echo $fecha; ?></p>
<p>Hora: <?php echo $hora; ?></p>
<p>Ubicación: <?php echo $ciudad; ?></p>
<p>Temperatura: <?php echo $temperatura; ?>°C</p>

<!-- MÁS EFICIENTE - Un solo bloque PHP -->
<?php
echo "<h1>Bienvenida $usuario</h1>";
echo "<p>Fecha: $fecha</p>";
echo "<p>Hora: $hora</p>";
echo "<p>Ubicación: $ciudad</p>";
echo "<p>Temperatura: {$temperatura}°C</p>";
?>

<!-- ALTERNATIVA: Usando heredoc para HTML complejo -->
<?php
echo <<<HTML
<h1>Bienvenida $usuario</h1>
<p>Fecha: $fecha</p>
<p>Hora: $hora</p>
<p>Ubicación: $ciudad</p>
<p>Temperatura: {$temperatura}°C</p>
HTML;
?>

¿Cuándo importa esto?

  • En páginas con muchas variables embebidas (cientos)
  • En sitios con mucho tráfico
  • En aplicaciones donde la velocidad es crítica

Para sitios web normales, la diferencia es insignificante, pero es bueno conocer el concepto.

TOP