refactor: rename for clarity that it is an arbitrary path setting

Author: m1rm

docs/hosts.md

@@ -78,10 +78,10 @@ host('example.org')
 
 ### Path
 
-You can store an arbitrary path string in the `path` config (for example to reuse in `{{path}}` placeholders). On a host, prefer `setPath()` over `set('path', …)` so the value is typed as a string and IDEs or static analysis can catch mistakes such as passing a number, which the generic `set()` method does not flag. In the recipe file (outside a host definition), use the global [set()](api.md#set) function—for example `set('path', '/var/www/myapp')`.
+You can store an arbitrary path string in the `path` config (for example to reuse in `{{path}}` placeholders). On a host, prefer `setPathConfig()` over `set('path', …)` so the name reflects that this is the `path` *configuration* value (and not, for example, the deployment root), and so the value is typed as a string. IDEs or static analysis can then catch mistakes such as passing a number, which the generic `set()` method does not flag. In the recipe file (outside a host definition), use the global [set()](api.md#set) function—for example `set('path', '/var/www/myapp')`.
 
 ```php
-host('example.org')->setPath('/var/www/myapp');
+host('example.org')->setPathConfig('/var/www/myapp');
 
 set('path', '/var/www/myapp');
 ```
@@ -138,7 +138,7 @@ set('default_selector', "stage=prod&role=web,role=special");
 | **`port`**             | SSH port. Default is `22`.                                                                     |
 | **`config_file`**      | SSH config file location. Default is `~/.ssh/config`.                                          |
 | **`identity_file`**    | SSH private key file. E.g., `~/.ssh/id_rsa`.                                                   |
-| **`path`**             | Optional path string for custom use (e.g. `{{path}}`). Use `setPath()` on the host for a typed setter. |
+| **`path`**             | Optional path string for custom use (e.g. `{{path}}`). Use `setPathConfig()` on the host for a typed setter. |
 | **`forward_agent`**    | Enable SSH agent forwarding. Default is `true`.                                                |
 | **`ssh_multiplexing`** | Enable SSH multiplexing for performance. Default is `true`.                                    |
 | **`shell`**            | Shell to use. Default is `bash -ls`.                                                           |

src/Host/Host.php

@@ -123,17 +123,6 @@ public function getPort(): int|string|null
         return $this->config->get('port', null);
     }
 
-    public function setPath(string $path): self
-    {
-        $this->config->set('path', $path);
-        return $this;
-    }
-
-    public function getPath(): ?string
-    {
-        return $this->config->get('path', null);
-    }
-
     public function setConfigFile(string $file): self
     {
         $this->config->set('config_file', $file);
@@ -211,6 +200,29 @@ public function getDeployPath(): ?string
         return $this->config->get('deploy_path', null);
     }
 
+    /**
+     * Set the optional `path` configuration value (the `path` key).
+     *
+     * Use it for recipe-defined or host-specific data exposed as `{{path}}` in task strings. This is
+     * not the remote deployment root; for that, use `setDeployPath()`.
+     */
+    public function setPathConfig(string $value): self
+    {
+        $this->config->set('path', $value);
+        return $this;
+    }
+
+    /**
+     * Get the optional `path` configuration value, or `null` if the key is not set.
+     *
+     * This is the `path` key (e.g. for `{{path}}` in tasks), not the remote deployment directory;
+     * for that, use `getDeployPath()`.
+     */
+    public function getPathConfig(): ?string
+    {
+        return $this->get('path', null);
+    }
+
     public function setLabels(array $labels): self
     {
         $this->config->set('labels', $labels);

tests/src/Host/HostTest.php

@@ -30,7 +30,7 @@ public function testHost()
         $host
             ->setHostname('hostname')
             ->setRemoteUser('remote_user')
-            ->setPath('/var/www')
+            ->setPathConfig('/var/www')
             ->setPort(22)
             ->setConfigFile('~/.ssh/config')
             ->setIdentityFile('~/.ssh/id_rsa')
@@ -41,7 +41,7 @@ public function testHost()
         self::assertStringContainsString('host', $host->getTag());
         self::assertEquals('hostname', $host->getHostname());
         self::assertEquals('remote_user', $host->getRemoteUser());
-        self::assertEquals('/var/www', $host->getPath());
+        self::assertEquals('/var/www', $host->getPathConfig());
         self::assertEquals(22, $host->getPort());
         self::assertEquals('~/.ssh/config', $host->getConfigFile());
         self::assertEquals('~/.ssh/id_rsa', $host->getIdentityFile());
@@ -89,7 +89,7 @@ public function testHostWithPathFromParams()
             ->set('env', $value)
             ->set('path', '{{env}}');
 
-        self::assertEquals($value, $host->getPath());
+        self::assertEquals($value, $host->getPathConfig());
     }
 
     public function testHostWithUserFromConfig()