Add schema loader with multi-source support

src/Parser/SchemaLoader.php

···
+<?php
+
+namespace SocialDept\Schema\Parser;
+
+use Illuminate\Support\Facades\Cache;
+use SocialDept\Schema\Exceptions\SchemaNotFoundException;
+use SocialDept\Schema\Exceptions\SchemaParseException;
+
+class SchemaLoader
+{
+    /**
+     * In-memory cache of loaded schemas for current request.
+     *
+     * @var array<string, array>
+     */
+    protected array $memoryCache = [];
+
+    /**
+     * Schema source directories.
+     *
+     * @var array<string>
+     */
+    protected array $sources;
+
+    /**
+     * Whether to use Laravel cache.
+     */
+    protected bool $useCache;
+
+    /**
+     * Cache TTL in seconds.
+     */
+    protected int $cacheTtl;
+
+    /**
+     * Cache key prefix.
+     */
+    protected string $cachePrefix;
+
+    /**
+     * Create a new SchemaLoader instance.
+     *
+     * @param  array<string>  $sources
+     */
+    public function __construct(
+        array $sources,
+        bool $useCache = true,
+        int $cacheTtl = 3600,
+        string $cachePrefix = 'schema'
+    ) {
+        $this->sources = $sources;
+        $this->useCache = $useCache;
+        $this->cacheTtl = $cacheTtl;
+        $this->cachePrefix = $cachePrefix;
+    }
+
+    /**
+     * Load schema by NSID.
+     */
+    public function load(string $nsid): array
+    {
+        // Check memory cache first
+        if (isset($this->memoryCache[$nsid])) {
+            return $this->memoryCache[$nsid];
+        }
+
+        // Check Laravel cache
+        if ($this->useCache) {
+            $cacheKey = $this->getCacheKey($nsid);
+            $cached = Cache::get($cacheKey);
+
+            if ($cached !== null) {
+                $this->memoryCache[$nsid] = $cached;
+
+                return $cached;
+            }
+        }
+
+        // Load from sources
+        $schema = $this->loadFromSources($nsid);
+
+        // Cache the result
+        $this->memoryCache[$nsid] = $schema;
+
+        if ($this->useCache) {
+            Cache::put($this->getCacheKey($nsid), $schema, $this->cacheTtl);
+        }
+
+        return $schema;
+    }
+
+    /**
+     * Check if schema exists.
+     */
+    public function exists(string $nsid): bool
+    {
+        try {
+            $this->load($nsid);
+
+            return true;
+        } catch (SchemaNotFoundException) {
+            return false;
+        }
+    }
+
+    /**
+     * Load schema from configured sources.
+     */
+    protected function loadFromSources(string $nsid): array
+    {
+        foreach ($this->sources as $source) {
+            // Try to load from this source
+            $schema = $this->loadFromSource($nsid, $source);
+
+            if ($schema !== null) {
+                return $schema;
+            }
+        }
+
+        throw SchemaNotFoundException::forNsid($nsid);
+    }
+
+    /**
+     * Load schema from a specific source directory.
+     */
+    protected function loadFromSource(string $nsid, string $source): ?array
+    {
+        // Try NSID-based path (app.bsky.feed.post -> app/bsky/feed/post.json)
+        $nsidPath = $this->nsidToPath($nsid);
+        $jsonPath = $source . '/' . $nsidPath . '.json';
+
+        if (file_exists($jsonPath)) {
+            return $this->loadJsonFile($jsonPath, $nsid);
+        }
+
+        // Try PHP file
+        $phpPath = $source . '/' . $nsidPath . '.php';
+
+        if (file_exists($phpPath)) {
+            return $this->loadPhpFile($phpPath, $nsid);
+        }
+
+        // Try flat structure (app.bsky.feed.post.json)
+        $flatJsonPath = $source . '/' . $nsid . '.json';
+
+        if (file_exists($flatJsonPath)) {
+            return $this->loadJsonFile($flatJsonPath, $nsid);
+        }
+
+        $flatPhpPath = $source . '/' . $nsid . '.php';
+
+        if (file_exists($flatPhpPath)) {
+            return $this->loadPhpFile($flatPhpPath, $nsid);
+        }
+
+        return null;
+    }
+
+    /**
+     * Convert NSID to file path (app.bsky.feed.post -> app/bsky/feed/post).
+     */
+    protected function nsidToPath(string $nsid): string
+    {
+        return str_replace('.', '/', $nsid);
+    }
+
+    /**
+     * Load and parse JSON file.
+     */
+    protected function loadJsonFile(string $path, string $nsid): array
+    {
+        $contents = file_get_contents($path);
+
+        if ($contents === false) {
+            throw SchemaNotFoundException::forFile($path);
+        }
+
+        $data = json_decode($contents, true);
+
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            throw SchemaParseException::invalidJson($nsid, json_last_error_msg());
+        }
+
+        if (! is_array($data)) {
+            throw SchemaParseException::malformed($nsid, 'Schema must be a JSON object');
+        }
+
+        return $data;
+    }
+
+    /**
+     * Load PHP file returning array.
+     */
+    protected function loadPhpFile(string $path, string $nsid): array
+    {
+        $data = include $path;
+
+        if (! is_array($data)) {
+            throw SchemaParseException::malformed($nsid, 'PHP file must return an array');
+        }
+
+        return $data;
+    }
+
+    /**
+     * Get cache key for NSID.
+     */
+    protected function getCacheKey(string $nsid): string
+    {
+        return "{$this->cachePrefix}:parsed:{$nsid}";
+    }
+
+    /**
+     * Clear cached schema.
+     */
+    public function clearCache(?string $nsid = null): void
+    {
+        if ($nsid === null) {
+            // Clear all memory cache
+            $this->memoryCache = [];
+
+            // Note: Can't easily clear all Laravel cache entries with prefix
+            // Users should call Cache::flush() or use cache tags if needed
+            return;
+        }
+
+        // Clear specific NSID from memory cache
+        unset($this->memoryCache[$nsid]);
+
+        // Clear from Laravel cache
+        if ($this->useCache) {
+            Cache::forget($this->getCacheKey($nsid));
+        }
+    }
+
+    /**
+     * Get all cached NSIDs from memory.
+     *
+     * @return array<string>
+     */
+    public function getCachedNsids(): array
+    {
+        return array_keys($this->memoryCache);
+    }
+}

