Parse and validate AT Protocol Lexicons with DTO generation for Laravel
Create README and documentation
+444
-42
+63
-13
CONTRIBUTING.md
+63
-13
CONTRIBUTING.md
···
1
1
# Contributing
2
2
3
-
Contributions are welcome and will be fully credited.
3
+
Contributions are **welcome** and will be fully **credited**.
4
4
5
-
Contributions are accepted via Pull Requests on [Github](https://github.com/social-dept/schema).
5
+
## Etiquette
6
6
7
-
# Things you could do
8
-
If you want to contribute but do not know where to start, this list provides some starting points.
9
-
- Add license text
10
-
- Remove rewriteRules.php
11
-
- Set up TravisCI, StyleCI, ScrutinizerCI
12
-
- Write a comprehensive ReadMe
7
+
This project is open source, and as such, the maintainers give their free time to build and maintain the source code held within. They make the code freely available in the hope that it will be of use to other developers. It would be extremely unfair for them to suffer abuse or anger for their hard work.
13
8
14
-
## Pull Requests
9
+
Please be considerate towards maintainers when raising issues or presenting pull requests. Let's show the world that developers are civilized and selfless people.
15
10
16
-
- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
11
+
It's the duty of the maintainer to ensure that all submissions to the project are of sufficient quality to benefit the project. Many developers have different skillsets, strengths, and weaknesses. Respect the maintainer's decision, and do not be upset or abusive if your submission is not used.
17
12
18
-
- **Document any change in behaviour** - Make sure the `readme.md` and any other relevant documentation are kept up-to-date.
13
+
## Viability
19
14
20
-
- **Consider our release cycle** - We try to follow [SemVer v2.0.0](http://semver.org/). Randomly breaking public APIs is not an option.
15
+
When requesting or submitting new features, first consider whether it might be useful to others. Open source projects are used by many developers, who may have entirely different needs to your own. Think about whether or not your feature is likely to be used by other users of the project.
16
+
17
+
## Procedure
18
+
19
+
### Before Filing an Issue
20
+
21
+
- Search existing issues to avoid duplicates
22
+
- Check the [documentation](README.md) to ensure it's not a usage question
23
+
- Provide a clear title and description
24
+
- Include steps to reproduce the issue
25
+
- Specify your environment (PHP version, Laravel version, Schema version)
26
+
- Include relevant code samples and full error messages
27
+
28
+
### Before Submitting a Pull Request
29
+
30
+
- **Discuss non-trivial changes first** by opening an issue
31
+
- **Fork the repository** and create a feature branch from `main`
32
+
- **Follow all requirements** listed below
33
+
- **Write tests** for your changes
34
+
- **Update documentation** if behavior changes
35
+
- **Run code style checks** with `vendor/bin/php-cs-fixer fix`
36
+
- **Ensure all tests pass** with `vendor/bin/phpunit`
37
+
- **Write clear commit messages** that explain what and why
38
+
39
+
## Requirements
40
+
41
+
- **[PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/)** - Run `vendor/bin/php-cs-fixer fix` to automatically fix code style issues.
42
+
43
+
- **Add tests** - Your patch won't be accepted if it doesn't have tests. All tests must use [PHPUnit](https://phpunit.de/) with [Pest](https://pestphp.com/).
44
+
45
+
- **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date.
46
+
47
+
- **Consider our release cycle** - We follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option.
21
48
22
49
- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
23
50
24
-
- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](http://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
51
+
- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
52
+
53
+
## Running Tests
25
54
55
+
```bash
56
+
vendor/bin/phpunit
57
+
```
58
+
59
+
Run specific test suites:
60
+
61
+
```bash
62
+
# Unit tests only
63
+
vendor/bin/phpunit --testsuite=unit
64
+
65
+
# Integration tests only
66
+
vendor/bin/phpunit --testsuite=integration
67
+
```
68
+
69
+
## Code Style
70
+
71
+
Schema follows PSR-12 coding standard. Run PHP CS Fixer before submitting:
72
+
73
+
```bash
74
+
vendor/bin/php-cs-fixer fix
75
+
```
26
76
27
77
**Happy coding**!
+381
-29
README.md
+381
-29
README.md
···
1
-
# Schema
1
+
[](https://github.com/socialdept/atp-signals)
2
+
3
+
<h3 align="center">
4
+
Parse, validate, and transform AT Protocol Lexicon schemas in Laravel.
5
+
</h3>
6
+
7
+
<p align="center">
8
+
<br>
9
+
<a href="https://packagist.org/packages/socialdept/atp-schema" title="Latest Version on Packagist"><img src="https://img.shields.io/packagist/v/socialdept/atp-schema.svg?style=flat-square"></a>
10
+
<a href="https://packagist.org/packages/socialdept/atp-schema" title="Total Downloads"><img src="https://img.shields.io/packagist/dt/socialdept/atp-schema.svg?style=flat-square"></a>
11
+
<a href="LICENSE" title="Software License"><img src="https://img.shields.io/github/license/socialdept/atp-schema?style=flat-square"></a>
12
+
</p>
13
+
14
+
---
15
+
16
+
## What is Schema?
17
+
18
+
**Schema** is a Laravel package for working with AT Protocol Lexicon schemas. It provides comprehensive tools for parsing schema definitions, validating data against those schemas, handling file uploads (blobs), and transforming between raw data and domain models.
19
+
20
+
Think of it as your complete toolkit for building AT Protocol applications that need strict data validation and schema compliance.
21
+
22
+
## Why use Schema?
23
+
24
+
- **Complete Lexicon support** - All types, formats, and constraints from the AT Protocol spec
25
+
- **Multiple validation modes** - STRICT, OPTIMISTIC, and LENIENT for different use cases
26
+
- **Laravel integration** - Works seamlessly with Laravel's validation and storage systems
27
+
- **Blob handling** - Built-in file upload validation and storage
28
+
- **Model transformation** - Convert between arrays and domain objects
29
+
- **Union types** - Full support for discriminated unions with `$type` fields
30
+
- **Extensible** - Macros and hooks let you customize behavior
31
+
- **Production ready** - 818 passing tests with comprehensive coverage
32
+
33
+
## Quick Example
34
+
35
+
```php
36
+
use SocialDept\Schema\Data\LexiconDocument;
37
+
use SocialDept\Schema\Validation\Validator;
38
+
use SocialDept\Schema\Parser\SchemaLoader;
39
+
40
+
// Load a schema
41
+
$schema = LexiconDocument::fromArray([
42
+
'lexicon' => 1,
43
+
'id' => 'app.bsky.feed.post',
44
+
'defs' => [
45
+
'main' => [
46
+
'type' => 'record',
47
+
'record' => [
48
+
'type' => 'object',
49
+
'required' => ['text', 'createdAt'],
50
+
'properties' => [
51
+
'text' => ['type' => 'string', 'maxLength' => 300],
52
+
'createdAt' => ['type' => 'string', 'format' => 'datetime'],
53
+
],
54
+
],
55
+
],
56
+
],
57
+
]);
2
58
3
-
[![Latest Version on Packagist][ico-version]][link-packagist]
4
-
[![Total Downloads][ico-downloads]][link-downloads]
5
-
[![Build Status][ico-travis]][link-travis]
6
-
[![StyleCI][ico-styleci]][link-styleci]
59
+
// Validate data
60
+
$validator = new Validator(new SchemaLoader([]));
7
61
8
-
This is where your description should go. Take a look at [contributing.md](CONTRIBUTING.md) to see a to do list.
62
+
$data = [
63
+
'text' => 'Hello, AT Protocol!',
64
+
'createdAt' => '2024-01-01T12:00:00Z',
65
+
];
66
+
67
+
if ($validator->validate($data, $schema)) {
68
+
// Data is valid!
69
+
}
70
+
71
+
// Get Laravel-formatted errors
72
+
$errors = $validator->validateWithErrors($invalidData, $schema);
73
+
// ['text' => ['The text field exceeds maximum length.']]
74
+
```
9
75
10
76
## Installation
11
77
12
-
Via Composer
78
+
```bash
79
+
composer require socialdept/atp-schema
80
+
```
81
+
82
+
The package will auto-register with Laravel. Optionally publish the config:
13
83
14
84
```bash
15
-
composer require social-dept/schema
85
+
php artisan vendor:publish --tag=schema-config
86
+
```
87
+
88
+
## Basic Usage
89
+
90
+
### Validation Modes
91
+
92
+
Choose the validation strictness that fits your use case:
93
+
94
+
```php
95
+
use SocialDept\Schema\Validation\Validator;
96
+
97
+
// STRICT - Rejects unknown fields
98
+
$validator->setMode(Validator::MODE_STRICT);
99
+
100
+
// OPTIMISTIC - Allows unknown fields (default)
101
+
$validator->setMode(Validator::MODE_OPTIMISTIC);
102
+
103
+
// LENIENT - Skips constraint validation
104
+
$validator->setMode(Validator::MODE_LENIENT);
16
105
```
17
106
18
-
## Usage
107
+
### Handling Blobs
108
+
109
+
Upload and validate files with built-in constraints:
110
+
111
+
```php
112
+
use SocialDept\Schema\Services\BlobHandler;
113
+
114
+
$blobHandler = new BlobHandler('local');
115
+
116
+
$blob = $blobHandler->store(request()->file('image'), [
117
+
'accept' => ['image/*'],
118
+
'maxSize' => 1024 * 1024 * 5, // 5MB
119
+
]);
120
+
121
+
// Use in validated data
122
+
$data = [
123
+
'image' => $blob->toArray(),
124
+
];
125
+
```
126
+
127
+
### Model Transformation
128
+
129
+
Transform between raw arrays and domain objects:
130
+
131
+
```php
132
+
use SocialDept\Schema\Services\ModelMapper;
133
+
use SocialDept\Schema\Contracts\Transformer;
134
+
135
+
class Post
136
+
{
137
+
public function __construct(
138
+
public string $text,
139
+
public string $createdAt
140
+
) {}
141
+
}
19
142
20
-
## Change log
143
+
class PostTransformer implements Transformer
144
+
{
145
+
public function fromArray(array $data): Post
146
+
{
147
+
return new Post(
148
+
text: $data['text'],
149
+
createdAt: $data['createdAt']
150
+
);
151
+
}
21
152
22
-
Please see the [changelog](changelog.md) for more information on what has changed recently.
153
+
public function toArray(mixed $model): array
154
+
{
155
+
return [
156
+
'text' => $model->text,
157
+
'createdAt' => $model->createdAt,
158
+
];
159
+
}
160
+
161
+
public function supports(string $type): bool
162
+
{
163
+
return $type === 'app.bsky.feed.post';
164
+
}
165
+
}
166
+
167
+
// Register and use
168
+
$mapper = new ModelMapper();
169
+
$mapper->register('app.bsky.feed.post', new PostTransformer());
170
+
171
+
$post = $mapper->fromArray('app.bsky.feed.post', $data);
172
+
$array = $mapper->toArray('app.bsky.feed.post', $post);
173
+
```
174
+
175
+
### Union Types
176
+
177
+
Work with discriminated unions using the `$type` field:
178
+
179
+
```php
180
+
use SocialDept\Schema\Services\UnionResolver;
181
+
182
+
$resolver = new UnionResolver();
183
+
184
+
$data = [
185
+
'$type' => 'app.bsky.embed.images',
186
+
'images' => [/* ... */],
187
+
];
188
+
189
+
$type = $resolver->extractType($data);
190
+
// "app.bsky.embed.images"
191
+
192
+
$isValid = $resolver->validate($data, $unionDef);
193
+
```
194
+
195
+
## Complete Workflow Example
196
+
197
+
Here's how to validate a post with an image upload:
198
+
199
+
```php
200
+
use SocialDept\Schema\Data\LexiconDocument;
201
+
use SocialDept\Schema\Validation\Validator;
202
+
use SocialDept\Schema\Services\BlobHandler;
203
+
204
+
// Load schema
205
+
$schema = LexiconDocument::fromArray([/* ... */]);
206
+
207
+
// Handle image upload
208
+
$blobHandler = new BlobHandler('local');
209
+
$blob = $blobHandler->store(request()->file('image'), [
210
+
'accept' => ['image/*'],
211
+
'maxSize' => 1024 * 1024 * 5,
212
+
]);
213
+
214
+
// Create post data
215
+
$postData = [
216
+
'text' => 'Check out this photo!',
217
+
'createdAt' => now()->toIso8601String(),
218
+
'embed' => [
219
+
'$type' => 'app.bsky.embed.images',
220
+
'images' => [
221
+
[
222
+
'image' => $blob->toArray(),
223
+
'alt' => 'A beautiful sunset',
224
+
],
225
+
],
226
+
],
227
+
];
228
+
229
+
// Validate
230
+
$validator = new Validator(new SchemaLoader([]));
231
+
232
+
if ($validator->validate($postData, $schema)) {
233
+
// Store post...
234
+
} else {
235
+
$errors = $validator->validateWithErrors($postData, $schema);
236
+
// Handle errors...
237
+
}
238
+
```
239
+
240
+
## Supported Types
241
+
242
+
Schema supports all AT Protocol Lexicon types:
243
+
244
+
- **Primitives** - `string`, `integer`, `boolean`, `bytes`
245
+
- **Objects** - Nested objects with properties
246
+
- **Arrays** - Sequential lists with item validation
247
+
- **Blobs** - File uploads with mime type and size constraints
248
+
- **Unions** - Discriminated unions with `$type` field
249
+
- **Unknown** - Accept any value
250
+
251
+
## Supported Formats
252
+
253
+
Built-in validators for AT Protocol formats:
254
+
255
+
- `datetime` - ISO 8601 timestamps
256
+
- `uri` - Valid URIs
257
+
- `at-uri` - AT Protocol URIs
258
+
- `did` - Decentralized identifiers
259
+
- `nsid` - Namespaced identifiers
260
+
- `cid` - Content identifiers
261
+
262
+
## Advanced Features
263
+
264
+
### Extension Hooks
265
+
266
+
Add custom logic at key points in the validation lifecycle:
267
+
268
+
```php
269
+
use SocialDept\Schema\Support\ExtensionManager;
270
+
271
+
$extensions = new ExtensionManager();
272
+
273
+
$extensions->hook('before:validate', function ($data) {
274
+
$data['text'] = trim($data['text']);
275
+
return $data;
276
+
});
277
+
278
+
$transformed = $extensions->filter('before:validate', $data);
279
+
```
280
+
281
+
### Macros
282
+
283
+
Extend core services with custom methods:
284
+
285
+
```php
286
+
use SocialDept\Schema\Services\ModelMapper;
287
+
288
+
ModelMapper::macro('validateAndTransform', function ($type, $data, $schema) {
289
+
if (!$this->validator->validate($data, $schema)) {
290
+
return null;
291
+
}
292
+
return $this->fromArray($type, $data);
293
+
});
294
+
295
+
$mapper = new ModelMapper();
296
+
$result = $mapper->validateAndTransform('app.bsky.feed.post', $data, $schema);
297
+
```
298
+
299
+
## API Reference
300
+
301
+
### Core Classes
302
+
303
+
**LexiconDocument**
304
+
```php
305
+
LexiconDocument::fromArray(array $data): self
306
+
LexiconDocument::fromJson(string $json): self
307
+
$document->getNsid(): string
308
+
$document->getVersion(): int
309
+
$document->getDefinition(string $name = 'main'): array
310
+
```
311
+
312
+
**Validator**
313
+
```php
314
+
$validator->validate(array $data, LexiconDocument $schema): bool
315
+
$validator->validateWithErrors(array $data, LexiconDocument $schema): array
316
+
$validator->setMode(string $mode): self
317
+
```
318
+
319
+
**BlobHandler**
320
+
```php
321
+
$handler->store(UploadedFile $file, array $constraints = []): BlobReference
322
+
$handler->storeFromString(string $content, string $mimeType): BlobReference
323
+
$handler->get(string $ref): ?string
324
+
$handler->delete(string $ref): bool
325
+
$handler->exists(string $ref): bool
326
+
```
327
+
328
+
**ModelMapper**
329
+
```php
330
+
$mapper->register(string $type, Transformer $transformer): self
331
+
$mapper->fromArray(string $type, array $data): mixed
332
+
$mapper->toArray(string $type, mixed $model): array
333
+
$mapper->fromArrayMany(string $type, array $items): array
334
+
```
335
+
336
+
**UnionResolver**
337
+
```php
338
+
$resolver->extractType(array $data): ?string
339
+
$resolver->validate(array $data, array $definition): bool
340
+
$resolver->getTypeDefinition(array $data, array $definition): ?LexiconDocument
341
+
```
23
342
24
343
## Testing
25
344
345
+
Run the test suite:
346
+
26
347
```bash
27
-
composer test
348
+
vendor/bin/phpunit
28
349
```
29
350
30
-
## Contributing
351
+
Run specific test categories:
352
+
353
+
```bash
354
+
# Unit tests only
355
+
vendor/bin/phpunit --testsuite=unit
31
356
32
-
Please see [contributing.md](CONTRIBUTING.md) for details and a todolist.
357
+
# Integration tests only
358
+
vendor/bin/phpunit --testsuite=integration
359
+
```
33
360
34
-
## Security
361
+
## Configuration
35
362
36
-
If you discover any security related issues, please email author@email.com instead of using the issue tracker.
363
+
Customize behavior in `config/schema.php`:
364
+
365
+
```php
366
+
return [
367
+
'storage' => [
368
+
'disk' => env('SCHEMA_STORAGE_DISK', 'local'),
369
+
],
370
+
371
+
'validation' => [
372
+
'mode' => env('SCHEMA_VALIDATION_MODE', 'optimistic'),
373
+
],
374
+
375
+
'blob' => [
376
+
'max_size' => env('SCHEMA_BLOB_MAX_SIZE', 1024 * 1024 * 10), // 10MB
377
+
],
378
+
];
379
+
```
380
+
381
+
## Requirements
382
+
383
+
- PHP 8.2+
384
+
- Laravel 11+
385
+
386
+
## Resources
387
+
388
+
- [AT Protocol Documentation](https://atproto.com/)
389
+
- [Lexicon Specification](https://atproto.com/specs/lexicon)
390
+
- [Bluesky API Docs](https://docs.bsky.app/)
391
+
392
+
## Support & Contributing
393
+
394
+
Found a bug or have a feature request? [Open an issue](https://github.com/socialdept/atp-schema/issues).
395
+
396
+
Want to contribute? We'd love your help! Check out the [contribution guidelines](CONTRIBUTING.md).
37
397
38
398
## Credits
39
399
40
-
- [Author Name][link-author]
41
-
- [All Contributors][link-contributors]
400
+
- [Miguel Batres](https://batres.co) - founder & lead maintainer
401
+
- [All contributors](https://github.com/socialdept/atp-schema/graphs/contributors)
42
402
43
403
## License
44
404
45
-
MIT. Please see the [license file](LICENSE) for more information.
405
+
Schema is open-source software licensed under the [MIT license](LICENSE).
46
406
47
-
[ico-version]: https://img.shields.io/packagist/v/social-dept/schema.svg?style=flat-square
48
-
[ico-downloads]: https://img.shields.io/packagist/dt/social-dept/schema.svg?style=flat-square
49
-
[ico-travis]: https://img.shields.io/travis/social-dept/schema/master.svg?style=flat-square
50
-
[ico-styleci]: https://styleci.io/repos/12345678/shield
407
+
---
51
408
52
-
[link-packagist]: https://packagist.org/packages/social-dept/schema
53
-
[link-downloads]: https://packagist.org/packages/social-dept/schema
54
-
[link-travis]: https://travis-ci.org/social-dept/schema
55
-
[link-styleci]: https://styleci.io/repos/12345678
56
-
[link-author]: https://github.com/social-dept
57
-
[link-contributors]: ../../contributors
409
+
**Built for the Federation** • By Social Dept.