README

Paquete Composer de short links + códigos QR para aplicaciones Laravel.

Versión: 1.2.0
Requisitos: PHP ^8.3, Laravel ^11|^12|^13
Repositorio: github.com/Richard-Roman/short-links-qr
Packagist: packagist.org/packages/richard-roman/short-links-qr

Instalación

Packagist (recomendado)

composer require richard-roman/short-links-qr:^1.2
composer require endroid/qr-code:^6.0

VCS (sin Packagist)

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/Richard-Roman/short-links-qr"
        }
    ],
    "require": {
        "richard-roman/short-links-qr": "^1.2",
        "endroid/qr-code": "^6.0"
    }
}

El paquete se auto-descubre vía ShortLinksServiceProvider. Ejecutar migraciones:

php artisan migrate

Configuración (opcional)

php artisan vendor:publish --tag=short-links-config

Claves principales en config/short-links.php:

Clave	Default	Descripción
`route_prefix`	`l`	Prefijo de rutas públicas
`qr_generator`	`RichardRoman\ShortLinks\Laravel\Qr\EndroidQrGenerator::class`	Clase del generador de QR a resolver desde el contenedor
`throttle`	`120,1`	Rate limit redirect/QR
`cache.ttl`	`3600`	TTL cache de URL resuelta (seg)
`cache.prefix`	`short_link_redirect:`	Prefijo clave cache
`generator.length`	`8`	Longitud de códigos auto-generados
`generator.charset`	charset sin ambiguos	Caracteres del generador aleatorio
`route_pattern`	`[a-hjkmnp-z2-9]{8}`	Regex Laravel `where()` + validación de códigos

Variables de entorno opcionales: SHORT_LINKS_LENGTH, SHORT_LINKS_CHARSET, SHORT_LINKS_ROUTE_PATTERN.

v1.1.0 — Códigos configurables y manuales

Actualización semver minor compatible con v1.0: sin overrides en .env, el comportamiento es idéntico a 1.0.0.

Código manual opcional

$shortLink = ShortLinks::create(
    urlDestino: 'https://example.com/recurso',
    titulo: 'Demo',
    codigo: 'K7MNP2WX', // normalizado a minúsculas; debe cumplir route_pattern
);

Si el código no cumple route_pattern, se lanza InvalidCodeFormatException. Si ya existe, DuplicateCodeException sin reintentos aleatorios.

Personalizar generador y patrón de ruta

SHORT_LINKS_LENGTH=5
SHORT_LINKS_CHARSET=abc
SHORT_LINKS_ROUTE_PATTERN=[abc]{5}

El generador y las rutas públicas MUST usar el mismo route_pattern.

Actualizar desde v1.1

composer require richard-roman/short-links-qr:^1.2

No requiere migraciones nuevas. Ver CHANGELOG.md para el detalle completo.

v1.2.0 — Gestión del ciclo de vida de enlaces

Actualización semver minor compatible con v1.1: sin cambios en .env ni migraciones.

Redirección asíncrona

El registro de clicks ya no bloquea el response HTTP. Se despacha en background vía ProcessShortLinkClickJob. Requerís un driver de cola configurado:

QUEUE_CONNECTION=database  # o redis, sqs, etc.

Desactivar un enlace

// Marca el link como inactivo e invalida su caché de redirección.
ShortLinks::deactivate('k7mn2wxp');

// A partir de este momento GET /l/k7mn2wxp retorna 404.

Rotación atómica de enlace

Desactiva el viejo y crea el nuevo en una única transacción de base de datos. Si la creación del nuevo falla, el viejo permanece activo (rollback automático).

// Rotación con código auto-generado
$nuevoLink = ShortLinks::rotate('codigo-viejo');

// Rotación con código manual
$nuevoLink = ShortLinks::rotate('codigo-viejo', 'codigo-nuevo');

// El nuevo link hereda: urlDestino, entidadTipo, entidadId, titulo, creadoPorId
echo $nuevoLink->codigo; // "codigo-nuevo"

Si el código viejo no existe o está inactivo, lanza ShortLinkNotFoundException.

Uso básico

Crear short links (Facade)

use RichardRoman\ShortLinks\Laravel\Facades\ShortLinks;

$shortLink = ShortLinks::create(
    urlDestino: 'https://www.youtube.com/watch?v=abc123',
    titulo: 'Video demo',
    entidadTipo: 'entregable',
    entidadId: $entregableId,
    creadoPorId: auth()->id(),
);

$existente = ShortLinks::findByEntity('entregable', $entregableId);

Rutas públicas (auto-registradas)

GET /l/{codigo} → redirect 302 seguro + analytics
GET /l/{codigo}/qr → PNG 300×300 del short URL

Nombres de ruta: short-links.redirect, short-links.qr.

Importante: registrar el ServiceProvider antes de rutas catch-all del host (p. ej. /blog).

Entity resolvers (host)

El paquete no conoce modelos de la app. Registrar resolvers en AppServiceProvider::boot():

use App\ShortLinks\Resolvers\EntregableEntityResolver;
use App\ShortLinks\Resolvers\ProyectoEntityResolver;

$this->app->tag([
    ProyectoEntityResolver::class,
    EntregableEntityResolver::class,
], 'short-links.entity-resolvers');

Cada resolver implementa RichardRoman\ShortLinks\Contracts\EntityResolverInterface:

public function supports(string $entidadTipo): bool;
public function resolveUrl(string $entidadId): ?string;

Cache de redirect

Tras resolver la URL (resolver host o url_destino), se cachea por codigo. La cache se invalida al desactivar un link.

QR

Requiere endroid/qr-code en el proyecto consumidor. Sin la dependencia, GET /l/{codigo}/qr responde 503.

Ejemplo multi-app

App A (app-web): resolvers producto, factura, entregable.
App B (blog): resolver articulo opcional; links externos solo con url_destino.

Misma instalación Composer; distintos resolvers taggeados por host.

Desarrollo local

git clone https://github.com/Richard-Roman/short-links-qr.git
cd short-links-qr
composer install
composer validate --strict
composer test

Path repository (monorepo dev)

{
    "repositories": [
        {
            "type": "path",
            "url": "../short-links-qr",
            "options": { "symlink": true }
        }
    ],
    "require": {
        "richard-roman/short-links-qr": "@dev"
    }
}

Estructura

src/Contracts/     ← interfaces
src/Core/          ← PHP (servicios, VOs, validación)
src/Laravel/       ← Eloquent, rutas, Facade, QR endroid
tests/Unit/        ← tests
tests/Feature/     ← Orchestra Testbench

Licencia

MIT — ver LICENSE.

richard-roman / short-links-qr

Maintainers

Package info

Statistics

Security