Opt-in config for surfacing import failures

[el-schneider]

Problem

Typesense's bulk import endpoint returns HTTP 200 even when individual documents are rejected (schema type mismatch, missing required field, etc.). The per-document outcomes are returned in the response body, and typesense-php returns them from Documents::import() — it only throws on transport/HTTP errors.

The driver currently discards that return value, so rejected documents silently vanish from the search index: no log entry, no exception. We lost documents from the index due to a schema type mismatch and only found out much later when content was missing from search results.

Solution

• Index::insertDocuments() now inspects the import results and collects failures.
• Default (non-breaking): failures are logged as a warning, including the index name, failure count, and per-document details (id + error), capped at 10 entries to bound log size.
• Opt-in strict mode: a new throw_on_import_failure config key (default false). When enabled, an ImportFailedException is thrown instead, carrying the raw failures array ($e->failures()) and index name ($e->index()) so callers can inspect them.
• The import now passes return_id, so Typesense includes the document id in each result line (newer Typesense versions no longer echo the full document on failure by default).

Before

Nothing. Documents are dropped without a trace.

After

local.WARNING: Typesense rejected 2 document(s) during import into the [pages_index] index. {"failures":[{"id":"entry::abc123","error":"Field `tags` must be an array."},{"id":"entry::def456","error":"Field `tags` must be an array."}]}

Alternative considered

Dispatching an event (e.g. DocumentsImportFailed) instead of logging, and letting users decide how to react. That would be more flexible but requires users to opt in to get any signal at all — the main goal here is that failures are visible by default. Happy to rework it that way if you'd prefer.

[ryanmitchell]

Thanks!

[ryanmitchell]

Sorry, I've just realised you targeted v2, can you re-open and target main, we're only providing security fixes on v2 now

[el-schneider]

I can bring it to v6 as well, but we urgently need it on v5. We currently can not update to v6 right away unfortunately.

[ryanmitchell]

You'd be better using your own fork for your v5 requirement.