Install specific Cachetool version

- Force the use of a specific Cachetool version.
- Use the latest version if none is defined and installed.
- Support the obsolete "cachetool_url" option for backwards
  compatibility and inform to switch to the "cachetool_version"
  option for improved version control.
- Make sure that the downloaded file is named "cachetool.phar".
- Download the file to .dep/cachetool.phar instead of
  current/cachetool.phar, similar to how Composer is handled.

Author: alexander-nitsche-governikus

contrib/cachetool.php

@@ -49,21 +49,31 @@
 namespace Deployer;
 
 set('cachetool', '');
-/**
- * URL to download cachetool from if it is not available
- *
- * CacheTool 9.x works with PHP >=8.1
- * CacheTool 8.x works with PHP >=8.0
- * CacheTool 7.x works with PHP >=7.3
- */
-set('cachetool_url', 'https://github.com/gordalina/cachetool/releases/download/9.1.0/cachetool.phar');
 set('cachetool_args', '');
+set('cachetool_version', null);
+
+// Returns Cachetool binary path if found. Otherwise, tries to install Cachetool to `.dep/cachetool.phar`.
 set('bin/cachetool', function () {
-    if (!test('[ -f {{release_or_current_path}}/cachetool.phar ]')) {
-        run("cd {{release_or_current_path}} && curl -sLO {{cachetool_url}}");
+    if (test('[ -f {{deploy_path}}/.dep/cachetool.phar ]')) {
+        if (empty(get('cachetool_version')) || preg_match(parse('/Cachetool.*{{cachetool_version}}/'), run('{{bin/php}} {{deploy_path}}/.dep/cachetool.phar --version'))) {
+            return '{{bin/php}} {{deploy_path}}/.dep/cachetool.phar';
+        }
     }
-    return '{{release_or_current_path}}/cachetool.phar';
+
+    if (has('cachetool_url')) {
+        warning('The option "cachetool_url" is outdated, use "cachetool_version" instead.');
+    }
+
+    $urlLatest = 'https://github.com/gordalina/cachetool/releases/latest/download/cachetool.phar';
+    $urlVersion = 'https://github.com/gordalina/cachetool/releases/download/%1$s/cachetool.phar';
+    $url = get('cachetool_version') ? sprintf($urlVersion, get('cachetool_version')) : (has('cachetool_url') ? get('cachetool_url') : $urlLatest);
+    $versionAsName = get('cachetool_version') ? ' {{cachetool_version}}' : '';
+    warning("Cachetool{$versionAsName} wasn't found. Installing to \"{{deploy_path}}/.dep/cachetool.phar\".");
+    run("cd {{deploy_path}} && curl -sSL $url -o cachetool.phar");
+    run('mv {{deploy_path}}/cachetool.phar {{deploy_path}}/.dep/cachetool.phar');
+    return '{{bin/php}} {{deploy_path}}/.dep/cachetool.phar';
 });
+
 set('cachetool_options', function () {
     $options = (array) get('cachetool');
     $fullOptions = (string) get('cachetool_args');

docs/contrib/cachetool.md

@@ -85,42 +85,36 @@ http://gordalina.github.io/cachetool/
 
 
 
-### cachetool_url
-[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L59)
+### cachetool_args
+[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L52)
 
-URL to download cachetool from if it is not available
 
-CacheTool 9.x works with PHP >=8.1
-CacheTool 8.x works with PHP >=8.0
-CacheTool 7.x works with PHP >=7.3
 
-```php title="Default value"
-'https://github.com/gordalina/cachetool/releases/download/9.1.0/cachetool.phar'
-```
 
 
-### cachetool_args
-[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L60)
+### cachetool_version
+[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L53)
 
 
 
+```php title="Default value"
+null
+```
 
 
 ### bin/cachetool
-[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L61)
+[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L56)
 
+Returns Cachetool binary path if found. Otherwise, tries to install Cachetool to `.dep/cachetool.phar`.
+:::info Autogenerated
+The value of this configuration is autogenerated on access.
+:::
 
 
-```php title="Default value"
-if (!test('[ -f {{release_or_current_path}}/cachetool.phar ]')) {
-run("cd {{release_or_current_path}} && curl -sLO {{cachetool_url}}");
-}
-return '{{release_or_current_path}}/cachetool.phar';
-```
 
 
 ### cachetool_options
-[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L67)
+[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L77)
 
 
 :::info Autogenerated
@@ -134,23 +128,23 @@ The value of this configuration is autogenerated on access.
 ## Tasks
 
 ### cachetool\:clear\:opcache {#cachetool-clear-opcache}
-[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L89)
+[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L99)
 
 Clears OPcode cache.
 
 Clear opcache cache
 
 
 ### cachetool\:clear\:apcu {#cachetool-clear-apcu}
-[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L100)
+[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L110)
 
 Clears APCu system cache.
 
 Clear APCu cache
 
 
 ### cachetool\:clear\:stat {#cachetool-clear-stat}
-[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L111)
+[Source](https://github.com/deployphp/deployer/blob/master/contrib/cachetool.php#L121)
 
 Clears file status and realpath caches.