tests/Unit/Parser/SchemaLoaderTest.php

···
+<?php
+
+namespace SocialDept\Schema\Tests\Unit\Parser;
+
+use Illuminate\Support\Facades\Cache;
+use Orchestra\Testbench\TestCase;
+use SocialDept\Schema\Exceptions\SchemaNotFoundException;
+use SocialDept\Schema\Exceptions\SchemaParseException;
+use SocialDept\Schema\Parser\SchemaLoader;
+
+class SchemaLoaderTest extends TestCase
+{
+    protected string $fixturesPath;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->fixturesPath = __DIR__ . '/../../fixtures';
+
+        // Clear cache before each test
+        Cache::flush();
+    }
+
+    public function test_it_loads_schema_from_hierarchical_json(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], false);
+
+        $schema = $loader->load('app.bsky.feed.post');
+
+        $this->assertIsArray($schema);
+        $this->assertSame(1, $schema['lexicon']);
+        $this->assertSame('app.bsky.feed.post', $schema['id']);
+    }
+
+    public function test_it_loads_schema_from_flat_php(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], false);
+
+        $schema = $loader->load('com.atproto.repo.getRecord');
+
+        $this->assertIsArray($schema);
+        $this->assertSame(1, $schema['lexicon']);
+        $this->assertSame('com.atproto.repo.getRecord', $schema['id']);
+    }
+
+    public function test_it_checks_if_schema_exists(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], false);
+
+        $this->assertTrue($loader->exists('app.bsky.feed.post'));
+        $this->assertTrue($loader->exists('com.atproto.repo.getRecord'));
+        $this->assertFalse($loader->exists('nonexistent.schema'));
+    }
+
+    public function test_it_throws_when_schema_not_found(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], false);
+
+        $this->expectException(SchemaNotFoundException::class);
+        $this->expectExceptionMessage('Schema not found for NSID: nonexistent.schema');
+
+        $loader->load('nonexistent.schema');
+    }
+
+    public function test_it_caches_schemas_in_memory(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], false);
+
+        // First load
+        $schema1 = $loader->load('app.bsky.feed.post');
+
+        // Second load should come from memory
+        $schema2 = $loader->load('app.bsky.feed.post');
+
+        $this->assertSame($schema1, $schema2);
+        $this->assertContains('app.bsky.feed.post', $loader->getCachedNsids());
+    }
+
+    public function test_it_caches_schemas_in_laravel_cache(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], true, 3600, 'schema');
+
+        // First load - should store in cache
+        $schema = $loader->load('app.bsky.feed.post');
+
+        // Clear memory cache to force Laravel cache lookup
+        $loader->clearCache('app.bsky.feed.post');
+
+        // Manually put it back in Laravel cache
+        Cache::put('schema:parsed:app.bsky.feed.post', $schema, 3600);
+
+        // This should retrieve from Laravel cache
+        $cached = $loader->load('app.bsky.feed.post');
+
+        $this->assertSame($schema, $cached);
+    }
+
+    public function test_it_retrieves_from_laravel_cache(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], true);
+
+        // First load to cache it
+        $originalSchema = $loader->load('app.bsky.feed.post');
+
+        // Clear memory cache
+        $loader->clearCache('app.bsky.feed.post');
+
+        // Second load should come from Laravel cache
+        $cachedSchema = $loader->load('app.bsky.feed.post');
+
+        $this->assertSame($originalSchema, $cachedSchema);
+        $this->assertSame('app.bsky.feed.post', $cachedSchema['id']);
+    }
+
+    public function test_it_clears_specific_schema_cache(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], true);
+
+        // Load to populate caches
+        $loader->load('app.bsky.feed.post');
+
+        $this->assertContains('app.bsky.feed.post', $loader->getCachedNsids());
+
+        // Clear cache
+        $loader->clearCache('app.bsky.feed.post');
+
+        // Memory cache should be cleared
+        $this->assertNotContains('app.bsky.feed.post', $loader->getCachedNsids());
+
+        // Laravel cache should also be cleared (verify by loading again and checking it comes from file)
+        $this->assertFalse(Cache::has('schema:parsed:app.bsky.feed.post'));
+    }
+
+    public function test_it_clears_all_memory_cache(): void
+    {
+        $loader = new SchemaLoader([$this->fixturesPath], false);
+
+        // Load multiple schemas
+        $loader->load('app.bsky.feed.post');
+        $loader->load('com.atproto.repo.getRecord');
+
+        $this->assertCount(2, $loader->getCachedNsids());
+
+        // Clear all
+        $loader->clearCache();
+
+        $this->assertCount(0, $loader->getCachedNsids());
+    }
+
+    public function test_it_searches_multiple_sources_in_order(): void
+    {
+        $source1 = $this->fixturesPath . '/source1';
+        $source2 = $this->fixturesPath;
+
+        // Schema only exists in source2
+        $loader = new SchemaLoader([$source1, $source2], false);
+
+        $schema = $loader->load('app.bsky.feed.post');
+
+        $this->assertSame('app.bsky.feed.post', $schema['id']);
+    }
+
+    public function test_it_throws_on_invalid_json(): void
+    {
+        $invalidPath = $this->fixturesPath . '/invalid';
+        @mkdir($invalidPath, 0755, true);
+        file_put_contents($invalidPath . '/invalid.json', '{invalid json}');
+
+        $loader = new SchemaLoader([$invalidPath], false);
+
+        $this->expectException(SchemaParseException::class);
+        $this->expectExceptionMessage('Failed to parse schema JSON');
+
+        try {
+            $loader->load('invalid');
+        } finally {
+            @unlink($invalidPath . '/invalid.json');
+            @rmdir($invalidPath);
+        }
+    }
+
+    public function test_it_throws_on_php_file_not_returning_array(): void
+    {
+        $invalidPath = $this->fixturesPath . '/invalid';
+        @mkdir($invalidPath, 0755, true);
+        file_put_contents($invalidPath . '/invalid.php', '<?php return "not an array";');
+
+        $loader = new SchemaLoader([$invalidPath], false);
+
+        $this->expectException(SchemaParseException::class);
+        $this->expectExceptionMessage('PHP file must return an array');
+
+        try {
+            $loader->load('invalid');
+        } finally {
+            @unlink($invalidPath . '/invalid.php');
+            @rmdir($invalidPath);
+        }
+    }
+
+}

tests/fixtures/app/bsky/feed/post.json

···
+{
+  "lexicon": 1,
+  "id": "app.bsky.feed.post",
+  "description": "A post record",
+  "defs": {
+    "main": {
+      "type": "record",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["text", "createdAt"],
+        "properties": {
+          "text": {
+            "type": "string",
+            "maxLength": 300,
+            "maxGraphemes": 300
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime"
+          }
+        }
+      }
+    }
+  }
+}

tests/fixtures/com.atproto.repo.getRecord.php

···
+<?php
+
+return [
+    'lexicon' => 1,
+    'id' => 'com.atproto.repo.getRecord',
+    'description' => 'Get a record',
+    'defs' => [
+        'main' => [
+            'type' => 'query',
+            'parameters' => [
+                'type' => 'params',
+                'required' => ['repo', 'collection', 'rkey'],
+                'properties' => [
+                    'repo' => [
+                        'type' => 'string',
+                    ],
+                    'collection' => [
+                        'type' => 'string',
+                    ],
+                    'rkey' => [
+                        'type' => 'string',
+                    ],
+                ],
+            ],
+        ],
+    ],
+];