PanelController

Overview

The PanelController handles the registration of new product returns (devoluciones). It provides form display, data validation, file upload handling, and database persistence for return records. Source: controllers/PanelController.php Access Control: Grado 1 (Administrator) or Grado 2 (Auxiliary) only Dependencies:

Models/ProductoModel.php - Product catalog access
Models/DevolucionModel.php - Return data persistence

Constructor

public function __construct()

Initializes the controller with authentication and authorization checks. Security Checks:

Starts PHP session if not active
Verifies user is authenticated ($_SESSION['logged_in'])
Verifies user has Grado 1 or Grado 2 access
Redirects unauthorized users appropriately:
- Not logged in → login page
- Wrong grado → home page

Access RestrictionOnly users with Grado 1 (Administrator) or Grado 2 (Auxiliary) can access this controller. Grado 3 users are redirected to the home page.

Source Code:

public function __construct() {
    if (session_status() === PHP_SESSION_NONE) session_start();
    
    // Verificar autenticación
    if (!isset($_SESSION['logged_in'])) {
        header('Location: index.php?url=auth/index');
        exit;
    }
    
    // Verificar permisos (Solo Admin Grado 1 o Auxiliar Grado 2)
    if (!isset($_SESSION['grado']) || ($_SESSION['grado'] != 1 && $_SESSION['grado'] != 2)) {
        header('Location: index.php?url=home/index');
        exit;
    }
    
    $this->prodModel = new ProductoModel();
    $this->devModel = new DevolucionModel();
}

Methods

auxiliar()

public function auxiliar(): void

Displays the return registration form with product catalog dropdown. Functionality:

Retrieves all products from database
Loads registration form view
Populates product dropdown

Data Provided to View:

productos

array

Complete product catalog array with item codes and descriptions

titulo

string

Page title: “Registro de Devolución - DevolutionSync”

View Rendered: Views/admin/panel_auxiliar.php Example Usage:

GET index.php?url=panel/auxiliar

Source Code:

public function auxiliar() {
    $productos = $this->prodModel->listarTodos();
    $titulo = "Registro de Devolución - DevolutionSync";
    require_once 'Views/admin/panel_auxiliar.php';
}

registrar()

public function registrar(): void

Processes return registration form submission with validation, file upload, and database persistence. HTTP Method: POST POST Parameters:

producto

string

required

Product item code from catalog

nit

string

required

Customer NIT (tax identification number)

nombre_cliente

string

required

Customer full name

direccion

string

required

Customer address

motivo

string

required

Reason for return (e.g., “Producto defectuoso”)

cantidad_und

float

required

Quantity in units (must be > 0)

cantidad_kg

float

required

Quantity in kilograms (must be ≥ 0)

observacion

string

required

Additional observations/notes

File Upload Parameter:

evidencia

file

default:"optional"

Evidence image file (JPG, PNG, or GIF, max 5MB)

Process Flow:

Registration Process Steps

Validate product selection
- Check $_POST['producto'] is not empty
- Retrieve product data from database
- Throw exception if product not found
Validate all required fields
- Call validarCampos($_POST)
- Check all mandatory fields present
- Validate quantity ranges
Handle file upload (if present)
- Check $_FILES['evidencia'] for upload
- Call subirEvidencia() if file provided
- Store file path or null
Prepare data array
- Sanitize all text inputs with limpiar()
- Merge POST data with product info
- Add creator username from session
Save to database
- Call DevolucionModel::guardar($datos)
- Set success/error message in session
Redirect to form
- Always redirects to index.php?url=panel/auxiliar
- Alert message displayed from session

Data Structure Saved:

$datos = [
    'nit' => string,                    // Sanitized customer NIT
    'nombre_cliente' => string,         // Sanitized customer name
    'direccion' => string,              // Sanitized address
    'item_producto' => string,          // Product item code
    'descripcion_producto' => string,   // Product description
    'unidad' => string,                 // Unit type (default: 'UND')
    'kg' => float,                      // Product kg value
    'motivo' => string,                 // Return reason
    'cantidad_und' => float,            // Quantity in units
    'cantidad_kg' => float,             // Quantity in kg
    'observacion' => string,            // Observations
    'usuario_creador' => string,        // $_SESSION['user']
    'evidencia' => string|null          // File path or null
];

