✨ Add new custom-cache-suffix option (#239)

As discussed in 234.

Includes tests.

Fixes 234

Co-authored-by: jrfnl <jrfnl@users.noreply.github.com>

.github/workflows/continuous-integration.yml

@@ -218,6 +218,18 @@ jobs:
           dependency-versions: "${{ matrix.dependency-versions }}"
           custom-cache-key: 'my-super-custom-cache-key'
 
+      - name: Clean up between tests
+        run: |
+          git clean -ffdx && git reset --hard HEAD
+          composer clear-cache
+
+      - name: "Test: custom cache suffix"
+        uses: ./
+        with:
+          working-directory: "${{ matrix.working-directory }}"
+          dependency-versions: "${{ matrix.dependency-versions }}"
+          custom-cache-suffix: $(/bin/date -u --date='last Mon' "+%F")
+
   run-no-cleanup:
     needs: test
     name: "Run unclean"

README.md

@@ -148,6 +148,32 @@ wish to update the cache.
     custom-cache-key: "my-custom-cache-key"
 ```
 
+#### custom-cache-suffix
+
+`ramsey/composer-install` will auto-generate a cache key which is composed of
+the following elements:
+* The OS image name, like `ubuntu-latest`.
+* The exact PHP version, like `8.1.11`.
+* The options passed via `composer-options`.
+* The dependency version setting as per `dependency-versions`.
+* The working directory as per `working-directory`.
+* A hash of the `composer.json` and/or `composer.lock` files.
+
+If you don't want to generate your own cache key, but do want to make the cache key
+even more specific, you can specify a suffix to be added to the cache key via the
+`custom-cache-suffix` parameter.
+
+```yaml
+# Adds a suffix to the cache key which is equivalent to the full date-time
+# of "last Monday 00:00", which means that the cache will be force refreshed
+# via the first workflow which is run every Monday.
+- uses: "ramsey/composer-install@v2"
+  with:
+    custom-cache-suffix: $(/bin/date -u --date='last Mon' "+%F")
+```
+
+:warning: Note: specifying a `custom-cache-key` will take precedence over the `custom-cache-suffix`.
+
 ### Matrix Example
 
 GitHub Workflows allow you to set up a [job matrix](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix),

action.yml

@@ -30,6 +30,10 @@ inputs:
     description: >-
       A custom cache key to use instead of an auto-generated cache key.
     required: false
+  custom-cache-suffix:
+    description: >-
+      A custom suffix to add to the auto-generated cache key.
+    required: false
 
 runs:
   using: "composite"
@@ -66,6 +70,7 @@ runs:
           "${{ inputs.composer-options }}" \
           "${{ hashFiles('**/composer.json', '**/composer.lock') }}" \
           "${{ inputs.custom-cache-key }}" \
+          "${{ inputs.custom-cache-suffix }}" \
           "${{ inputs.working-directory }}"
 
     - name: "Cache Composer dependencies"

bin/cache_key.sh

@@ -25,7 +25,8 @@ dependency_versions="${3:-locked}"
 composer_options="${4}"
 files_hash="${5}"
 custom_cache_key="${6}"
-working_directory="${7}"
+custom_cache_suffix="${7}"
+working_directory="${8}"
 
 key=()
 restore_key=()
@@ -41,7 +42,7 @@ esac
 if [ -n "${custom_cache_key}" ]; then
     key+=("${custom_cache_key}")
 else
-    key+=("${runner_os}" "php" "${php_version}" "composer" "${composer_options}" "${dependency_versions}" "${working_directory}")
+    key+=("${runner_os}" "php" "${php_version}" "composer" "${composer_options}" "${dependency_versions}" "${working_directory}" "${custom_cache_suffix}")
 
     restore_key=("$(make_key "${key[@]}")-")
 

tests/expect/cache_key_06.exp

@@ -9,7 +9,7 @@ set gitHubOutputFile cache_key_output_06.txt
 set ::env(GITHUB_OUTPUT) $gitHubOutputFile
 
 set timeout 3
-spawn ../../bin/cache_key.sh "Linux" "8.1.1" "" "" "long-files-hash" "" "path/to/working/dir"
+spawn ../../bin/cache_key.sh "Linux" "8.1.1" "" "" "long-files-hash" "" "" "path/to/working/dir"
 match_max 100000
 
 expect -exact "::debug::Cache primary key is 'Linux-php-8.1.1-composer-locked-path/to/working/dir-long-files-hash'"

tests/expect/cache_key_08.exp

@@ -0,0 +1,50 @@
+#!/usr/bin/env -S expect -f
+
+# For testing environment variables written to GITHUB_ENV
+set gitHubEnvFile cache_key_08.txt
+set ::env(GITHUB_ENV) $gitHubEnvFile
+
+# For testing outputs variables written to GITHUB_OUTPUT
+set gitHubOutputFile cache_key_output_08.txt
+set ::env(GITHUB_OUTPUT) $gitHubOutputFile
+
+set timeout 3
+spawn ../../bin/cache_key.sh "Linux" "8.1.12" "lowest" "--ignore-platform-req=php+" "long-files-hash" "" "suffix"
+match_max 100000
+
+expect -exact "::debug::Cache primary key is 'Linux-php-8.1.12-composer---ignore-platform-req=php+-lowest-suffix-long-files-hash'"
+expect -exact "::debug::Cache restore keys are 'Linux-php-8.1.12-composer---ignore-platform-req=php+-lowest-suffix-'"
+expect eof
+
+# Confirm environment variables.
+set fp [open $gitHubEnvFile r]
+set fileData [read $fp]
+close $fp
+
+set expectedValue "CACHE_RESTORE_KEY<<EOF
+Linux-php-8.1.12-composer---ignore-platform-req=php+-lowest-suffix-
+EOF
+"
+
+if { $expectedValue != $fileData } {
+    puts "\nExpected environment variable does not match. Received:\n"
+    puts $fileData
+    exit 1
+}
+
+# Verify output variables have been set correctly.
+set fp [open $gitHubOutputFile r]
+set fileData [read $fp]
+close $fp
+
+set expectedValue "key=Linux-php-8.1.12-composer---ignore-platform-req=php+-lowest-suffix-long-files-hash\n"
+
+if { $expectedValue != $fileData } {
+    puts "\nExpected output variable does not match. Received:\n"
+    puts $fileData
+    exit 1
+}
+
+# Clean up
+file delete $gitHubEnvFile
+file delete $gitHubOutputFile