Atp Schema Laravel Package

Getting Started

This package provides AT Protocol schema/lexicon handling for Laravel applications. The v0.3.0 release is a namespace-only breaking change: all classes moved from SocialDept\Schema to SocialDept\AtpSchema.

Minimal upgrade/first-use steps:

1. Require the release that ships the new namespace. Verify the package name on Packagist if your composer.json still references the old package.
2. Update every import from SocialDept\Schema\... to SocialDept\AtpSchema\....
3. Dump autoload and clear Laravel caches:

composer dump-autoload
php artisan config:clear
php artisan cache:clear

Where to look first:

• src/ for the schema registry/resolver and validation entry points.
• The package service provider for bindings and config publishing.
• Tests for expected record/lexicon shapes.

First use case: validating an incoming AT Protocol record before persistence. The exact API is small but young; inspect the facade or injectable schema resolver first, then wrap it in a Laravel form request or validation rule.

use SocialDept\AtpSchema\Schema; // illustrative import; confirm exact class

$schema = Schema::for('app.bsky.feed.post');
$schema->validate($record);

If your app only consumes lexicons indirectly, start by checking whether the package exposes a validation rule or facade you can bind into existing form requests.

Implementation Patterns

Namespace migration pattern

Do a project-wide replacement before running tests:

// Before
use SocialDept\Schema\Schema;
use SocialDept\Schema\Lexicon;

// After
use SocialDept\AtpSchema\Schema;
use SocialDept\AtpSchema\Lexicon;

Search all PHP and non-PHP files, because class names often leak into config, cached payloads, and test fixtures:

grep -R "SocialDept\\\\Schema" app config database resources tests composer.json

Validation in form requests

Wrap schema validation in a form request so controllers stay clean:

public function rules(): array
{
    return [
        'record' => ['required', 'array'],
        // Add a custom rule that delegates to SocialDept\AtpSchema
    ];
}

Service-container integration

If the package exposes a schema resolver or registry, bind it in a service provider and inject it into actions/jobs rather than using static calls:

public function __construct(
    private readonly \SocialDept\AtpSchema\SchemaResolver $schemas
) {}

This makes it easier to swap lexicons in tests and avoids hard-coding schema identifiers throughout the app.

Testing pattern

Use the package to assert that fixtures match expected lexicons, and keep one happy-path plus one invalid-record test per record type. If the package provides fake or in-memory schema registration, use it to avoid network or filesystem dependencies.

Integration with queues and jobs

Validate before dispatching jobs that persist AT Protocol records. If you serialize schema objects into queued payloads, re-check after the namespace change: serialized class names from old releases will not resolve.

Gotchas and Tips

• v0.3.0 is a hard breaking change. Any use SocialDept\Schema\... statement, string class reference, config value, or serialized payload will fail after upgrade.
• After replacing imports, run composer dump-autoload -o and clear config/cache. Stale Laravel caches can hide the rename.
• Check vendor/composer/autoload_psr4.php if classes still are not found; confirm SocialDept\AtpSchema\ maps correctly.
• Update static analysis baselines (PHPStan/Psalm) and IDE indexes. The old namespace may linger in generated stubs.
• If you maintain config files that reference class strings, update them manually. Namespace renames are not always covered by IDE refactors.
• Pin the previous version if you cannot migrate immediately, but expect the old namespace to disappear from future releases.
• The package is still young (v0.3.0). Treat public APIs beyond the namespace as unstable and keep schema validation behind a small adapter class in your app.
• Good extension point: wrap the package's schema resolver in your own service. That isolates future namespace or API churn to one class.
• Debugging tip: use php artisan tinker and class_exists(\SocialDept\AtpSchema\...::class) to confirm autoloading before chasing validation failures.
• If validation fails unexpectedly after upgrade, verify you are not mixing old cached class names with new source imports.