Last updated: 12 November 2026. See theupdate logat the end.
Most of the time in a Laravel CI run goes to downloading packages: Composer dependencies on every run, and npm packages whenever you build front-end assets. Each run starts on a clean machine, so without a cache the same files are fetched again and again. This is Part 2 of the series. Part 1 built the test workflow; here we add caching to it, and Part 3 reuses the same steps in the deploy job.
I did not time any run, so there are no speed-up numbers here. What follows is the configuration, why each line exists, and how to confirm the cache is working in your own logs.
What to cache, and what not to
Cache the package manager's download cache, not the installed vendor directory. The setup-php README says it plainly: do not cache vendor with actions/cache, because that has side effects. The download cache is safe, since composer install still runs and builds a correct vendor from the lock file, it just skips the downloads.
Composer
Add two steps before composer install in the test job:
- name: Find the Composer cache directory
id: composer-cache
run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
- name: Cache Composer downloads
uses: actions/cache@v6
with:
path: ${{ steps.composer-cache.outputs.dir }}
key: composer-${{ runner.os }}-php${{ matrix.php }}-${{ hashFiles('composer.lock') }}
restore-keys: |
composer-${{ runner.os }}-php${{ matrix.php }}-
- name: Install Composer dependencies
run: composer install --prefer-dist --no-interaction --no-progress
The first step asks Composer where its cache lives instead of hardcoding a path. Running that same command from the workflow file locally printed a path ending in composer/files, and the step wrote it as dir=... into the step output:
dir=<home>/composer/files
The second step is actions/cache (v6 at the time of writing). It restores the directory at the start and saves it when the job ends successfully.
How the key works
-
keyhas the OS, the PHP version from the matrix and a hash ofcomposer.lock. When you change a dependency, the hash changes, so you get a fresh cache entry. -
restore-keysis a list of prefixes tried in order when the exact key isn't found. After a lock file change, the job restores the most recent cache for the same OS and PHP version, so most packages are still local and Composer only downloads what changed. The action's README describes this as restoring a stale cache when there is no exact match. - The PHP version is in the key so each matrix entry has its own cache.
The cache-hit output is true only for an exact key match, and false when a restore-keys entry or nothing was restored, per the action's README. A partial restore is normal and good.
npm
If the job builds assets (Part 3 does), actions/setup-node can cache npm for you:
- name: Set up Node.js
uses: actions/setup-node@v7
with:
node-version: '24'
cache: npm
- name: Build front-end assets
run: |
npm ci
npm run build
With cache: npm the action caches npm's package data and, according to its README, looks for package-lock.json (or npm-shrinkwrap.json, yarn.lock) in the repository root and uses its hash as part of the key. If your lock file is somewhere else, set cache-dependency-path. Use npm ci, not npm install: it installs exactly what the lock file says and fails if package.json and the lock file disagree.
Read the setup-node README for your version before relying on defaults. It describes automatic npm caching when package.json has a packageManager field set to npm, and a package-manager-cache option to turn that off. Being explicit with cache: npm avoids depending on that behavior.
How to confirm it works
- Push a commit. The first run should report that no cache was found for your key, and the post-job step saves one.
- Push a commit that doesn't touch
composer.lock. The cache step should report a hit on the exact key, and Composer should install from local files. - Change a dependency. You should see a restore through
restore-keys(not an exact hit), then a new cache saved under the new key.
The exact log wording belongs to the action and can change, so look at the cache step in the run log rather than searching for a fixed string.
Limits and gotchas
- Size and eviction. The action's README says a repository can hold up to 10 GB of caches, with older entries evicted by last access, and caches not accessed within a week are evicted as well. A small project may never notice; a busy monorepo might.
-
Caches don't update. The tips document in the
cacherepository states that a cache is immutable. If the key matches, nothing is saved again. That is why the lock file hash goes in the key. -
Branch scope. The README says caches are scoped to the key, version and branch, and the default branch's cache is available to other branches. A cache written on a feature branch is not visible to other feature branches, so runs on
mainare what warm the cache for everyone else. -
A missing lock file means a useless key.
hashFiles('composer.lock')is empty if the file doesn't exist, so the key never changes. Commit your lock files. -
Runner version. The README notes
actions/cachev5 and newer run on Node 24 and need Actions Runner 2.327.1 or newer. This only matters on self-hosted runners; GitHub-hosted runners are kept current.
Alternatives
-
Built-in cache in other setup actions.
setup-nodehas its own as shown above. For Composer, the explicitactions/cachestep is what thesetup-phpdocs show. -
Cache the PHP extensions too. The
setup-phpREADME has a section on caching extensions. It helps when you compile extensions from PECL, and does little if you only use ones bundled with the image. -
Skip work instead of caching it. Run the full suite in pull requests, but skip jobs that don't matter for a change with path filters in
on:.
Common mistakes
- Caching
vendorinstead of Composer's download directory. - Using a key without the lock file hash, so the cache is stale forever.
- Using a key that changes on every run (a timestamp or run number), so nothing is ever restored.
- Forgetting the PHP version in the key when the matrix runs several versions.
- Using
npm installin CI, which can change the lock file and produce different results from one run to another.
Related Dev Talk articles
- GitHub Actions for Laravel, Part 1: Run Tests with a PHP Matrix and MySQL
- GitHub Actions for Laravel, Part 3: Deploy over SSH with Releases and Rollback
Frequently asked questions
Should the cache step go before or after setup-php?
After. The cache path comes from composer config cache-files-dir, so Composer must already exist, and setup-php installs it.
What if I suspect a bad cache entry?
Change the key prefix (for example composer-v2-...). Entries are immutable, so a new prefix is the simplest way to start from an empty cache. You can also delete caches from the repository's Actions settings.
Does the deploy job in Part 3 reuse this cache?
It uses the same key format with PHP 8.4, so it should match the entry the PHP 8.4 test job saved, subject to the branch scope rules above. I did not observe this on GitHub, so check the cache step in your own deploy log.
Update log
- 12 November 2026: first version.
-
To recheck on each update: the current major versions of
actions/cacheandactions/setup-node, the cache size and eviction limits, and thesetup-nodeautomatic caching defaults.
Sources
- actions/cache README, examples and tips
- actions/setup-node README
- shivammathur/setup-php README: Cache Composer Dependencies
- actionlint
Originally published on DEV Talk.
Top comments (0)