socialdept/atp-support

What is ATP Support?

ATP Support is the foundational Laravel package for the SocialDept AT Protocol ecosystem. It provides DID and handle resolution, identity validation, AT-URI parsing, NSID utilities, and shared configuration used by all other atp-* packages.

If you're building anything on AT Protocol with Laravel, this is your starting point.

Why use ATP Support?

• Identity resolution - Resolve DIDs, handles, and PDS endpoints with intelligent caching
• Validation utilities - Validate DIDs, handles, and NSIDs with battle-tested logic
• AT-URI parsing - Parse and create at:// URIs as immutable value objects
• Shared configuration - Common AT Protocol settings (PLC directory, PDS endpoint, public API) in one place
• Extensible resolvers - Pluggable DID method resolvers with support for did:plc and did:web
• DNS lexicon resolution - Discover lexicon schemas via DNS TXT records
• Microcosm integration - Backlink discovery via Constellation and fast record caching via Slingshot

Quick Example

use SocialDept\AtpSupport\Facades\Resolver;
use SocialDept\AtpSupport\Identity;
use SocialDept\AtpSupport\AtUri;
use SocialDept\AtpSupport\Nsid;

// Resolve a handle to a DID
$did = Resolver::handleToDid('alice.bsky.social');

// Resolve a DID to its PDS endpoint
$pds = Resolver::resolvePds('did:plc:ewvi7nxzyoun6zhxrhs64oiz');

// Validate identities
Identity::isDid('did:plc:abc123');          // true
Identity::isHandle('alice.bsky.social');     // true

// Parse AT-URIs
$uri = AtUri::parse('at://did:plc:xyz/app.bsky.feed.post/3k4abc');
$uri->did;        // did:plc:xyz
$uri->collection; // app.bsky.feed.post
$uri->rkey;       // 3k4abc

// Work with NSIDs
$nsid = Nsid::parse('app.bsky.feed.post');
$nsid->getAuthority(); // app.bsky.feed
$nsid->getName();      // post

Installation

composer require socialdept/atp-support

Publish the configuration:

php artisan vendor:publish --tag=atp-support-config

Configuration

All shared AT Protocol settings live in config/atp-support.php:

return [
    'plc_directory' => env('ATP_PLC_DIRECTORY', 'https://plc.directory'),
    'pds_endpoint' => env('ATP_PDS_ENDPOINT', 'https://bsky.social'),
    'public_api' => env('ATP_PUBLIC_API', 'https://public.api.bsky.app'),
    'timeout' => env('ATP_RESOLVER_TIMEOUT', 10),
    'cache' => [
        'enabled' => env('ATP_RESOLVER_CACHE_ENABLED', true),
        'did_ttl' => env('ATP_RESOLVER_CACHE_DID_TTL', 3600),
        'handle_ttl' => env('ATP_RESOLVER_CACHE_HANDLE_TTL', 3600),
        'pds_ttl' => env('ATP_RESOLVER_CACHE_PDS_TTL', 3600),
    ],
];

Other atp-* packages read shared values like public_api directly from this config.

Usage

Resolving Identities

The Resolver facade is the main entry point for all resolution operations:

use SocialDept\AtpSupport\Facades\Resolver;

// Resolve a DID to its DID Document
$doc = Resolver::resolveDid('did:plc:ewvi7nxzyoun6zhxrhs64oiz');
$doc->getPdsEndpoint(); // https://morel.us-east.host.bsky.network
$doc->getHandle();      // alice.bsky.social

// Convert a handle to a DID
$did = Resolver::handleToDid('alice.bsky.social');

// Auto-detect and resolve (accepts both DIDs and handles)
$doc = Resolver::resolveIdentity('alice.bsky.social');

// Resolve directly to PDS endpoint
$pds = Resolver::resolvePds('alice.bsky.social');

Caching

All resolutions are cached by default with configurable TTLs. You can bypass or clear the cache:

// Bypass cache for a single call
$doc = Resolver::resolveDid('did:plc:abc123', useCache: false);

// Clear specific caches
Resolver::clearDidCache('did:plc:abc123');
Resolver::clearHandleCache('alice.bsky.social');
Resolver::clearPdsCache('did:plc:abc123');

// Clear everything
Resolver::clearCache();

Validating Identities

The Identity class provides static validation methods:

use SocialDept\AtpSupport\Identity;

Identity::isDid('did:plc:abc123');     // true
Identity::isDid('not-a-did');          // false

Identity::isHandle('alice.bsky.social'); // true
Identity::isHandle('invalid');           // false

Identity::isPlcDid('did:plc:abc123');  // true
Identity::isWebDid('did:web:example.com'); // true

Identity::extractDidMethod('did:plc:abc123'); // "plc"

Parsing AT-URIs

The AtUri value object parses the at:// URI format used throughout AT Protocol:

use SocialDept\AtpSupport\AtUri;

$uri = AtUri::parse('at://did:plc:xyz/app.bsky.feed.post/3k4abc');

$uri->did;        // did:plc:xyz
$uri->collection; // app.bsky.feed.post
$uri->rkey;       // 3k4abc

// Create programmatically
$uri = AtUri::make('did:plc:xyz', 'app.bsky.feed.post', '3k4abc');
echo $uri; // at://did:plc:xyz/app.bsky.feed.post/3k4abc

