PHPackages                             versadumps-php/versadumps-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. versadumps-php/versadumps-php

ActiveLibrary[Logging & Monitoring](/categories/logging)

versadumps-php/versadumps-php
=============================

Librería PHP moderna para enviar dumps a versaDumps Visualizer con Builder Pattern, métodos semánticos, stack traces y 10 colores predefinidos

2.2.2(8mo ago)034MITPHPPHP >=8.1

Since Aug 30Pushed 4mo agoCompare

[ Source](https://github.com/kriollo/versadumps-php)[ Packagist](https://packagist.org/packages/versadumps-php/versadumps-php)[ GitHub Sponsors](https://github.com/sponsors/kriollo)[ RSS](/packages/versadumps-php-versadumps-php/feed)WikiDiscussions main Synced today

READMEChangelog (9)Dependencies (3)Versions (10)Used By (0)

VersaDumps PHP
==============

[](#versadumps-php)

[![PHP](https://camo.githubusercontent.com/c0761d101b201f2531c8037e6264420e2e43705d3776a9fcfb70c8cf3d3563a3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d3737374242342e737667)](#)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](#)[![Status](https://camo.githubusercontent.com/d6e6f3c53998470e14568ffca92b1e716677fb539b5bcf450f0a4900889f3ca9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d737461626c652d627269676874677265656e2e737667)](#)[![Version](https://camo.githubusercontent.com/daeda6626a8ed2021937aa2fba0e8b1053f26401c5a3c200ccfbf12507e0a1b8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d322e322e302d626c75652e737667)](#)

VersaDumps PHP es una librería moderna para enviar "dumps" (estructuras de datos, mensajes, depuración, etc.) a un visualizador VersaDumps con características avanzadas como:

✨ **Características principales:**

- 🎨 **Patrón Builder** con interfaz fluida para configuración avanzada
- 🏷️ **Auto-detección de nombres de variables** para debugging más intuitivo
- 🎯 **Métodos semánticos** (info, success, warning, error) para clasificación visual
- 🔍 **Stack traces** opcionales para debugging profundo
- 🎨 **10 colores predefinidos** para categorización visual
- 🚀 **Ejecución condicional** (if, unless, once) para optimización
- ⚡ **Control de profundidad** para serialización eficiente de estructuras complejas

Este README explica cómo instalar y usar el paquete tanto desde el repositorio como vía Composer, cómo ejecutar el helper CLI para crear la configuración inicial y cómo integrar la función global `vd()` en tus proyectos.

Requisitos
----------

[](#requisitos)

- PHP >= 8.1
- ext-json
- Composer

Instalación
-----------

[](#instalación)

Puedes instalar el paquete de dos formas:

### 1) Instalar desde Composer (recomendado)

[](#1-instalar-desde-composer-recomendado)

Desde tu proyecto, ejecuta:

```
composer require versadumps-php/versadumps-php
```

Composer descargará el paquete y sus dependencias.

Después de instalado, hay dos formas de inicializar el archivo de configuración `versadumps.yml`:

- Ejecutar el script instalado en `vendor/bin`:

```
# Windows / pwsh
php vendor/bin/versadumps-init

# o si Composer >= 2.1
composer exec versadumps-init --
```

- O añadir un script en el `composer.json` de tu proyecto para ejecutar más cómodo:

```
"scripts": {
  "versadumps-init": "vendor/bin/versadumps-init"
}
```

Y luego:

```
composer run-script versadumps-init
```

> Nota: `composer run-script versadumps-init` funciona solo si el script está definido en el composer.json del proyecto donde lo ejecutas.

### 2) Instalar desde el repositorio (desarrollo)

[](#2-instalar-desde-el-repositorio-desarrollo)

Clona el repositorio y, desde la raíz del proyecto, ejecuta:

```
git clone https://github.com/kriollo/versadumps-php.git
cd versadumps-php
composer install
```

Puedes ejecutar el bin localmente:

```
php bin/versadumps-init
```

Uso básico
----------

[](#uso-básico)

El paquete expone una función global llamada `vd()` que soporta dos estilos de uso: **tradicional** y **moderno** (builder pattern).

### 1. Asegúrate de requerir el autoload

[](#1-asegúrate-de-requerir-el-autoload)

```
require 'vendor/autoload.php';
```

### 2. Estilo tradicional (compatible con versiones anteriores)

[](#2-estilo-tradicional-compatible-con-versiones-anteriores)

```
// Con etiqueta explícita
vd("Usuario", ['nombre' => 'Juan', 'edad' => 30]);
vd("mensaje", 'Un mensaje simple');

// Auto-detección del nombre de variable
vd($usuarios); // Se envía con label "usuarios"
```

### 3. Estilo moderno (Builder Pattern) ⭐

[](#3-estilo-moderno-builder-pattern-)

```
// Uso básico con auto-detección
vd($usuarios)->send();

// Con etiqueta personalizada
vd($data)->label('Datos importantes')->send();

// Métodos semánticos para clasificación visual
vd($user)->success(); // Color verde - operación exitosa
vd($error)->error();  // Color rojo - error crítico
vd($info)->info();    // Color azul - información general
vd($alert)->warning(); // Color amarillo - advertencia

// Stack trace para debugging
vd($variable)->trace(5); // Incluye 5 niveles de stack trace

// Control de profundidad para estructuras complejas
vd($deepObject)->depth(3); // Limita la serialización a 3 niveles

// Ejecución condicional
vd($debug)->if($isDevelopment); // Solo se ejecuta si la condición es true
vd($data)->unless($isProduction); // Solo se ejecuta si la condición es false

// Ejecutar solo una vez (útil en loops)
vd($item)->once(); // Solo se ejecuta en la primera iteración

// Colores personalizados
vd($data)->color('purple'); // 10 colores disponibles

// Combinación de métodos (fluent interface)
vd($order)
    ->label('Pedido procesado')
    ->success()
    ->trace(3)
    ->if($debug);

// Ejecución inmediata (sin esperar al destructor)
vd($criticalData)->error()->send();
```

Métodos disponibles del Builder
-------------------------------

[](#métodos-disponibles-del-builder)

MétodoParámetrosDescripción`label(string)`Etiqueta personalizadaDefine una etiqueta explícita para el dump`trace(int)`Niveles (default: 5)Incluye stack trace con N niveles`color(string)`Nombre del colorEstablece color personalizado (red, green, blue, yellow, purple, orange, pink, cyan, gray, white)`depth(int)`Profundidad máximaLimita la profundidad de serialización`once()`-Ejecuta solo la primera vez (por archivo:línea:label)`if(bool)`CondiciónEjecuta solo si la condición es verdadera`unless(bool)`CondiciónEjecuta solo si la condición es falsa`send()`-Ejecuta inmediatamente (sin esperar al destructor)**Métodos semánticos**`info()`-Atajo para `color('blue')` - información general`success()`-Atajo para `color('green')` - operación exitosa`warning()`-Atajo para `color('yellow')` - advertencia`error()`-Atajo para `color('red')` - error crítico`important()`-Atajo para `color('orange')` - dato importante### Ejemplos prácticos

[](#ejemplos-prácticos)

```
// Debugging de API
function procesarPedido($pedido) {
    vd($pedido)->label('Pedido recibido')->info();

    try {
        $resultado = $this->procesador->procesar($pedido);
        vd($resultado)->success();
        return $resultado;
    } catch (Exception $e) {
        vd($e)->error()->trace(10);
        throw $e;
    }
}

// Debugging condicional en producción
vd($query)->if(config('app.debug'))->label('SQL Query');

// Evitar spam en loops
foreach ($items as $item) {
    vd($item)->once(); // Solo muestra el primero
}

// Análisis de estructuras complejas
vd($deepNestedObject)->depth(2)->warning(); // Limita a 2 niveles

// Sistema de logging visual
vd($user)->info()->label('Usuario autenticado');
vd($payment)->success()->label('Pago procesado');
vd($stock)->warning()->label('Stock bajo');
vd($exception)->error()->trace(5)->label('Error crítico');
```

Documentación detallada
-----------------------

[](#documentación-detallada)

Para más información sobre características avanzadas, consulta:

- **[BUILDER\_EXTENSIONS.md](BUILDER_EXTENSIONS.md)** - Documentación completa de todas las extensiones del builder
- **[SEMANTIC\_METHODS.md](SEMANTIC_METHODS.md)** - Guía rápida de métodos semánticos (info, success, warning, error)
- **[example/index.php](example/index.php)** - Ejemplos básicos de uso
- **[example/advanced.php](example/advanced.php)** - Ejemplos avanzados con todas las extensiones
- **[example/semantic-methods.php](example/semantic-methods.php)** - Ejemplos de métodos semánticos

Internamente, `vd()` delega a un singleton `Versadumps\Versadumps\VersaDumps` que envía los datos a `http://{host}:{port}/data`. Los valores por defecto se toman desde `versadumps.yml`.

Archivo de configuración `versadumps.yml`
-----------------------------------------

[](#archivo-de-configuración-versadumpsyml)

El archivo debe ubicarse en el *working directory* (getcwd) del proceso PHP. Contiene dos claves mínimas:

```
host: 127.0.0.1
port: 9191
```

Puedes crear este archivo usando el comando CLI `versadumps-init` descrito antes.

Detalles técnicos
-----------------

[](#detalles-técnicos)

- **Singleton Pattern**: La clase `VersaDumps` se implementa como singleton (`getInstance()`) para que la función global `vd()` pueda invocar siempre la misma instancia.
- **Builder Pattern**: La función `vd()` retorna un objeto `VersaDumpsBuilder` que permite encadenar métodos de configuración.
- **Lazy Execution**: El builder ejecuta automáticamente en su destructor, o puedes forzar ejecución inmediata con `send()`.
- **Auto-detección de variables**: Analiza el código fuente para inferir nombres de variables cuando no se proporciona etiqueta explícita.
- **Backward Compatible**: El estilo tradicional `vd("label", $data)` sigue funcionando sin cambios.
- **Helpers globales**: `src/helpers.php` está registrado en `composer.json` como `autoload.files` para exponer `vd()` automáticamente.
- **CLI Tool**: `bin/versadumps-init` está expuesto en `vendor/bin/` para crear configuración inicial.

Características avanzadas
-------------------------

[](#características-avanzadas)

### Variable Name Inference

[](#variable-name-inference)

```
$usuario = ['nombre' => 'Juan'];
vd($usuario); // Label automático: "usuario"

$this->datosImportantes = [1, 2, 3];
vd($this->datosImportantes); // Label automático: "datosImportantes"
```

### Once Cache (evitar duplicados)

[](#once-cache-evitar-duplicados)

```
foreach ($items as $item) {
    vd($item)->once(); // Solo el primer ítem se envía
}

// La cache usa: archivo:línea:label como clave única
```

### Conditional Execution

[](#conditional-execution)

```
// Solo en desarrollo
vd($query)->if(config('app.debug'));

// Solo en producción
vd($metrics)->unless(config('app.debug'));
```

### Depth Control

[](#depth-control)

```
$deepObject = [
    'level1' => [
        'level2' => [
            'level3' => [
                'level4' => 'deep'
            ]
        ]
    ]
];

vd($deepObject)->depth(2); // Solo muestra hasta level2
```

### Stack Traces

[](#stack-traces)

```
function problematicFunction() {
    vd($data)->trace(10); // Incluye 10 niveles del stack
}
```

Payload estructura
------------------

[](#payload-estructura)

El payload enviado al servidor VersaDumps tiene la siguiente estructura:

```
{
  "context": {
    "variables": [...],
    "line": 42,
    "file": "/path/to/file.php"
  },
  "frame": {
    "file": "/path/to/file.php",
    "line": 42,
    "caller": "MyClass::myMethod"
  },
  "label": "Usuario",
  "metadata": {
    "color": "green",
    "includeTrace": 5,
    "max_depth": 3
  }
}
```

Solución de problemas
---------------------

[](#solución-de-problemas)

### Error "Call to undefined function vd()"

[](#error-call-to-undefined-function-vd)

- Asegúrate de haber incluido `require 'vendor/autoload.php';` en tu script.
- Verifica que `src/helpers.php` esté presente en el paquete y registrado en `composer.json` como `autoload.files`.
- Si instalaste la versión publicada del paquete, ejecuta `composer dump-autoload -o` en el proyecto consumidor.

### Error "Command 'versadumps-init' is not defined"

[](#error-command-versadumps-init-is-not-defined)

- `composer run-script versadumps-init` solo funciona para scripts declarados en el composer.json del proyecto actual.
- Para usar el comando provisto por este paquete usa `php vendor/bin/versadumps-init` o `composer exec versadumps-init --`.
- Si quieres `composer run-script versadumps-init` en tu proyecto, añade un script en tu composer.json que invoque `vendor/bin/versadumps-init`.

### Error "El archivo de configuración 'versadumps.yml' no se encuentra"

[](#error-el-archivo-de-configuración-versadumpsyml-no-se-encuentra)

- Ejecuta `php vendor/bin/versadumps-init` (o `php bin/versadumps-init` si trabajas desde el repo) para crear el archivo en el directorio actual.

### El builder no ejecuta mi dump

[](#el-builder-no-ejecuta-mi-dump)

- Si no usas `send()`, el builder ejecuta automáticamente en su destructor.
- Verifica que no haya un `return` antes de que se destruya el objeto.
- Usa `send()` para forzar ejecución inmediata si es necesario.

### Los métodos semánticos no muestran colores

[](#los-métodos-semánticos-no-muestran-colores)

- Los colores deben ser soportados por tu visualizador VersaDumps.
- Verifica que el payload incluya el campo `metadata.color` en la petición HTTP.
- Asegúrate de estar usando versión 2.2.0+ de la librería.

### Stack trace demasiado largo

[](#stack-trace-demasiado-largo)

- Usa `trace(N)` con un número menor de niveles, ej: `trace(3)`.
- Por defecto se incluyen 5 niveles si no especificas parámetro.

Changelog
---------

[](#changelog)

### v2.2.0 (2025-10-28)

[](#v220-2025-10-28)

- ✨ **Nuevo**: Patrón Builder con interfaz fluida
- ✨ **Nuevo**: 13 métodos de extensión (label, trace, color, depth, once, if, unless, send, info, success, warning, error, important)
- ✨ **Nuevo**: Métodos semánticos para clasificación visual
- ✨ **Nuevo**: Ejecución condicional (if, unless, once)
- ✨ **Nuevo**: Control de profundidad de serialización
- ✨ **Nuevo**: Stack traces opcionales
- ✨ **Nuevo**: 10 colores predefinidos
- 📚 **Nuevo**: Documentación completa (BUILDER\_EXTENSIONS.md, SEMANTIC\_METHODS.md)
- 📝 **Nuevo**: Ejemplos avanzados (advanced.php, semantic-methods.php)
- 🔧 **Mejora**: Propiedades readonly en VersaDumps (PHP 8.1+)
- 🔧 **Mejora**: Valores por defecto para configuración
- 🐛 **Fix**: Eliminación de variables no utilizadas
- ♻️ **Refactor**: Mejor detección de estilo tradicional vs moderno

### v2.1.0

[](#v210)

- ✨ Auto-detección de nombres de variables
- 🔧 Mejoras en backtrace y caller frame

### v2.0.0

[](#v200)

- ✨ Parser YAML integrado
- 🔧 Soporte para objetos con método `toArray()`

### v1.x

[](#v1x)

- ✨ Implementación inicial
- ✨ Patrón Singleton
- ✨ Función global `vd()`

Contribuir
----------

[](#contribuir)

Pull requests y issues son bienvenidos. Sigue las guías de estilo de PHP y añade pruebas si agregas funciones nuevas.

Licencia
--------

[](#licencia)

MIT

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance70

Regular maintenance activity

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Recently: every ~14 days

Total

9

Last Release

246d ago

Major Versions

1.2.3 → 2.0.02025-09-02

PHP version history (2 changes)1.0.0PHP >=8.0

2.0.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/6fa569f7bd5127e75b9664c59ab9dfd5fe0ea3bc1fa40b3e0b4e3f6e9d3c8ac4?d=identicon)[kriollo](/maintainers/kriollo)

---

Top Contributors

[![kriollo](https://avatars.githubusercontent.com/u/32275426?v=4)](https://github.com/kriollo "kriollo (38 commits)")

---

Tags

debugdebuggingloggerstack tracevar\_dumpbuilder-patternvisualizerdumpssemantic-methods

###  Code Quality

Static AnalysisRector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/versadumps-php-versadumps-php/health.svg)

```
[![Health](https://phpackages.com/badges/versadumps-php-versadumps-php/health.svg)](https://phpackages.com/packages/versadumps-php-versadumps-php)
```

###  Alternatives

[analog/analog

Fast, flexible, easy PSR-3-compatible PHP logging package with dozens of handlers.

3511.6M24](/packages/analog-analog)[inpsyde/wonolog

Monolog-based logging package for WordPress.

184637.3k7](/packages/inpsyde-wonolog)[bdk/debug

Browser/javascript like console class for PHP

819.1k1](/packages/bdk-debug)[snapshotpl/zf-snap-php-debug-bar

PHP Debug Bar module for Zend Framework 2

3026.1k](/packages/snapshotpl-zf-snap-php-debug-bar)[hryha/laravel-request-logger

A Laravel package to log requests and responses

112.5k](/packages/hryha-laravel-request-logger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)