Session Alerts:

$_SESSION['alerta']['tipo']

string

Alert type: "success" or "error"

$_SESSION['alerta']['msg']

string

Alert message to display to user

Success Alert:

[
    'tipo' => 'success',
    'msg' => '✅ Devolución registrada correctamente. ID de registro generado.'
]

Error Alert:

[
    'tipo' => 'error',
    'msg' => '❌ {exception_message}'
]

Source Code:

public function registrar() {
    if ($_SERVER['REQUEST_METHOD'] == 'POST') {
        try {
            // 1. Obtener datos del producto seleccionado
            $itemProducto = $_POST['producto'] ?? '';
            
            if (empty($itemProducto)) {
                throw new Exception('Debe seleccionar un producto');
            }
            
            $producto = $this->prodModel->obtenerPorItem($itemProducto);
            
            if (!$producto) {
                throw new Exception('Producto no encontrado');
            }
            
            // 2. Validar campos obligatorios
            $this->validarCampos($_POST);
            
            // 3. Manejar subida de evidencia (si existe)
            $rutaEvidencia = null;
            if (isset($_FILES['evidencia']) && $_FILES['evidencia']['error'] == UPLOAD_ERR_OK) {
                $rutaEvidencia = $this->subirEvidencia($_FILES['evidencia']);
            }
            
            // 4. Preparar array de datos para guardar
            $datos = [
                'nit' => $this->limpiar($_POST['nit']),
                'nombre_cliente' => $this->limpiar($_POST['nombre_cliente']),
                'direccion' => $this->limpiar($_POST['direccion']),
                'item_producto' => $producto['item'],
                'descripcion_producto' => $producto['descripcion'],
                'unidad' => $producto['unidad'] ?? 'UND',
                'kg' => $producto['kg'] ?? 0,
                'motivo' => $this->limpiar($_POST['motivo']),
                'cantidad_und' => floatval($_POST['cantidad_und']),
                'cantidad_kg' => floatval($_POST['cantidad_kg']),
                'observacion' => $this->limpiar($_POST['observacion']),
                'usuario_creador' => $_SESSION['user'],
                'evidencia' => $rutaEvidencia
            ];
            
            // 5. Guardar en la base de datos
            if ($this->devModel->guardar($datos)) {
                $_SESSION['alerta'] = [
                    'tipo' => 'success', 
                    'msg' => '✅ Devolución registrada correctamente. ID de registro generado.'
                ];
            } else {
                throw new Exception('Error al guardar en la base de datos');
            }
            
        } catch (Exception $e) {
            $_SESSION['alerta'] = [
                'tipo' => 'error', 
                'msg' => '❌ ' . $e->getMessage()
            ];
        }
        
        // Redirigir de vuelta al formulario
        header('Location: index.php?url=panel/auxiliar');
        exit;
    }
}

validarCampos()

private function validarCampos(array $post): void

Validates all required form fields and quantity constraints. Parameters:

post

array

required

$_POST array from form submission

Validation Rules:

$camposRequeridos = [
    'nit' => 'NIT del cliente',
    'nombre_cliente' => 'Nombre del cliente',
    'direccion' => 'Dirección',
    'producto' => 'Producto',
    'motivo' => 'Motivo',
    'cantidad_und' => 'Cantidad en unidades',
    'cantidad_kg' => 'Cantidad en kilogramos',
    'observacion' => 'Observaciones'
];

Exceptions Thrown:

Exception Message	Cause
`El campo '{nombre}' es obligatorio`	Required field is empty
`La cantidad en unidades debe ser mayor a 0`	cantidad_und ≤ 0
`La cantidad en kilogramos no puede ser negativa`	cantidad_kg < 0

Source Code:

