[RFC]: Read string specifications through a typed accessor in AbstractSql #211

Proposed Version

Next minor

Basic Information

Delete, Insert, Update, Combine and CreateTable render clauses with str_replace() on a specification read straight from $this->specifications[static::SPECIFICATION_*]. $specifications holds both string templates and nested parameter specifications, so the analyzer cannot tell that a given entry is a string. It also cannot tell that the key exists, since subclasses can replace the whole array. This accounts for 26 analyzer findings in src/Sql: possibly-undefined-string-array-index, possibly-null-argument, possibly-invalid-argument and one invalid-return-statement.

Background

At runtime, a missing or non-string specification produces an "Undefined array key" warning followed by a TypeError from str_replace(), or renders an array where a string is expected. Neither error names the specification. Subclasses (the *Ignore test assets, and driver decorators) replace individual entries, so this can happen outside the library.

Considerations

• A new protected method on AbstractSql. A subclass that already declares a method with the same name would conflict; none of the driver packages do.
• The failure changes from a warning plus TypeError to a named exception. That only affects specifications that are already broken.

Proposal(s)

/**
 * @throws Exception\RuntimeException
 */
protected function getStringSpecification(string $name): string
{
    $specification = $this->specifications[$name] ?? null;
    if (! is_string($specification)) {
        throw Exception\RuntimeException::forInvalidSpecification($name);
    }

    return $specification;
}

Each str_replace(..., $this->specifications[static::SPECIFICATION_X]) becomes str_replace(..., $this->getStringSpecification(static::SPECIFICATION_X)). A matching named constructor and message constant are added to Sql\Exception\RuntimeException.

Appendix/Additional Info

Finding counts are from mago analyze --ignore-baseline src/Sql once the docblock typing in #204 is applied.