Blt Laravel Package

Getting Started

• Install with composer require blumilksoftware/blt --dev (this is a development-quality toolchain, not a runtime dependency — keep it out of require so it never ships to production).
• v1.1.0 adds Laravel 13 support, so composer.json constraints now accept Laravel 12.x and 13.x. If you are still on Laravel 11, pin ^1.0 or upgrade the app first; do not assume the widened constraint back-ports to older majors.
• First place to look after install: the package's published config and its composer scripts/bin entries. Run the exposed binary (or the documented artisan command) against a single directory rather than the whole repo, e.g. vendor/bin/<tool> app/Models — you want a fast, scoped first run before wiring it into CI.
• First concrete use case: run it on one fresh feature branch and diff the output. Treat the first run as a baseline audit, not a gate — commit the resulting fixes separately from the CI wiring so the noise is attributable.
• If you use the shipped GitHub Actions workflows, read .github/workflows/* in the package before copying them into your repo: v1.1.0 hardened them with explicit minimum permissions: blocks and SHA-pinned actions, and those pins will need periodic refresh.

Implementation Patterns

• Composer script wiring. Expose the tool through composer.json scripts ("lint": "...", "lint:fix": "...") so local devs and CI invoke the identical entrypoint. This is the single highest-leverage integration: it makes the package part of the workflow rather than a thing people remember to run.
• Tiered pipelines. Run the cheap/fast checks on every push in a pre-commit hook (or composer lint on staged files), and the full sweep only in CI. Full-repo runs on every save destroy the feedback loop.
• CI matrix on framework version. Since v1.1.0 spans Laravel 12 and 13, test your own package/app matrix with both: laravel/framework: ^12.0 and ^13.0. A widened constraint from a dev dependency can surface transitive conflicts only on one side.
• Baseline-then-ratchet. If the tool reports violations, capture the current count in CI and fail only on regressions. This lets you adopt the package on a legacy codebase without a 400-file reformat PR.
• Scoped configurations per context. Keep a strict config for app/ and a laxer one for tests//database/migrations — migration and fixture code almost always needs exemptions.
• Container/DI-friendly invocation for tests. If you want to assert on the tool's output in your own test suite, wrap the binary call in a small service class and bind it, rather than shelling out from tests directly.
• Workflow reuse. If you adopt the shipped GitHub Actions, copy them into .github/workflows/ and immediately record the pinned SHAs in a comment or a renovate/dependabot config so the pins don't silently rot.

Gotchas and Tips

• --dev is not optional. Installing this in require will drag dev tooling into production images and can trip composer install --no-dev audit steps.
• Widened Laravel constraints are not a guarantee. ^13.0 support means the maintainers test it; it does not mean your app's other dev dependencies (PHPStan, Rector, PHP CS Fixer plugins) are compatible. Bump the framework first, then re-run the tool, and be prepared to bump the analyser versions too.
• SHA-pinned actions require maintenance. The v1.1.0 supply-chain hardening is genuinely good, but pinned SHAs never auto-update. Without dependabot/renovate, you'll be running a year-old checkout before you notice.
• Minimum permissions can break your workflow. If you copied a workflow from v1.0.0 and later merge the v1.1.0 version, permissions: contents: read at the top level will break any step that comments on a PR or pushes a commit. Add job-level permissions: overrides where needed rather than reverting to write-all.
• Debugging a false positive: run the tool on the single file in isolation. Nine times out of ten the issue is a config path glob that silently matches nothing, so the check "passes" vacuously — verify with a deliberately broken file that the check actually fails.
• Cache invalidation. Tool caches keyed on file hashes can go stale in CI when the cache is restored across branches. If results look impossible, clear the cache before chasing a real bug.
• Extension points over forks. Prefer the package's config file and custom ruleset registration to patching vendor code; a fork will need re-forking on every Laravel major, and there is now at least one such major per year.
• Pin the version in CI. composer require --dev with a floating constraint means a tool release can redden your pipeline unrelated to your own changes. Use a committed composer.lock and update deliberately.