private function validarCampos($post) {
    $camposRequeridos = [
        'nit' => 'NIT del cliente',
        'nombre_cliente' => 'Nombre del cliente',
        'direccion' => 'Dirección',
        'producto' => 'Producto',
        'motivo' => 'Motivo',
        'cantidad_und' => 'Cantidad en unidades',
        'cantidad_kg' => 'Cantidad en kilogramos',
        'observacion' => 'Observaciones'
    ];
    
    foreach ($camposRequeridos as $campo => $nombre) {
        if (empty($post[$campo])) {
            throw new Exception("El campo '{$nombre}' es obligatorio");
        }
    }
    
    // Validar que las cantidades sean números positivos
    if (floatval($post['cantidad_und']) <= 0) {
        throw new Exception('La cantidad en unidades debe ser mayor a 0');
    }
    
    if (floatval($post['cantidad_kg']) < 0) {
        throw new Exception('La cantidad en kilogramos no puede ser negativa');
    }
}

subirEvidencia()

private function subirEvidencia(array $archivo): string

Handles secure file upload for evidence images with validation and unique naming. Parameters:

archivo

array

required

$_FILES[‘evidencia’] array from file upload

Return Value:

return

string

Relative path to uploaded file (e.g., uploads/evidencias/evidencia_1234567890_abc123.jpg)

Upload Configuration:

$directorioDestino = 'uploads/evidencias/';
$tamañoMaximo = 5 * 1024 * 1024; // 5MB
$extensionesPermitidas = ['jpg', 'jpeg', 'png', 'gif'];

Validation Checks:

File Size Validation
- Maximum: 5MB (5,242,880 bytes)
- Throws: "El archivo excede el tamaño máximo de 5MB"
File Extension Validation
- Allowed: JPG, JPEG, PNG, GIF (case-insensitive)
- Throws: "Formato de archivo no permitido. Use JPG, PNG o GIF"
Upload Success Check
- Verifies move_uploaded_file() success
- Throws: "Error al subir el archivo de evidencia"

Directory Creation: Automatically creates uploads/evidencias/ directory if it doesn’t exist:

if (!file_exists($directorioDestino)) {
    mkdir($directorioDestino, 0777, true);
}

Security Considerations:

Directory permissions 0777 are overly permissive - consider 0755
No MIME type validation - only extension checked
No image content validation - malicious files could be renamed
Consider implementing:
- MIME type checking with mime_content_type()
- Image reprocessing with GD/Imagick
- Virus scanning for production

Source Code:

private function subirEvidencia($archivo) {
    // Configuración
    $directorioDestino = 'uploads/evidencias/';
    $tamañoMaximo = 5 * 1024 * 1024; // 5MB
    $extensionesPermitidas = ['jpg', 'jpeg', 'png', 'gif'];
    
    // Crear directorio si no existe
    if (!file_exists($directorioDestino)) {
        mkdir($directorioDestino, 0777, true);
    }
    
    // Validar tamaño
    if ($archivo['size'] > $tamañoMaximo) {
        throw new Exception('El archivo excede el tamaño máximo de 5MB');
    }
    
    // Validar extensión
    $extension = strtolower(pathinfo($archivo['name'], PATHINFO_EXTENSION));
    if (!in_array($extension, $extensionesPermitidas)) {
        throw new Exception('Formato de archivo no permitido. Use JPG, PNG o GIF');
    }
    
    // Generar nombre único
    $nombreArchivo = 'evidencia_' . time() . '_' . uniqid() . '.' . $extension;
    $rutaCompleta = $directorioDestino . $nombreArchivo;
    
    // Mover archivo
    if (move_uploaded_file($archivo['tmp_name'], $rutaCompleta)) {
        return $rutaCompleta;
    } else {
        throw new Exception('Error al subir el archivo de evidencia');
    }
}

Example File Upload HTML:

<form action="index.php?url=panel/registrar" method="POST" enctype="multipart/form-data">
    <label>Evidencia fotográfica (opcional)</label>
    <input type="file" name="evidencia" accept=".jpg,.jpeg,.png,.gif">
    <small>Máximo 5MB - Formatos: JPG, PNG, GIF</small>
    
    <!-- Other form fields... -->
    
    <button type="submit">Registrar Devolución</button>
</form>

limpiar()

private function limpiar(string $texto): string

Sanitizes and escapes text input to prevent XSS attacks. Parameters:

texto

string

required

Raw text input from user

Return Value:

return

string

Trimmed and HTML-escaped text safe for output