// Returns null for invalid URIs
AtUri::parse('not-a-uri'); // null

Working with NSIDs

Namespace Identifiers are the reversed-domain notation used for AT Protocol collections and methods:

use SocialDept\AtpSupport\Nsid;

$nsid = Nsid::parse('app.bsky.feed.post');

$nsid->getAuthority();       // app.bsky.feed
$nsid->getName();            // post
$nsid->getSegments();        // ['app', 'bsky', 'feed', 'post']
$nsid->toDomain();           // post.feed.bsky.app
$nsid->getAuthorityDomain(); // feed.bsky.app

// Validation
Nsid::isValid('app.bsky.feed.post');  // true
Nsid::isValid('invalid');             // false

// Equality
$nsid->equals(Nsid::parse('app.bsky.feed.post')); // true

DNS Lexicon Resolution

Discover lexicon schemas published via DNS TXT records:

use SocialDept\AtpSupport\Resolvers\LexiconDnsResolver;

$resolver = app(LexiconDnsResolver::class);

// Full pipeline: DNS lookup -> DID resolution -> XRPC fetch
$schema = $resolver->resolve('com.example.myrecord');

// Individual steps
$did = $resolver->lookupDns('example.com');
$schema = $resolver->retrieveSchema($pdsEndpoint, $did, 'com.example.myrecord');

Microcosm

Microcosm.blue provides protocol-level content discovery APIs for AT Protocol. ATP Support includes HTTP clients for two Microcosm services:

• Constellation - Backlink indexing: find all records that link to a given subject
• Slingshot - Fast record and identity caching

Constellation (Backlinks)

use SocialDept\AtpSupport\Microcosm\ConstellationClient;

$constellation = app(ConstellationClient::class);

// Find all likes on a post
$backlinks = $constellation->getBacklinks(
    subject: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3mcibiyf7fs2r',
    source: 'app.bsky.feed.like:subject.uri',
    limit: 50,
);

$backlinks->total;   // 2852
$backlinks->records; // BacklinkReference[]
$backlinks->cursor;  // Pagination cursor

// Get just the count
$count = $constellation->getBacklinksCount(
    subject: 'at://did:plc:abc/app.bsky.feed.post/rk1',
    source: 'app.bsky.feed.like:subject.uri',
);

// Get a summary of all link types pointing at a target
$summary = $constellation->getAllLinks('at://did:plc:abc/app.bsky.feed.post/rk1');
$summary->total();                              // Total records across all types
$summary->forCollection('app.bsky.feed.like');  // Filter to likes

The source parameter uses collection:path format, where the path is the dot-notation location of the linking field within the record.

Slingshot (Record Cache)

use SocialDept\AtpSupport\Microcosm\SlingshotClient;

$slingshot = app(SlingshotClient::class);

// Fetch a cached record
$record = $slingshot->getRecord('did:plc:abc', 'app.bsky.feed.post', 'rk1');
$record->uri;   // AT-URI
$record->cid;   // Content ID
$record->value; // Record data

// Fetch by AT-URI
$record = $slingshot->getRecordByUri('at://did:plc:abc/app.bsky.feed.post/rk1');

// Resolve a minimal identity document
$doc = $slingshot->resolveMiniDoc('did:plc:z72i7hdynmk6r22z27h6tvur');
$doc->did;        // did:plc:z72i7hdynmk6r22z27h6tvur
$doc->handle;     // bsky.app
$doc->pds;        // https://puffball.us-east.host.bsky.network
$doc->signingKey; // Public signing key

Microcosm Facade

Access both clients through a single facade:

use SocialDept\AtpSupport\Facades\Microcosm;

Microcosm::constellation()->getBacklinks(...);
Microcosm::slingshot()->getRecord(...);

Microcosm Configuration

Add these environment variables to customize endpoints:

ATP_CONSTELLATION_URL=https://constellation.microcosm.blue
ATP_CONSTELLATION_TIMEOUT=10
ATP_SLINGSHOT_URL=https://slingshot.microcosm.blue
ATP_SLINGSHOT_TIMEOUT=5

Custom DID Resolvers

Register custom resolvers for additional DID methods:

use SocialDept\AtpSupport\Contracts\DidResolver;
use SocialDept\AtpSupport\Data\DidDocument;

class CustomDidResolver implements DidResolver
{
    public function resolve(string $did): DidDocument
    {
        // Your resolution logic
    }

    public function supports(string $method): bool
    {
        return $method === 'custom';
    }
}

// Register in a service provider
$manager = app(DidResolverManager::class);
$manager->register('custom', new CustomDidResolver());

API Reference

Facade Methods

Value Objects

Microcosm

Validation

Exceptions

Requirements

• PHP 8.2+
• Laravel 11+

Resources

• AT Protocol Documentation
• DID Specification
• AT-URI Specification
• NSID Specification

Support & Contributing

Found a bug or have a feature request? Open an issue.

Want to contribute? We'd love your help! Check out the contribution guidelines.

Credits

• Miguel Batres - founder & lead maintainer
• All contributors

License

ATP Support is open-source software licensed under the MIT license.

Built for the Atmosphere • By Social Dept.