Composer Template Diff Plugin Laravel Package

Getting Started

This package tracks and verifies the integrity of your vendor/ directory by comparing it against a stored set of hashes — useful as a lightweight supply-chain tripwire in CI or on shared/staging environments.

1. Install as a dev dependency (you almost never want this in production runtime):

   composer require --dev <vendor>/<package>
   

2. Look first at the service provider and the src/Console (or Commands) directory. In 1.1.0 the update command is the entry point you care about — it is what generates/refreshes the hash baseline. Confirm the exact signature with php artisan list after installing.
3. Publish the config if available. 1.1.0 added "basic config" support, so check for a publishable config file (php artisan vendor:publish) and read it before running anything — the defaults determine which paths are hashed and where the manifest lives.
4. First use case: run composer install from a clean, trusted lockfile, then run the new update command to snapshot the vendor tree, and commit the resulting hash file. That committed baseline is the artifact every later check compares against.

If you only do one thing with this package, do that: baseline once, commit it, verify on every CI run.

Implementation Patterns

Generate the baseline as a Composer hook. Wire the update command into post-install-cmd / post-update-cmd in composer.json so the manifest is refreshed whenever dependencies legitimately change, instead of relying on developers to remember:

"scripts": {
    "post-install-cmd": ["@php artisan vendor:update-hashes"],
    "post-update-cmd": ["@php artisan vendor:update-hashes"]
}

Treat the manifest diff in code review as the security-relevant change — a lockfile bump and a hash bump should appear together.

Verify in CI as a separate, fast job. Run the verification command (or the artisan command without the update flag) before your test suite. Failing early means you aren't paying for a full test run on a tampered or drifted vendor tree. This is far cheaper than composer audit alone because it catches local mutation, not just known CVEs.

Pair it with a clean-install CI step. The only trustworthy baseline is one generated from a composer install against a committed lockfile. In CI, always run composer install --no-dev or equivalent first, then verify — never verify against a cached or reused vendor directory.

Use config for exclusions. The 1.1.0 config support is the right place to exclude packages that legitimately rewrite files at install time (post-install scripts, generated stubs, compiled assets). Exclude narrowly and document why each exclusion exists.

Local pre-push guard. For repos where developers share a vendor cache, a pre-push hook running the verify command catches accidental edits before they reach CI — and gives a clearer error than a red pipeline.

Gotchas and Tips

• Never "fix" a failing check by running the update command. The whole value of this package is that refreshing the baseline is a deliberate, reviewable act. Make that a stated team rule; an auto-updating hook in a verification context silently defeats the tool.
• Platform-dependent files cause false positives. Composer generates some files that differ by PHP version or OS. If you see drift on one machine only, that's an exclusion, not a corruption — but confirm before excluding.
• Ordering matters. Running the update command before composer install finishes (or inside a post-autoload-dump hook that fires mid-install) can snapshot a half-written vendor/ tree. Prefer post-install-cmd / post-update-cmd, which run after the tree is complete.
• Config caching. If you deploy with php artisan config:cache, remember the config is frozen at cache time; config changes require a re-cache. In CI this is usually irrelevant since you're running fresh, but it bites people debugging locally.
• Large vendor directories cost real time. Hashing every file is I/O-heavy. If the verify step is slow, use the config to scope it to the directories you actually care about rather than hashing the entire tree.
• Extension points to check: the config file (paths, manifest location, algorithm), the command signatures (whether update and verify are separate commands or one with a flag), and whether the package exposes an event or facade you can hook into for custom reporting. The service provider is the fastest way to answer all three.
• Version pin it in CI. Because the integrity check is itself part of your trust boundary, pin a specific version in composer.lock and review upgrades of this package with the same scrutiny as any other security tooling.