Offer unified coordinate system classes, deprecate naming by count

Author: spawnia

CHANGELOG.md

@@ -9,6 +9,16 @@ See [GitHub releases](https://github.com/mll-lab/php-utils/releases).
 
 ## Unreleased
 
+## v5.2.0
+
+### Added
+
+- Add coordinate systems `CoordinateSystem4x3`, `CoordinateSystem8x6` and `CoordinateSystem12x8`
+
+### Changed
+
+- Deprecate coordinate systems `CoordinateSystem12Well`, `CoordinateSytem48Well` and `CoordinateSystem96Well`
+
 ## v5.1.0
 
 ### Added

src/FluidXPlate/FluidXPlate.php

@@ -4,7 +4,7 @@
 
 use Illuminate\Support\Collection;
 use MLL\Utils\Microplate\Coordinates;
-use MLL\Utils\Microplate\CoordinateSystem96Well;
+use MLL\Utils\Microplate\CoordinateSystem12x8;
 use MLL\Utils\Microplate\Enums\FlowDirection;
 use MLL\Utils\Microplate\Microplate;
 
@@ -15,7 +15,7 @@ class FluidXPlate
 
     public string $rackID;
 
-    /** @var Microplate<string, CoordinateSystem96Well> */
+    /** @var Microplate<string, CoordinateSystem12x8> */
     private Microplate $microplate;
 
     public function __construct(string $rackID)
@@ -27,12 +27,12 @@ public function __construct(string $rackID)
         $this->microplate = new Microplate(self::coordinateSystem());
     }
 
-    public static function coordinateSystem(): CoordinateSystem96Well
+    public static function coordinateSystem(): CoordinateSystem12x8
     {
-        return new CoordinateSystem96Well();
+        return new CoordinateSystem12x8();
     }
 
-    /** @param Coordinates<CoordinateSystem96Well> $coordinates */
+    /** @param Coordinates<CoordinateSystem12x8> $coordinates */
     public function addWell(Coordinates $coordinates, string $barcode): void
     {
         if (\Safe\preg_match(self::FLUIDX_BARCODE_REGEX, $barcode) === 0) {
@@ -42,7 +42,7 @@ public function addWell(Coordinates $coordinates, string $barcode): void
         $this->microplate->addWell($coordinates, $barcode);
     }
 
-    /** @return Coordinates<CoordinateSystem96Well> */
+    /** @return Coordinates<CoordinateSystem12x8> */
     public function addToNextFreeWell(string $content, FlowDirection $flowDirection): Coordinates
     {
         return $this->microplate->addToNextFreeWell($content, $flowDirection);

src/FluidXPlate/FluidXScanner.php

@@ -4,7 +4,6 @@
 
 use Illuminate\Support\Str;
 use MLL\Utils\Microplate\Coordinates;
-use MLL\Utils\Microplate\CoordinateSystem96Well;
 use MLL\Utils\StringUtil;
 
 /** Communicates with a FluidX scanner device and fetches results from it. */
@@ -87,8 +86,9 @@ public static function parseRawContent(string $rawContent): FluidXPlate
         }
 
         $plate = new FluidXPlate($id);
+        $coordinateSystem = FluidXPlate::coordinateSystem();
         foreach ($barcodes as $coordinates => $barcode) {
-            $plate->addWell(Coordinates::fromString($coordinates, new CoordinateSystem96Well()), $barcode);
+            $plate->addWell(Coordinates::fromString($coordinates, $coordinateSystem), $barcode);
         }
 
         return $plate;

src/Microplate/CoordinateSystem.php

@@ -4,6 +4,10 @@
 
 use Illuminate\Support\Arr;
 
+/**
+ * Children should be called `CoordinateSystemXxY`, where X is the number of columns and Y is the number of rows.
+ * Naming them by the number of positions is insufficient, e.g. it does not allow distinguishing between 3x4 and 4x3.
+ */
 abstract class CoordinateSystem
 {
     /** @return list<string> */

src/Microplate/CoordinateSystem12Well.php

@@ -2,18 +2,5 @@
 
 namespace MLL\Utils\Microplate;
 
-class CoordinateSystem12Well extends CoordinateSystem
-{
-    /** Duplicates @see CoordinateSystem::positionsCount() for static contexts. */
-    public const POSITIONS_COUNT = 12;
-
-    public function rows(): array
-    {
-        return range('A', 'C');
-    }
-
-    public function columns(): array
-    {
-        return range(1, 4);
-    }
-}
+/** @deprecated use CoordinateSystem4x3 */
+class CoordinateSystem12Well extends CoordinateSystem4x3 {}

src/Microplate/CoordinateSystem12x8.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\Microplate;
+
+class CoordinateSystem12x8 extends CoordinateSystem
+{
+    /** Duplicates @see CoordinateSystem::positionsCount() for static contexts. */
+    public const POSITIONS_COUNT = 96;
+
+    public function rows(): array
+    {
+        return range('A', 'H');
+    }
+
+    public function columns(): array
+    {
+        return range(1, 12);
+    }
+}

src/Microplate/CoordinateSystem48Well.php

@@ -2,18 +2,5 @@
 
 namespace MLL\Utils\Microplate;
 
-class CoordinateSystem48Well extends CoordinateSystem
-{
-    /** Duplicates @see CoordinateSystem::positionsCount() for static contexts. */
-    public const POSITIONS_COUNT = 48;
-
-    public function rows(): array
-    {
-        return range('A', 'F');
-    }
-
-    public function columns(): array
-    {
-        return range(1, 8);
-    }
-}
+/** @deprecated use CoordinateSystem8x6 */
+class CoordinateSystem48Well extends CoordinateSystem8x6 {}

src/Microplate/CoordinateSystem4x3.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\Microplate;
+
+class CoordinateSystem4x3 extends CoordinateSystem
+{
+    /** Duplicates @see CoordinateSystem::positionsCount() for static contexts. */
+    public const POSITIONS_COUNT = 12;
+
+    public function rows(): array
+    {
+        return range('A', 'C');
+    }
+
+    public function columns(): array
+    {
+        return range(1, 4);
+    }
+}

src/Microplate/CoordinateSystem8x6.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types=1);
+
+namespace MLL\Utils\Microplate;
+
+class CoordinateSystem8x6 extends CoordinateSystem
+{
+    /** Duplicates @see CoordinateSystem::positionsCount() for static contexts. */
+    public const POSITIONS_COUNT = 48;
+
+    public function rows(): array
+    {
+        return range('A', 'F');
+    }
+
+    public function columns(): array
+    {
+        return range(1, 8);
+    }
+}

src/Microplate/CoordinateSystem96Well.php

@@ -2,18 +2,5 @@
 
 namespace MLL\Utils\Microplate;
 
-class CoordinateSystem96Well extends CoordinateSystem
-{
-    /** Duplicates @see CoordinateSystem::positionsCount() for static contexts. */
-    public const POSITIONS_COUNT = 96;
-
-    public function rows(): array
-    {
-        return range('A', 'H');
-    }
-
-    public function columns(): array
-    {
-        return range(1, 12);
-    }
-}
+/** @deprecated use CoordinateSystem12x8 */
+class CoordinateSystem96Well extends CoordinateSystem12x8 {}