Laravel Uninspire Laravel Package

Getting Started

jonpurvis/laravel-uninspire is a dev-only Artisan tool that strips the "inspirational" / LLM-flavoured comments out of your codebase — the // This beautiful function handles... and // Here's a clean implementation of... noise that piles up after AI-assisted coding sessions.

Minimum steps

1. Install as a dev dependency (never in production):

   composer require jonpurvis/laravel-uninspire --dev
   

2. Confirm your PHP version. v3.0.0 drops PHP 8.2 support — you need PHP 8.3+. If you're still on 8.2 in local/CI, pin ^2.0.1 instead:

   composer require jonpurvis/laravel-uninspire:^2.0.1 --dev
   

3. Publish the config so you can see what's scanned and how:

   php artisan vendor:publish --tag="uninspire-config"
   

4. Run it against a single directory first, and read the diff, not the terminal output:

   php artisan uninspire app/
   git diff
   

Where to look first

• config/uninspire.php — the paths/exclusions and the pattern list it matches against.
• src/Commands — the command signature and available flags (--dry-run/--path style options), which is the fastest way to know exactly what it will touch.
• The README's usage block — the package is small enough that the README is effectively the full manual.

First real use case: run it on a branch where you've just merged a big chunk of AI-generated code, before human review. Reviewing a diff full of removed fluff comments is far cheaper than reviewing code where the fluff is still embedded.

Implementation Patterns

Dry-run-then-apply loop. Always preview before writing. Diff the output or use the command's dry-run mode, confirm only comment lines are being removed, then run for real. This is the single most important habit with a tool that mutates source files.

Composer script for convenience. Add to composer.json so it's discoverable and consistent across the team:

"scripts": {
    "uninspire": "@php artisan uninspire",
    "uninspire:check": "@php artisan uninspire --dry-run"
}

Pre-commit hook. Wire it into captainhook, husky + lint-staged, or a plain .git/hooks/pre-commit so staged PHP files are cleaned as part of the commit. Keep it scoped to changed files (git diff --cached --name-only --diff-filter=ACM -- '*.php') so it stays fast on large repos.

Pair it with Pint, in this order. Uninspire removes lines → Pint normalises the leftover whitespace/blank-line runs. Running Pint first means uninspire's deletions can leave ragged formatting behind:

composer uninspire && ./vendor/bin/pint --dirty

Post-AI-session cleanup. The most natural workflow: after a Claude/Copilot session, run uninspire across the touched files, then git diff and skim. It turns "review 400 lines of narration" into "review 120 lines of actual code."

CI guard (optional). If you want to keep the codebase clean rather than just clean it up occasionally, run the check mode on PRs and fail when it reports pending changes. This only works if the team agrees on the convention — otherwise it becomes noise.

Scope it deliberately. Point it at app/, src/, tests/ explicitly rather than the repo root, and confirm vendor/, node_modules/, storage/, and any generated code (IDE helper stubs, compiled assets, *.blade.php caches) are excluded in config before the first full run.

Gotchas and Tips

PHP 8.2 is no longer supported in v3. This is the headline breaking change. Two places to check: your composer.json require-dev constraint, and every CI matrix entry (shivammathur/setup-php versions, Docker image tags, Forge/Vapor build images). A CI job silently on 8.2 will fail to resolve the dependency — the error surfaces at composer install, not at runtime, so it's loud but easy to misread as a network/lockfile issue. Staying on v2.0.1 is a perfectly reasonable short-term answer.

Comment removal is destructive and unstaged. Commit or stash before the first run on any real directory. There is no undo beyond git checkout. Do the first run on a throwaway branch.

It can't tell your comments from the machine's. A regex-driven tool will happily remove comments that carry meaning: license headers, @var/@param annotations, // @phpstan-ignore-next-line, // phpcs:disable, // TODO notes with ticket numbers, and explanatory comments a human genuinely wrote. Audit the config's ignore/allow list before trusting it broadly, and add patterns for anything your team relies on.

Run static analysis and tests immediately after. Removed inline @phpstan-ignore and @psalm-suppress comments can turn a green build red without any code changing. ./vendor/bin/phpstan analyse && php artisan test after the first big pass is cheap insurance.

It doesn't reformat. Expect stray double blank lines and orphaned whitespace where multi-line docblocks used to be. Pint (or php-cs-fixer) afterwards is not optional if you care about diffs staying readable.

Strings and heredocs are (correctly) untouched. Only real comment tokens are targeted, so a "comment" inside a string literal or a Blade template won't be stripped. If you expected a file to change and it didn't, check whether the text is actually a comment.

Debugging a no-op run: point the command at a single known-dirty file rather than a directory, and check the config's path list — the most common cause of "it did nothing" is that the path you passed isn't in the scanned set. Verbose output (-v) usually names the files it considered.

Extension points are thin by design. The published config is the lever: paths, exclusions, and the pattern list. There's no event/pipe system worth relying on — if you need bespoke behaviour, wrap the command in your own Artisan command rather than subclassing the package's.

Keep it out of production. It's a require-dev tool. If it ever appears in composer.json's require block or in a deploy pipeline, something has gone wrong — the last thing you want is a build step editing source on the way to a release.