Add interface and trait for classes with a `lineNumber`

[JakeQZ]

Some things to decide first:

• Should this also include column number (which may not be used in all cases)?
• What should the interface be called (Positionable?)?

And some changes that could be made in the course of this:

• Rename getLineNo() to getLineNumber() as follows:
  • Add both methods to the interface, with getLineNo marked as deprecated from 9.0, to be removed in 10.0;
  • The trait can handle forwarding getLineNo to getLineNumber (or simply access the property), so that no changes to implementing classes are required, provided they can use the trait;
• Use null to indicate 'no line number' instead of 0:
  • Again, the trait should be able to take care of the details, avoiding changes to implementing classes.

[oliverklee]

Should this also include column number (which may not be used in all cases)?

Yes, I'd like that. I propose we make both properties optional and nullable for this.

What should the interface be called (Positionable?)?

I quite like Positionable!

Rename getLineNo() to getLineNumber() as follows:

Yes, sounds good.

I propose getLineNo() then returns a non-nullable int (for backwards compatibality), while getLineNumber() returns int<1, max>|null.

I'd also like to move setting the position out of the constructors (in a separate PR). To make this possible, I think the interface should have (internal) setters for line number and column number. What do you think?

[JakeQZ]

Agree with everything (particularly using null instead of 0 to indicate absence), up until the final comment:

I'd also like to move setting the position out of the constructors (in a separate PR). To make this possible, I think the interface should have (internal) setters for line number and column number. What do you think?

I'd like to do the other bits first, then see how things look. As part of a separate later PR, we can also add setters to the interface then, if we decide that's what we want to do.

(Traits can have constructors, but they are simply 'copied' to the using class like the other methods, so if the using class has it's own constructor, the trait's constructor will be replaced, and can't be called using NameOfTrait::__construct(), though can with an additional use.)

[JakeQZ]

I'd also like to move setting the position out of the constructors (in a separate PR). To make this possible, I think the interface should have (internal) setters for line number and column number. What do you think?

Rule has a setPosition() method which sets both line and column number. It's the only class that has a column number (AFAICS).

The various other classes all have a line number only, but I don't think they would be bothered by having an optional column number, with the workings provided by a trait for the interface - they just simply wouldn't use it.

So I think

    public function setPosition(?int $lineNumber, ?int $columnNumber = null): void;

works for the interface, and also provides a method for constructors of classes using the trait to call without being concerned what the actual property name is.

move setting the position out of the constructors (in a separate PR)

With the int types nullable, this will be possible in a future PR.

I propose getLineNo() then returns a non-nullable int (for backwards compatibality), while getLineNumber() returns int<1, max>|null.

Ah. I've added #1221 as a demo (WIP), but not covered that point.