Refactor Index/Indexes separation and modernize Search API

[norkunas]

Pull Request

Related issue

Fixes #840
Fixes #760

What does this PR do?

This PR performs a major architectural refactor of the Index handling and modernizes the Search API to leverage modern PHP features and stricter static analysis.

1. Architectural Separation of Indexes and Index

• Logical Split: Separated collection-level operations (Indexes.php for /indexes) from instance-specific operations (Index.php for /indexes/{uid}).
• Trait Alignment: Moved HandlesDocuments, HandlesSettings, and HandlesTasks traits to the Index class. This ensures instance methods always have a valid uid context.
• Legacy Cleanup: Completely removed the legacy fill() and newInstance() pattern. Hydration is now handled via an explicit Index::fromArray() factory.

2. Implementation of Metadata Lazy Loading

• Sentinel Pattern: Used uninitialized typed properties for primaryKey, createdAt, and updatedAt.
• Transparent Hydration: Metadata is fetched automatically on first access via getPrimaryKey(), getCreatedAt(), or getUpdatedAt(). The use of isset() sentinels ensures that a null primary key doesn't trigger redundant API calls once the instance is loaded.

3. Modernized Search API

• New SearchQuery Object: Introduced a dedicated SearchQuery contract for single-index searches, while renaming the multi-search oriented class to MultiSearchQuery.
• API Overloading with Union Types: Refactored Index::search() and Index::rawSearch() to use native PHP 8.0 union types (string|SearchQuery|null). This supports both the traditional string-based queries and the new typed object API, ensuring full backward compatibility.
• Modern Feature Support: Added native support for media (multimodal) and retrieveVectors parameters.

4. Engineering Standards & Tooling

• Strict Typing: Implemented detailed multiline array shapes and utilized the non-empty-string PHPStan pseudo-type for identifiers and timestamps.
• Test Refactoring: Updated the test suite to use more robust mocking patterns (mocking the Http contract instead of the Index class) and verified all changes against a live Meilisearch instance.

PR checklist

Please check if your PR fulfills the following requirements:

• Did you use any AI tool while implementing this PR (code, tests, docs, etc.)? If yes, disclose it in the PR description and describe what it was used for. AI usage is allowed when it is disclosed.
• Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
• Have you read the contributing guidelines?
• Have you made sure that the title is accurate and descriptive of the changes?

AI Disclosure:
This PR was implemented with the assistance of Gemini 2.0 Flash (Experimental) via the Gemini CLI agent. The AI was used to automate the mass refactoring of the test suite (updating imports and typehints across 30+ files), assist in the design of the lazy-loading sentinel pattern, and ensure strict PHPStan array shape compliance across the new SearchQuery and Index contracts. All AI-generated changes were empirically verified via PHPUnit and static analysis.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7a8c42f0-409c-45e9-b89c-d777a2cd5cbd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}