[TASK] Add Positionable interface and implementing trait

This is for CSS items which have a position in the document.

New methods are added:
- `getLineNumber` to replace `getLineNo`;
- `getColumnNumber` to replace `getColNo`.

These return a nullable `int`, instead of using zero to indicate absence.

The old methods are now deprecated,
but defined in the interface and implemented in the trait.

Note that this change only adds the interface and trait.
It does not modify any classes to actually implement or use these.

Part of #1207.

Author: JakeQZ

src/Position/Position.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Position;
+
+/**
+ * Provides a standard reusable implementation of `Positionable`.
+ *
+ * @internal
+ *
+ * @phpstan-require-implements Positionable
+ */
+trait Position
+{
+    /**
+     * @var int<1, max>|null
+     */
+    protected $lineNumber;
+
+    /**
+     * @var int<0, max>|null
+     */
+    protected $columnNumber;
+
+    /**
+     * @return int<1, max>|null
+     */
+    public function getLineNumber(): ?int
+    {
+        return $this->lineNumber;
+    }
+
+    /**
+     * @return int<0, max>
+     */
+    public function getLineNo(): int
+    {
+        return $this->getLineNumber() ?? 0;
+    }
+
+    /**
+     * @return int<0, max>|null
+     */
+    public function getColumnNumber(): ?int
+    {
+        return $this->columnNumber;
+    }
+
+    /**
+     * @return int<0, max>
+     */
+    public function getColNo(): int
+    {
+        return $this->getColumnNumber() ?? 0;
+    }
+
+    /**
+     * @param int<0, max>|null $lineNumber
+     * @param int<0, max>|null $columnNumber
+     */
+    public function setPosition(?int $lineNumber, ?int $columnNumber = null): void
+    {
+        // The conditional is for backwards compatibility (backcompat); `0` will not be allowed in future.
+        $this->lineNumber = $lineNumber !== 0 ? $lineNumber : null;
+        $this->columnNumber = $columnNumber;
+    }
+}

src/Position/Positionable.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Position;
+
+/**
+ * Represents a CSS item that may have a position in the source CSS document (line number and possibly column number).
+ *
+ * A standard implementation of this interface is available in the `Position` trait.
+ */
+interface Positionable
+{
+    /**
+     * @return int<1, max>|null
+     */
+    public function getLineNumber(): ?int;
+
+    /**
+     * @deprecated in version 9.0.0, will be removed in v10.0. Use `getLineNumber()` instead.
+     *
+     * @return int<0, max>
+     */
+    public function getLineNo(): int;
+
+    /**
+     * @return int<0, max>|null
+     */
+    public function getColumnNumber(): ?int;
+
+    /**
+     * @deprecated in version 9.0.0, will be removed in v10.0. Use `getColumnNumber()` instead.
+     *
+     * @return int<0, max>
+     */
+    public function getColNo(): int;
+
+    /**
+     * @param int<0, max>|null $lineNumber
+     *        Providing zero for this parameter is deprecated in version 9.0.0, and will not be supported from v10.0.
+     *        Use `null` instead when no line number is available.
+     * @param int<0, max>|null $columnNumber
+     */
+    public function setPosition(?int $lineNumber, ?int $columnNumber = null): void;
+}

tests/Unit/Position/Fixtures/ConcretePosition.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\Position\Fixtures;
+
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
+
+final class ConcretePosition implements Positionable
+{
+    use Position;
+}