⭐ Found this useful? Install it from Packagist and give it a star on GitHub: it helps us maintain and improve the project.
Short links for Symfony: per-tenant short codes behind a public stateless redirect (/s/{code}), a target guard
(OutboundUrlGuard + denylist), a privacy-preserving click log with daily rollups and retention, a PHP API for generated
links (e-mail sends) and a UiKit + FormKit management UI.
Standard Symfony by default, DDD / hexagonal opt-in: zero configuration in a standard project; public ports are interfaces and value objects with no Symfony, Doctrine or HTTP types, the bundle-owned tables are mapped in XML (with an attribute twin) and referenced by id, and the bundle never flushes your EntityManager.
🚧 Status: built slice by slice from its design contract (docs/CONTRACT.md, v1.0 for spec 230 Block A): S1 (domain + persistence) and S2 (redirect + click log) are in review; statistics and the UI follow (docs/ROADMAP.md). First tag: 0.1.0, after its security audit.
📋 Compatible with Symfony 7.4, 8.0 and 8.1 · PHP 8.2+ (Symfony 8.x requires PHP 8.4+)
This bundle is FrankenPHP worker mode friendly.
Slices S1–S4 (contract v1.0): the PHP API, the redirect, statistics and the management UI; 1.0.0 after the audit.
- FrankenPHP worker mode, kernel kept alive and not reset: readonly services, no memo of codes, links, tenants or IPs; a worker test (one kernel, thousands of requests over two tenants, flat memory) (docs/FRANKENPHP-WORKER-AUDIT.md).
- Codes: random base62 (7 characters, case-sensitive, offensive-substring blocklist) or custom
[a-z0-9-]{3,32}, unique per instance, reserved words, deleted codes quarantined for 365 days. - Redirect
GET|HEAD /s/{code}: stateless (no session, no cookie), one indexed lookup, neutral identical 404 for every failure, per-IP miss / hit limiters,no-store+no-referrerheaders, p95 < 20 ms budget. - Target guard: http(s) only, no userinfo, no private / link-local / metadata targets (DNS check at save through OutboundUrlGuard, literal checks on every redirect), host denylist port, self-chain refusal, daily recheck command.
- Click log: truncated IP (/24, /48), browser family, referrer host, optional country, machine flag for scanners and link previews, Global Privacy Control honoured, raw rows kept 90 days, daily rollups kept.
- Multi-tenant: every call takes a tenant key; host ports for tenant context, view / manage access, plan quota
(exact with
symfony/lock), denylist and country. - Generated links:
createMany()for e-mail sends (kindemail, send ref + label + position, deduplicated), clicks per send throughbySource(), GDPR export / erasure per send, tenant and actor. - UI on UiKit + FormKit: list, create / edit, disable / enable / delete, stats with a chart and breakdowns, CSV.
composer require nowo-tech/short-link-bundleSee docs/INSTALLATION.md.
# config/packages/nowo_short_link.yaml
nowo_short_link:
public_base_url: '%env(DEFAULT_URI)%'
ui:
enabled: falseEvery key of the contract is already accepted (strict tree): docs/CONFIGURATION.md.
- PHP >= 8.2, < 8.6 (Symfony 8.x needs PHP 8.4+)
- Symfony 7.4, 8.0 or 8.1
- Doctrine DBAL 3.8+ / 4 and ORM 3.7+ with DoctrineBundle
nowo-tech/ui-kit-bundle^2.49,nowo-tech/form-kit-bundle^2.22,nowo-tech/outbound-url-guard-bundle^1.5
demo/symfony7 (Symfony 7.4, http://localhost:8230) and demo/symfony8 (Symfony 8.1, http://localhost:8231):
FrankenPHP worker mode, MySQL, UiKit layout and FormKit forms, Web Profiler, Twig Inspector and Hot Reload
(make -C demo up-symfony8), management UI under /short-links. Playwright e2e: make test-e2e; screenshots:
make demo-screenshots. See docs/DEMO-FRANKENPHP.md.
- Installation
- Configuration
- Usage
- Contributing
- Code of Conduct
- Changelog
- Upgrading
- Release
- Security
- Engram
- Spec-driven development
- GitHub Spec Kit
- Roadmap
- Contract v1.0 (spec 230 Block A)
- Architecture
- FrankenPHP worker audit
- Performance
- Privacy
- Demo with FrankenPHP
- PSR compliance
- GitHub CI
make test # PHPUnit in Docker
make test-coverage-100 # fails below 100 % of src/
make test-with-db # Database suite on MySQL 8.4
make release-check # every gate, demos included- PHP: 100 % of
src/(gate in CI). Database suite on SQLite, MySQL 8.4, MariaDB 10.11 and PostgreSQL 17 in CI.
MIT. See LICENSE.
Created by Héctor Franco Aceituno at Nowo.tech.


