Dsn Laravel Package

Product Decisions This Supports

A narrow but real enabler for queue portability. enqueue/dsn is not a queue implementation — it converts a DSN string (amqp://user:pass@host:5672/%2f, redis://…, sqs://…) into a structured, scheme-aware set of connection parameters. For a PM, its value is in the decisions it unblocks, not in the code it ships.

• Multi-broker flexibility / vendor de-risking. If we keep queue connection details in DSN form (env vars, tenant config, admin-entered settings), this package makes swapping providers — self-hosted RabbitMQ in dev, AWS SQS or a managed Redis in production — a configuration change rather than a code change. That is a negotiating lever with vendors and an insurance policy against pricing or reliability surprises.
• Environment parity and config hygiene. One parser across local, staging, and production removes a class of "works on my machine" bugs. It also enables early validation: fail the deploy fast on a malformed DSN instead of at first message publish.
• Build vs. buy: here the answer is buy — but the purchase is tiny. Reimplementing DSN parsing (userinfo, encoded vhosts, IPv6 hosts, sentinel lists, query-string options) is a classic source of subtle, expensive bugs. Adopting a ~100-line MIT-licensed utility is cheaper than a sprint task and cheaper still than the incident it prevents.
• Roadmap unlock for user-facing queue configuration. If any roadmap item involves letting customers or admins point us at their broker (white-label, BYO-infrastructure, enterprise deployments), a validated DSN parser is a prerequisite building block. It is the parsing layer of that feature, not the feature itself.
• Scoping sanity. This package does not give us retries, dead-letter queues, backoff, or a worker model — that is the rest of the Enqueue ecosystem, or Laravel's native queue. Deciding to adopt this should not be mistaken for a decision to adopt Enqueue as our messaging stack; treat those as two separate calls.

When to Consider This Package

Adopt when:

• DSNs are already, or are about to become, a first-class config format in our product — env-driven queue setup, admin panels, per-tenant broker config, CLI tooling.
• The stack is PHP 7.1+ / Laravel and we either use Enqueue transports or deliberately want to stay broker-agnostic at the parsing layer.
• We need scheme-specific validation semantics (AMQP vhost handling, Redis DB index, sentinel clusters) rather than generic URL parsing. Symfony's Url or parse_url() will silently accept and mis-shape these.
• We're validating untrusted input — a malformed DSN becoming a runtime connection failure in a worker is a far worse failure mode than a rejected form submission.
• We accept a small, stable, low-churn dependency and are prepared to own it.

Look elsewhere when:

• The product uses Laravel's native queue with config/queue.php arrays. Laravel already parses its own connection strings; adding a second parser creates two sources of truth about what a valid connection is.
• We need drivers this package doesn't model well (Kafka, Pulsar, NATS, custom internal schemes). Wrapping it in scheme-specific extensions is doable, but at that point the wrapper is the product and the dependency is a liability.
• Active maintenance is a hard requirement (regulated environments, security review gates that require a maintained dependency with a responsive security contact). The package is small and stable but not actively evolving; expect to fork or vendor it.
• We need to do something with the DSN beyond parsing it — connect, retry, monitor. That's a transport decision, and should be evaluated against Enqueue's transport packages or Laravel Horizon, not this.

Honest risk read for the record: repo-level stars (~2.2k) describe the Enqueue monorepo, not this package; zero dependents and a "development repository" notice mean we should plan on vendoring or forking rather than assuming upstream support. The blast radius is small — it's a pure function with no side effects — which is exactly what makes the risk acceptable.

How to Pitch It (Stakeholders)

For executives (one paragraph): "We keep queue connection details in a standard DSN format. Adopting enqueue/dsn — a small, MIT-licensed PHP parser — lets us validate those connection strings up front and switch queue providers by changing configuration rather than code. Practically, it means less lock-in to any one broker, fewer production incidents caused by malformed connection settings, and a low-cost building block for any future feature where customers bring their own infrastructure. The cost is one small dependency and roughly a day of integration; the risk is contained because the library only parses strings — it holds no connections and no state."

For engineering (the substance):

• What it is: a scoped DSN parser — ParsedDsn::parse($dsn) returns scheme-aware components, with per-scheme handling for AMQP (including URL-encoded vhosts) and Redis (DB index, sentinel). It is not a transport, not a worker, not a retry policy.
• Where it goes: a single QueueDsn value object or service bound in a service provider, parsed once at boot and cached with the config. Everything downstream consumes the parsed struct — never the raw string.
• Guardrails we should insist on: (1) wrap the parse call and convert failures into a domain exception with the offending scheme, never the credentials; (2) unit-test the schemes we actually deploy plus IPv6 and encoded-password edge cases; (3) keep a parse_url()-based fallback behind the same interface so the dependency is swappable in an afternoon; (4) do not log raw DSNs — they contain passwords.
• Rollout: phase 1, parse-and-log in a non-critical path to confirm our real-world DSNs round-trip; phase 2, replace ad-hoc parsing in queue config; phase 3, expose validation in admin/API surfaces; phase 4, decide on vendoring if it becomes load-bearing.
• The honest caveat: upstream is a development monorepo with thin maintenance. We are adopting a stable utility with a fork contingency, not a partnership. If that framing is uncomfortable, the alternative is ~150 lines we own — which is also a legitimate answer, just not a free one.