README

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

Versión: 1.1.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.1
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.1",
        "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:

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.0

composer require richard-roman/short-links-qr:^1.1
php artisan migrate

Ver CHANGELOG.md para el detalle completo.

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.