[RFC]: Split Adapter::query() into prepareQuery()/executeQuery()

[simon-mundy]

Proposed Version

0.6.0

Basic Information

Currently Adapter::query() conflates two distinct concerns behind a single method and a stringly-typed second argument (ParameterContainer|array|string $parametersOrQueryMode): preparing a statement (optionally binding parameters) and executing SQL directly. The return type is a three-way union (Driver\StatementInterface|ResultSet\ResultSetInterface|Driver\ResultInterface) that callers have to narrow themselves. This proposal seeks to split query() into two single-purpose methods and deprecate query() as a BC-preserving proxy.

Background

No response

Considerations

No response

Proposal(s)

1. Split query() into prepareQuery()/executeQuery()

public function prepareQuery(
 string $sql,
 ParameterContainer|array $parameters = [],
): Driver\StatementInterface;
// always prepares (and binds if parameters given), never executes

public function executeQuery(
 string|Driver\StatementInterface $sql,
 ?ResultSet\ResultSetInterface $resultPrototype = null,
): ResultSet\ResultSetInterface|Driver\ResultInterface;
// executes raw SQL or a prepared Statement, wraps the result if it's a query result

query() stays for BC, deprecated in favour of the above, proxying to prepareQuery()/executeQuery() internally. Both new methods are declared on AdapterInterface as well as Adapter — external implementors of AdapterInterface will need to add both methods to remain compatible. This is a deliberate BC break, superseding the original plan to land the methods on Adapter only during 0.x.

2. Driver\ResultInterface::getQueryResult()

Alongside isQueryResult(), add a strictly-typed accessor that returns the seeded ResultSet\ResultSetInterface directly, instead of callers re-deriving the clone/initialize dance themselves:

/**
 * @throws Exception\RuntimeException if !isQueryResult()
 */
public function getQueryResult(?ResultSet\ResultSetInterface $resultPrototype = null): ResultSet\ResultSetInterface;

executeQuery() delegates to this internally instead of duplicating the clone/initialize logic in Adapter.

Appendix/Additional Info

No response