DAT-1076: Add Capability enum and supports() method to replace getSupportFor* methods

[abnegate]

Summary

• Create Capability enum with all existing capability types (54 capabilities)
• Create NotSupported exception class for cleaner error handling
• Add abstract supports(Capability $capability): bool method to Adapter base class
• Add requireSupport(Capability $capability) helper method that throws NotSupported when capability is missing
• Add getAdapterName() abstract method for error messages in exceptions
• Implement supports() method in SQL, MariaDB, MySQL, SQLite, Postgres, Mongo, and Pool adapters
• Add supports() wrapper method to Database class

Usage

This provides a unified API for checking adapter capabilities:

if (!$this->supports(Capability::FullTextIndex)) {
    throw new NotSupported(Capability::FullTextIndex->value, $this->getAdapterName());
}

Or using the helper method:

$this->requireSupport(Capability::FullTextIndex);

Backward Compatibility

The existing getSupportFor* methods are preserved for backward compatibility. The new supports() method delegates to these methods internally.

Test plan

• All unit tests pass
• No syntax errors in any modified files
• E2E tests (require database servers and Redis)

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features

• Introduced a comprehensive capability-checking system for database adapters, allowing you to detect which advanced features (such as full-text search, spatial indexes, batch operations, and relationships) are supported by your database adapter.
• Improved error handling with descriptive messages that clearly indicate which specific capabilities are unavailable for your selected database adapter.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

A new capability-based feature support system is introduced across database adapters. A string-backed Capability enum centralizes feature definitions (schemas, indexes, vectors, etc.). Base Adapter adds abstract methods for adapter naming and capability checks, plus a concrete requireSupport() method. Concrete adapters implement getAdapterName(); MongoDB and SQL implement comprehensive supports() logic via match expressions. Pool and Database classes delegate to underlying adapters. A new NotSupported exception reports unsupported capabilities with adapter context.

Changes

Cohort / File(s)	Summary
Capability System Definition src/Database/Capability.php, src/Database/Exception/NotSupported.php	New string-backed Capability enum with 46+ cases (Schemas, Attributes, Index, Vectors, etc.). New NotSupported exception constructor accepts capability and adapter name parameters to format descriptive error messages.
Base Adapter Interface src/Database/Adapter.php	Adds abstract methods getAdapterName(): string and supports(Capability): bool. Adds concrete requireSupport(Capability) method that throws NotSupported when supports() returns false, including adapter name in error message.
Concrete Adapter Implementations src/Database/Adapter/MariaDB.php, src/Database/Adapter/MySQL.php, src/Database/Adapter/Postgres.php, src/Database/Adapter/SQLite.php	Each adapter implements getAdapterName() returning adapter-specific strings ('MariaDB', 'MySQL', 'PostgreSQL', 'SQLite').
Complex Capability Adapters src/Database/Adapter/Mongo.php, src/Database/Adapter/SQL.php	Mongo and SQL adapters implement both getAdapterName() and supports(Capability) with comprehensive match-based capability querying across numerous Capability variants, delegating to existing capability getter methods.
Wrapper Adapters src/Database/Adapter/Pool.php	Adds Capability import and implements getAdapterName() and supports(Capability) by delegating to underlying wrapped adapter instance.
Database Wrapper src/Database/Database.php	Adds public supports(Capability) method that delegates to underlying adapter.supports(), exposing capability checks on the Database class.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Database
    participant Adapter
    participant Capability as Capability<br/>(Enum)

    Client->>Database: supports(Capability.Vectors)
    activate Database
    Database->>Adapter: supports(Capability.Vectors)
    activate Adapter
    Adapter->>Capability: match against case
    Adapter->>Adapter: evaluate capability support
    alt Capability supported
        Adapter-->>Database: true
    else Capability not supported
        Adapter-->>Database: false
    end
    deactivate Adapter
    Database-->>Client: boolean result
    deactivate Database

    Note over Adapter: requireSupport() variant<br/>throws NotSupported if false

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• Get support for casting  #764: Flips casting support flags in Mongo/SQL adapters, directly tied to the Capability enum's casting-related cases and supports() logic implementation.
• 1.x #701: Adds capability-querying abstract methods to Adapter interface (getSupportForSpatialAxisOrder), paralleling the main PR's generic supports() pattern for capability checks.
• 1.x #717: Modifies Adapter API to expose adapter support checks for specific features (getSupportForOptionalSpatialAttributeWithExistingRows), overlapping with the main PR's capability standardization approach.

Suggested reviewers

• fogelito

Poem

🐰 Database adapters, hear my refrain!
With Capability cases like a flowered lane,
Now supports() checks what features we've got,
Each adapter declares its capabilities a lot!
From MySQL to Mongo, PostgreSQL too—
The rabbit says: adapters know what they can do! 🌸

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: introducing a Capability enum and supports() method as a new API to replace the getSupportFor* methods pattern.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

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.}