[RFC]: Decide which PhpDb\Sql classes become final #213

Proposed Version

Next major

Basic Information

Mago reports 44 class-must-be-final findings in src/Sql, all baselined. Resolving them means deciding which classes are extension points, which a mechanical fix can't do.

Classes reported:

• Statements: Select, Delete, Update, InsertIgnore, Combine, Sql, Join, Where, Having, Platform\Platform
• DDL: Ddl\CreateTable, Ddl\AlterTable, Ddl\DropTable, Ddl\Index\Index, the 17 concrete Ddl\Column\* classes, and Ddl\Constraint\{Check, ForeignKey, PrimaryKey, UniqueKey}
• Predicates: Predicate\{Operator, Expression, Literal, IsNotNull, NotBetween, NotIn, NotLike}
• Exceptions: Predicate\Exception\{InvalidArgumentException, RuntimeException}

Background

The driver packages extend several of these classes:

• Every platform decorator extends Select, Insert, Update, Delete, CreateTable or AlterTable (see Sql\Platform: decorator contract is incomplete and Platform's per-platform registry is unused #175).
• phpdb-mysql ships its own DDL decorators under src/Sql/Ddl.
• The test suite subclasses Delete, Update and Insert (DeleteIgnore, UpdateIgnore, Replace).

Metadata went through the same decision: its object classes were made final.

Considerations

• Making a class final breaks every subclass of it. The statement and DDL classes that decorators extend cannot become final without replacing inheritance with composition.
• Leaf predicates, concrete column types and the exception classes have no known subclasses.

Proposal(s)

1. Make final the classes with no known subclasses: the leaf predicates, the Predicate\Exception classes, Join, Where and Having. Check the driver packages first.
2. Keep the statement and DDL classes non-final, and add a per-path class-must-be-final exclusion in mago.toml documenting why, as already done for prefer-self-return-type.
3. Settle Platform\Platform as part of Sql\Platform: decorator contract is incomplete and Platform's per-platform registry is unused #175, which already proposes making it final.

Appendix/Additional Info

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