---
title: "Creating a file adapter"
manual: "AI Assistant"
version: "main"
source: "Developers/Extending/CreatingFileAdapter.rst"
rendered: "2026-10-03T14:54:45+00:00"
---

# Creating a file adapter {#creating-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 {#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 {#identifier}

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

## Supported extensions {#supported-extensions}

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

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

## Support checks {#support-checks}

A typical implementation uses the file extension or MIME type.

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

## Extraction {#extraction}

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

```php
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 {#service-registration}

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

## Multi-document adapters {#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.