Download the PHP package zenstruck/dsn without Composer

zenstruck/dsn

DSN parsing library with support for complex expressions:

1. URI: http://example.com?foo=bar#baz
2. Mailto: mailto:[email protected][email protected]
3. DSN Functions:
   1. Decorated: retry(inner://dsn)?times=5
   2. Group: round+robin(inner://dsn1 inner://dsn2)
   3. Complex: fail+over(rount+robin(inner://dsn1 inner://dsn2) inner://dsn3)

Installation

Usage

Parsing DSNs

For basic usage, you can use Zenstruck\Dsn::parse($mydsn). This takes a string and returns one of the following objects:

• Zenstruck\Uri
• Zenstruck\Uri\Mailto
• Zenstruck\Dsn\Decorated
• Zenstruck\Dsn\Group

The only thing in common with these returned objects is that they are all \Stringable.

If the parsing fails, a Zenstruck\Dsn\Exception\UnableToParse exception will be thrown.

Note See zenstruck/uri to view the API for Uri|Mailto.

URI

This DSN object is an instance of Zenstruck\Uri. View it's full API documentation.

Mailto

This DSN object is an instance of Zenstruck\Uri\Mailto. View it's full API documentation.

Decorated

This is a DSN Function that wraps a single inner DSN:

The above example would parse to a Zenstruck\Dsn\Decorated object with the following properties:

• Scheme/Function Name: retry
• Query: ['times' => '5']
• Inner DSN: This will be an instance of Zenstruck\Uri in this case but could be any DSN Object.

Group

This is a DSN Function that wraps a multiple inner DSNs (space separated):

The above example would parse to a Zenstruck\Dsn\Group object with the following properties:

• Scheme/Function Name: round+robin
• Query: ['strategy' => 'random']
• Child DSNs: This will be an array of 2 Zenstruck\Uri objects in this case but could an array of any DSN Objects.

Complex DSNs

You can nest Decorated DSNs to create complex expressions:

Using Parsed DSNs

Once parsed, you can use an instanceof check to determine the type of DSN that was parsed and act accordingly:

Usage Example

The best way to show how the parsed DSN could be used for something useful is with an example. Consider an email abstraction library that has multiple service transports (smtp, mailchimp, postmark) and special utility transports: round-robin (for distributing workload between multiple transports) and retry (for retrying failures x times before hard-failing).

You'd like end user's of this library to be able to create transports from a custom DSN syntax. The following is an example of a transport DSN factory:

The usage of this factory is as follows:

Advanced Usage

Under the hood Zenstruck\Dsn::parse() uses a parsing system for converting DSN strings to the packaged DSN objects. You can create your own parsers by having them implement the Zenstruck\Dsn\Parser interface.

Note Zenstruck\Dsn::parse() is a utility function that only uses the own parsers, you'll need to manually wire up a chain parser that includes them and use this for parsing DSNs.

Core Parsers

UriParser

Converts url-looking strings to Zenstruck\Uri objects.

MailtoParser

Converts mailto-looking strings to Zenstruck\Uri\Mailto objects.

WrappedParser

Converts dsn-function-looking strings to Zenstruck\Dsn\Decorated or Zenstruck\Dsn\Group objects.

Utility Parsers

ChainParser

Wraps a chain of parsers, during parse() it loops through these and attempts to find one that successfully parses a DSN string. It is considered successful if a \Stringable object is returned. If the parser throws a Zenstruck\Dsn\Exception\UnableToParse exception, the next parser in the chain is tried. Finally, if all the parsers throw UnableToParse, this is thrown.

Note This parser always contains the core parsers as the last items in the chain. Custom parsers you add to the constructor are attempted before these.

CacheParser

Wraps another parser and an instance of one of these cache interfaces:

• Symfony\Contracts\Cache\CacheInterface (Symfony cache)
• Psr\Cache\CacheItemPoolInterface (PSR-6 cache)
• Psr\SimpleCache\CacheInterface (PSR-16 cache)

The parsed object is cached (keyed by the DSN string) and subsequent parsing of the same string are retrieved from the cache. This gives a bit of a performance boost especially for complex DSNs.

Custom Parsers

You can create your own parser by creating an object that implements Zenstruck\Dsn\Parser:

Usage:

Symfony Bundle

A Symfony Bundle is provided that adds an autowireable Zenstruck\Dsn\Parser service. This is an interface with a parse(string $dsn) method. It works identically to Zenstruck\Dsn::parse() but caches the created DSN object (using cache.system) for a bit of a performance boost.

To use, enable the bundle:

Zenstruck\Dsn\Parser can be autowired:

DSN Service Factory

You can use the Zenstruck\Dsn\Parser service as a service factory to create DSN service objects:

The mailer_dsn service will be an instance of a parsed DSN object. The type depends on the value of the MAILER_DSN environment variable.

Using the mailer transport factory above, we can create the transport via a service factory that uses the mailer_dsn:

Now, when injecting App\Mailer\TransportInterface, the transport will be created by App\Mailer\TransportFactory using your MAILER_DSN environment variable.