Improve type safety with covariant return types in Engine implementations

Current Problem

Engine implementations like SqliteEngine declare return types using generic interfaces:

public function makeInsert(): Query\InsertQuery
{
    return new Query\Sqlite\InsertQuery($this);
}

This prevents static analysis tools (PHPStan, Psalm, PhpStorm) from inferring the concrete type, making it impossible to use engine-specific methods like onConflictDoUpdate() without manual type assertions.

Proposed Solution

Use covariant return types (available since PHP 7.4, which is already the minimum required version):

public function makeInsert(): Query\Sqlite\InsertQuery
{
    return new Query\Sqlite\InsertQuery($this);
}

This is backward compatible (covariance doesn't break Liskov substitution) and provides proper type information for static analysis.

I can provide with a PR.

Benefits

• Better IDE support
• Safer refactoring
• No runtime impact
• No BC break

[shadowhand]

Good idea! A PR would be welcomed.

Thanks for your quick feedback!

I've started working on it and realized the issue exists at two levels:

• EngineInterface implementations return generic types (eg.: Query\InsertQuery)
• QueryFactory also returns generic types, even though it delegates to concrete engines

This causes two problems:

1. Runtime checks required: Calling specific methods like onConflictDoXxxxxx requires method_exists() checks since there is no appropriate Interface
2. Static analysis failures: Using such methods raises static analysis errors like Method 'onConflictDoUpdate' not found in \Latitude\QueryBuilder\Query\InsertQuery

I propose a refactoring in 3 phases:

Phase 1: v4.5 (upcoming PR)

• Add QueryFactory\QueryFactoryInterface with appropriate implementations (MysqlQueryFactory, etc.) which will internally use their corresponding implementation of EngineInterface
• Add engine-specific implementations (SqliteQueryFactory, MysqlQueryFactory, PostgresQueryFactory) that:
  • Internally instantiate their corresponding engine
  • Return properly typed queries (Query\Sqlite\InsertQuery, etc.)

Phase 2: (future - v5)
Mark QueryFactory as deprecated

Phase 3: (future - v6?)

• Remove deprecated QueryFactory
• Incorporate engine loginc into specialized QueryFactoryInterface implementations
• Remove engines, no longer required

Rationale for Phase 3: Once QueryFactory is removed, engines would become implementation details—each SqliteQueryFactory would be the only consumer of SqliteEngine. At that point, merging the engine logic directly into the factory eliminates an unnecessary abstraction layer and simplifies the architecture.

This approach ensures zero breaking changes in v4.5 while providing immediate type safety benefits.

I'm ready to implement Phase 1. Does this work for you?

[shadowhand]

Sounds good!