Creating a file adapter

File adapters extract indexable text from files. They are resolved through AdapterRegistry by path, extension or support checks and are used by file indexers.

The public extension ships adapters for plain text-like files and JSON/JSONL. Specialized adapters, for example the PDF adapter, are documented in the premium extension when they are installed there.

Responsibilities

expose a stable adapter identifier;
list supported file extensions;
decide whether a file path is supported;
extract UTF-8 text;
add parser warnings or metadata where useful;
avoid throwing for recoverable parser issues when metadata can describe the problem.

Identifier

public function getIdentifier(): string
{
    return 'vendor.markdown';
}

Supported extensions

Adapters expose the file extensions they can process. Return the extension without leading dot.

public function getSupportedExtensions(): array
{
    return ['md', 'markdown'];
}

Support checks

A typical implementation uses the file extension or MIME type.

public function supports(string $path): bool
{
    return in_array(
        strtolower((string)pathinfo($path, PATHINFO_EXTENSION)),
        $this->getSupportedExtensions(),
        true
    );
}

Extraction

The adapter receives the local file path and a metadata object. It returns the indexable text and may enrich metadata with parser details.

use Madj2k\AiCore\DTO\DocumentMetadata;

public function extract(string $path, DocumentMetadata $metadata): string
{
    $metadata->addAdditional('parser', $this->getIdentifier());

    return trim((string)file_get_contents($path));
}

Service registration

services:
  Vendor\Extension\Indexing\Adapter\MarkdownAdapter:
    tags:
      - name: 'aiassistant.indexing.adapter'

Multi-document adapters

When one source file contains multiple logical records, implement Madj2k\AiCore\Indexing\Adapter\MultiDocumentAdapterInterface in addition to AdapterInterface. The JSON/JSONL adapter uses this pattern to turn one file into multiple IndexableDocument instances.