Processing Steps:

Trim whitespace - Removes leading/trailing spaces
HTML encode - Converts special characters to HTML entities
Quote escaping - Escapes both single and double quotes
UTF-8 encoding - Ensures proper character encoding

Implementation:

return htmlspecialchars(trim($texto), ENT_QUOTES, 'UTF-8');

Character Conversion Examples:

Input	Output
`<script>alert('XSS')</script>`	`<script>alert('XSS')</script>`
`Cliente "Premium"`	`Cliente "Premium"`
`O'Reilly & Sons`	`O'Reilly & Sons`

This method protects against XSS attacks but does NOT prevent SQL injection. Always use prepared statements in Model classes for database queries.

Source Code:

private function limpiar($texto) {
    return htmlspecialchars(trim($texto), ENT_QUOTES, 'UTF-8');
}

Complete Usage Example

Registration Form HTML

<form action="index.php?url=panel/registrar" method="POST" enctype="multipart/form-data">
    <!-- Customer Information -->
    <input type="text" name="nit" placeholder="NIT del cliente" required>
    <input type="text" name="nombre_cliente" placeholder="Nombre completo" required>
    <input type="text" name="direccion" placeholder="Dirección" required>
    
    <!-- Product Selection -->
    <select name="producto" required>
        <option value="">Seleccione un producto</option>
        <?php foreach ($productos as $prod): ?>
            <option value="<?= $prod['item'] ?>">
                <?= $prod['item'] ?> - <?= $prod['descripcion'] ?>
            </option>
        <?php endforeach; ?>
    </select>
    
    <!-- Return Details -->
    <input type="text" name="motivo" placeholder="Motivo de devolución" required>
    <input type="number" step="0.01" name="cantidad_und" placeholder="Cantidad (unidades)" required>
    <input type="number" step="0.01" name="cantidad_kg" placeholder="Cantidad (kg)" required>
    
    <!-- Observations -->
    <textarea name="observacion" placeholder="Observaciones" required></textarea>
    
    <!-- Evidence Upload -->
    <input type="file" name="evidencia" accept=".jpg,.jpeg,.png,.gif">
    
    <button type="submit">Registrar Devolución</button>
</form>

<!-- Display Alert Message -->
<?php if (isset($_SESSION['alerta'])): ?>
    <div class="alert alert-<?= $_SESSION['alerta']['tipo'] ?>">
        <?= $_SESSION['alerta']['msg'] ?>
    </div>
    <?php unset($_SESSION['alerta']); ?>
<?php endif; ?>

Error Handling Summary

Validation Errors:

Error Message	Cause
`Debe seleccionar un producto`	Empty product field
`Producto no encontrado`	Invalid product item code
`El campo '{nombre}' es obligatorio`	Missing required field
`La cantidad en unidades debe ser mayor a 0`	cantidad_und ≤ 0
`La cantidad en kilogramos no puede ser negativa`	cantidad_kg < 0
`El archivo excede el tamaño máximo de 5MB`	File too large
`Formato de archivo no permitido...`	Invalid file extension
`Error al subir el archivo de evidencia`	File upload failed
`Error al guardar en la base de datos`	Database save failed

Error Display: All errors are caught, stored in $_SESSION['alerta'], and displayed on the form page after redirect.

AuthController - Authentication (required for access)
AdminController - Review registered returns
ConsultaController - View return history
ProductoModel - Product catalog queries
DevolucionModel - Return data persistence

Controllers

Models

Overview

Constructor

Methods

auxiliar()

registrar()

validarCampos()

subirEvidencia()

limpiar()

Complete Usage Example

Registration Form HTML

Error Handling Summary

Build docs developers (and LLMs) love

Controllers

Models

Documentation Index

​Overview

​Constructor

​Methods

​auxiliar()

​registrar()

​validarCampos()

​subirEvidencia()

​limpiar()

​Complete Usage Example

​Registration Form HTML

​Error Handling Summary

​Related Components

Build docs developers (and LLMs) love

Overview

Constructor

Methods

auxiliar()

registrar()

validarCampos()

subirEvidencia()

limpiar()

Complete Usage Example

Registration Form HTML

Error Handling Summary

Related Components