Download the PHP package socialdept/atp-parity without Composer

Bidirectional mapping between AT Protocol records and Laravel Eloquent models.

What is Parity?

Parity is a Laravel package that bridges your Eloquent models with AT Protocol records. It provides bidirectional mapping, automatic firehose synchronization, and type-safe transformations between your database and the decentralized social web.

Think of it as Laravel's model casts, but for AT Protocol records.

Why use Parity?

• Laravel-style code - Familiar patterns you already know
• Bidirectional mapping - Transform records to models and back
• Firehose sync - Automatically sync network events to your database
• Type-safe DTOs - Full integration with atp-schema generated types
• Model traits - Add AT Protocol awareness to any Eloquent model
• Flexible mappers - Define custom transformations for your domain
• Blob handling - Download, upload, and serve images and videos

Quick Example

Installation

Optionally publish the configuration:

Getting Started

Once installed, you're three steps away from syncing AT Protocol records:

1. Create a Mapper

Define how your record maps to your model:

2. Register Your Mapper

3. Add the Trait to Your Model

Your model can now convert to/from AT Protocol records and query by URI.

What can you build?

• Data mirrors - Keep local copies of AT Protocol data
• AppViews - Build custom applications with synced data
• Analytics platforms - Store and analyze network activity
• Content aggregators - Collect and organize posts locally
• Moderation tools - Track and manage content in your database
• Hybrid applications - Combine local and federated data

Ecosystem Integration

Parity is designed to work seamlessly with the other atp-* packages:

Using with atp-schema

Use generated schema classes directly with SchemaMapper:

Using with atp-client

Fetch records by URI and convert directly to models:

The helper automatically resolves the DID to find the correct PDS endpoint, so it works with any AT Protocol server - not just Bluesky.

Using with atp-signals

Enable automatic firehose synchronization by registering the ParitySignal:

Run php artisan signal:consume and your models will automatically sync with matching firehose events.

Importing Historical Data

For existing records created before you started consuming the firehose:

Or programmatically:

Documentation

For detailed documentation on specific topics:

• Record Mappers - Creating and using mappers
• Model Traits - HasAtpRecord and SyncsWithAtp
• Automatic Syncing - Auto-sync models with AT Protocol
• Blob Handling - Downloading, uploading, and serving blobs
• atp-schema Integration - Using generated DTOs
• atp-client Integration - RecordHelper and fetching
• atp-signals Integration - ParitySignal and firehose sync
• Importing - Syncing historical data

Model Traits

HasAtpRecord

Add AT Protocol awareness to your models:

Available methods:

SyncsWithAtp

Extended trait for bidirectional sync tracking:

Additional methods:

HasAtpBlobs

Add blob handling to models with images or other binary content:

Available methods:

See Blob Handling for complete documentation including MediaLibrary integration.

AutoSyncsWithAtp

Automatically sync models with AT Protocol on create, update, and delete:

When enabled, the model automatically syncs:

Failed syncs due to expired OAuth sessions can be captured and retried after re-authentication. See Automatic Syncing for complete documentation including pending sync configuration.

Database Migration

Add AT Protocol columns to your models:

Publish and run Parity's core migration:

Optional migrations are published separately based on which features you use:

Configuration

Creating Custom Records

Extend the Record base class for custom AT Protocol records:

The Record class extends atp-schema's Data and implements atp-client's Recordable interface, ensuring full compatibility with the ecosystem.

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12
• socialdept/atp-schema ^0.3
• socialdept/atp-client ^0.0
• socialdept/atp-resolver ^1.1
• socialdept/atp-signals ^1.1

Testing

Resources

• AT Protocol Documentation
• Bluesky API Docs
• atp-schema - Generated AT Protocol DTOs
• atp-client - AT Protocol HTTP client
• atp-signals - Firehose event consumer

Support & Contributing

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

Want to contribute? Check out the contribution guidelines.

Changelog

Please see changelog for recent changes.

Credits

• Miguel Batres - founder & lead maintainer
• All contributors

License

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

Built for the Atmosphere - By Social Dept.