feature #2547 [Map] markers, polygons and polylines removal (sblondea…

…u, Kocal)

This PR was merged into the 2.x branch.

Discussion
----------

[Map] markers, polygons and polylines removal

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Issues        | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT

Add new methods to remove markers, polygons or polylines (map elements)
Map elements will be store in SplObjectStorage instead of arrays.

When create a map element, you can now add an optional identfier (string).
New methods `getMarker(string identifier)`, `getPolygon(string identifier)` and `getPolyline(string $identifier)` car retreive a map element from its identfiier.

example
    $departureMarker = new Marker (
        position: new Point(45.7640, 4.8357),
        title: 'Lyon',
        identifier: 'departure'
    )

    $map->addMarker($departureMarker);

    // remove marker with
    $map->removeMarker($departureMarker)
    // or
    $map->removeMarker($map->getMarker('departure'));

Commits
-------

7f48247 [Map] Minor adjustements
a27bd08 allow marker, polygone and polyline removal

src/Map/CHANGELOG.md

@@ -7,6 +7,10 @@
 -  Add `DistanceCalculatorInterface` interface and three implementations:
    `HaversineDistanceCalculator`, `SphericalCosineDistanceCalculator` and `VincentyDistanceCalculator`.
 -  Add `CoordinateUtils` helper, to convert decimal coordinates (`43.2109`) in DMS (`56° 78' 90"`)
+-  Add parameter `id` to `Marker`, `Polygon` and `Polyline` constructors
+-  Add method `Map::removeMarker(string|Marker $markerOrId)`
+-  Add method `Map::removePolygon(string|Polygon $polygonOrId)`
+-  Add method `Map::removePolyline(string|Polyline $polylineOrId)`
 
 ## 2.22
 

src/Map/doc/index.rst

@@ -136,6 +136,34 @@ You can add markers to a map using the ``addMarker()`` method::
         ))
     ;
 
+Remove elements from Map
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to remove elements like ``Marker``, ``Polygon`` and ``Polyline`` instances by using ``Map::remove*()`` methods::
+    
+    // Add elements
+    $map->addMarker($marker = new Marker(/* ... */));
+    $map->addPolygon($polygon = new Polygon(/* ... */));
+    $map->addPolyline($polyline = new Polyline(/* ... */));
+    
+    // And later, remove those elements
+    $map->removeMarker($marker);
+    $map->removePolygon($polygon);
+    $map->removePolyline($polyline);
+    
+If unfortunately you were unable to store an element instance, you can still remove them by passing the identifier string::
+ 
+    $map = new Map(/* ... */);
+    // Add elements
+    $map->addMarker(new Marker(id: 'my-marker', /* ... */));
+    $map->addPolygon(new Polygon(id: 'my-polygon', /* ... */));
+    $map->addPolyline(new Polyline(id: 'my-marker', /* ... */));
+    
+    // And later, remove those elements
+    $map->removeMarker('my-marker');
+    $map->removePolygon('my-polygon');
+    $map->removePolyline('my-marker');
+
 Add Polygons
 ~~~~~~~~~~~~
 

src/Map/src/Element.php

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map;
+
+/**
+ * @author Sylvain Blondeau <[email protected]>
+ *
+ * @internal
+ */
+interface Element
+{
+}

src/Map/src/Elements.php

@@ -0,0 +1,79 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map;
+
+/**
+ * Represents a collection of map elements.
+ *
+ * @author Sylvain Blondeau <[email protected]>
+ *
+ * @internal
+ */
+abstract class Elements
+{
+    private \SplObjectStorage $elements;
+
+    public function __construct(
+        array $elements,
+    ) {
+        $this->elements = new \SplObjectStorage();
+        foreach ($elements as $element) {
+            $this->elements->attach($element);
+        }
+    }
+
+    public function add(Element $element): static
+    {
+        $this->elements->attach($element, $element->id ?? $this->elements->getHash($element));
+
+        return $this;
+    }
+
+    private function getElement(string $id): ?Element
+    {
+        foreach ($this->elements as $element) {
+            if ($element->id === $id) {
+                return $element;
+            }
+        }
+
+        return null;
+    }
+
+    public function remove(Element|string $elementOrId): static
+    {
+        if (\is_string($elementOrId)) {
+            $elementOrId = $this->getElement($elementOrId);
+        }
+
+        if (null === $elementOrId) {
+            return $this;
+        }
+
+        if ($this->elements->contains($elementOrId)) {
+            $this->elements->detach($elementOrId);
+        }
+
+        return $this;
+    }
+
+    public function toArray(): array
+    {
+        foreach ($this->elements as $element) {
+            $elements[] = $element->toArray();
+        }
+
+        return $elements ?? [];
+    }
+
+    abstract public static function fromArray(array $elements): self;
+}

src/Map/src/Map.php

