Download the PHP package socialdept/atp-orm without Composer

Eloquent-like ORM for AT Protocol remote records in Laravel.

What is ORM?

ORM is a Laravel package that brings an Eloquent-like interface to AT Protocol remote records. Query Bluesky posts, likes, follows, and any other AT Protocol collection as if they were local database models — with built-in caching, pagination, dirty tracking, and write support.

Think of it as Eloquent, but for the AT Protocol.

Why use ORM?

• Familiar API - Query remote records with the same patterns you use for Eloquent models
• Built-in caching - Configurable TTLs with automatic cache invalidation via firehose
• Pagination - Cursor-based pagination that works out of the box
• Type-safe - Backed by atp-schema generated DTOs with full property access
• Read & write - Fetch, create, update, and delete records with authentication
• Dirty tracking - Track attribute changes just like Eloquent
• Backlink discovery - Find all records that link to a given record via Microcosm
• Slingshot support - Optionally fetch records from Slingshot cache instead of PDS
• Events - Laravel events for record lifecycle hooks
• Zero config - Works out of the box with sensible defaults

Quick Example

Installation

ORM will auto-register with Laravel. Optionally publish the config:

Defining Remote Records

Create a model class that extends RemoteRecord:

This generates:

Querying Records

Listing Records

Finding a Single Record

Pagination

ORM uses cursor-based pagination, matching the AT Protocol's native pattern:

You can also paginate manually with after():

Accessing Attributes

Records support property access, array access, and method access:

Caching

ORM caches query results automatically with configurable TTLs.

Cache TTL Resolution

TTLs are resolved in order of specificity:

1. Query-level - ->remember($ttl) on the builder
2. Model-level - $cacheTtl property on the RemoteRecord
3. Collection-level - Per-collection overrides in config
4. Global - cache.default_ttl in config

Manual Invalidation

Automatic Invalidation

When paired with atp-signals, ORM can automatically invalidate cache entries when records change on the network:

Cache Providers

ORM ships with three cache providers:

Write Operations

Write operations require an authenticated context via as():

Creating Records

Updating Records

Deleting Records

Dirty Tracking

ORM tracks attribute changes like Eloquent:

Bulk Loading with CAR Export

When you need to load an entire collection efficiently, use fromRepo() to fetch via CAR export instead of paginating through listRecords:

This uses com.atproto.sync.getRepo to fetch the repository as a CAR file and extract records locally — significantly faster for large collections.

Backlink Queries

ORM integrates with Microcosm's Constellation to discover all records that link to a given record across the entire AT Protocol network.

Basic Usage

Convenience Methods

Common Bluesky interaction types have built-in shortcuts:

Custom Sources

Query any collection and field path using source():

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

Standalone Queries

You don't need a RemoteRecord instance to query backlinks:

Link Summary

Get a summary of all link types pointing at a target at once:

Pagination

Backlink queries support cursor-based pagination:

Hydration

Hydrate backlink references into full RemoteRecord instances via Slingshot:

BacklinkCollection Helpers

Slingshot Record Source

By default, ORM fetches records directly from the user's PDS. You can optionally route through Slingshot for faster cached reads:

Or set it globally in config:

Slingshot returns the same record data as the PDS, but from a globally distributed cache. Records may be slightly stale compared to direct PDS reads.

Events

ORM fires Laravel events for record lifecycle changes:

Events can be disabled in config:

AT-URI Helper

ORM includes an AtUri helper for parsing and building AT Protocol URIs:

RemoteCollection

Query results are returned as RemoteCollection instances with a familiar collection API:

Configuration

Customize behavior in config/atp-orm.php:

Error Handling

ORM throws descriptive exceptions:

Testing

Run the test suite:

Use the ArrayCacheProvider in tests for fast, isolated caching:

Requirements

• PHP 8.2+
• Laravel 11+
• socialdept/atp-support - Identity resolution, Microcosm clients
• socialdept/atp-client - Authenticated AT Protocol HTTP client
• socialdept/atp-schema - Lexicon parsing and DTO generation

Optional

• socialdept/atp-signals - Automatic cache invalidation and CAR-based bulk loading

Resources

• AT Protocol Documentation
• Bluesky API Docs
• AT-URI Specification
• Lexicon 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

ORM is open-source software licensed under the MIT license.

Built for the Atmosphere • By Social Dept.