@@ -20,27 +20,28 @@
  */
 final class Map
 {
+    private Markers $markers;
+    private Polygons $polygons;
+    private Polylines $polylines;
+
+    /**
+     * @param Marker[]   $markers
+     * @param Polygon[]  $polygons
+     * @param Polyline[] $polylines
+     */
     public function __construct(
         private readonly ?string $rendererName = null,
         private ?MapOptionsInterface $options = null,
         private ?Point $center = null,
         private ?float $zoom = null,
         private bool $fitBoundsToMarkers = false,
-        /**
-         * @var array<Marker>
-         */
-        private array $markers = [],
-
-        /**
-         * @var array<Polygon>
-         */
-        private array $polygons = [],
-
-        /**
-         * @var array<Polyline>
-         */
-        private array $polylines = [],
+        array $markers = [],
+        array $polygons = [],
+        array $polylines = [],
     ) {
+        $this->markers = new Markers($markers);
+        $this->polygons = new Polygons($polygons);
+        $this->polylines = new Polylines($polylines);
     }
 
     public function getRendererName(): ?string
@@ -88,21 +89,42 @@ public function hasOptions(): bool
 
     public function addMarker(Marker $marker): self
     {
-        $this->markers[] = $marker;
+        $this->markers->add($marker);
+
+        return $this;
+    }
+
+    public function removeMarker(Marker|string $markerOrId): self
+    {
+        $this->markers->remove($markerOrId);
 
         return $this;
     }
 
     public function addPolygon(Polygon $polygon): self
     {
-        $this->polygons[] = $polygon;
+        $this->polygons->add($polygon);
+
+        return $this;
+    }
+
+    public function removePolygon(Polygon|string $polygonOrId): self
+    {
+        $this->polygons->remove($polygonOrId);
 
         return $this;
     }
 
     public function addPolyline(Polyline $polyline): self
     {
-        $this->polylines[] = $polyline;
+        $this->polylines->add($polyline);
+
+        return $this;
+    }
+
+    public function removePolyline(Polyline|string $polylineOrId): self
+    {
+        $this->polylines->remove($polylineOrId);
 
         return $this;
     }
@@ -124,9 +146,9 @@ public function toArray(): array
             'zoom' => $this->zoom,
             'fitBoundsToMarkers' => $this->fitBoundsToMarkers,
             'options' => $this->options ? MapOptionsNormalizer::normalize($this->options) : [],
-            'markers' => array_map(static fn (Marker $marker) => $marker->toArray(), $this->markers),
-            'polygons' => array_map(static fn (Polygon $polygon) => $polygon->toArray(), $this->polygons),
-            'polylines' => array_map(static fn (Polyline $polyline) => $polyline->toArray(), $this->polylines),
+            'markers' => $this->markers->toArray(),
+            'polygons' => $this->polygons->toArray(),
+            'polylines' => $this->polylines->toArray(),
         ];
     }
 

src/Map/src/Marker.php

@@ -18,17 +18,18 @@
  *
  * @author Hugo Alliaume <[email protected]>
  */
-final readonly class Marker
+final readonly class Marker implements Element
 {
     /**
      * @param array<string, mixed> $extra Extra data, can be used by the developer to store additional information and
      *                                    use them later JavaScript side
      */
     public function __construct(
-        private Point $position,
-        private ?string $title = null,
-        private ?InfoWindow $infoWindow = null,
-        private array $extra = [],
+        public Point $position,
+        public ?string $title = null,
+        public ?InfoWindow $infoWindow = null,
+        public array $extra = [],
+        public ?string $id = null,
     ) {
     }
 
@@ -38,6 +39,7 @@ public function __construct(
      *     title: string|null,
      *     infoWindow: array<string, mixed>|null,
      *     extra: array,
+     *     id: string|null
      * }
      */
     public function toArray(): array
@@ -47,6 +49,7 @@ public function toArray(): array
             'title' => $this->title,
             'infoWindow' => $this->infoWindow?->toArray(),
             'extra' => $this->extra,
+            'id' => $this->id,
         ];
     }
 
@@ -56,6 +59,7 @@ public function toArray(): array
      *     title: string|null,
      *     infoWindow: array<string, mixed>|null,
      *     extra: array,
+     *     id: string|null
      * } $marker
      *
      * @internal

src/Map/src/Markers.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Map;
+
+/**
+ * Represents a Marker collection.
+ *
+ * @author Sylvain Blondeau <[email protected]>
+ *
+ * @internal
+ */
+final class Markers extends Elements
+{
+    public static function fromArray(array $elements): self
+    {
+        $elementObjects = [];
+
+        foreach ($elements as $element) {
+            $elementObjects[] = Marker::fromArray($element);
+        }
+
+        return new self(elements: $elementObjects);
+    }
+}

src/Map/src/Polygon.php

@@ -18,7 +18,7 @@
  *
  * @author [Pierre Svgnt]
  */
-final readonly class Polygon
+final readonly class Polygon implements Element
 {
     /**
      * @param array<string, mixed> $extra Extra data, can be used by the developer to store additional information and use them later JavaScript side
@@ -28,6 +28,7 @@ public function __construct(
         private ?string $title = null,
         private ?InfoWindow $infoWindow = null,
         private array $extra = [],
+        public ?string $id = null,
     ) {
     }
 
@@ -39,6 +40,7 @@ public function __construct(
      *     title: string|null,
      *     infoWindow: array<string, mixed>|null,
      *     extra: array,
+     *     id: string|null
      * }
      */
     public function toArray(): array
@@ -48,6 +50,7 @@ public function toArray(): array
             'title' => $this->title,
             'infoWindow' => $this->infoWindow?->toArray(),
             'extra' => $this->extra,
+            'id' => $this->id,
         ];
     }
 
@@ -57,6 +60,7 @@ public function toArray(): array
      *     title: string|null,
      *     infoWindow: array<string, mixed>|null,
      *     extra: array,
+     *     id: string|null
      * } $polygon
      *
      * @internal