Code Review Guardian Laravel Package

Getting Started

Reality check first. nowo-tech/code-review-guardian is flagged abandoned (last release 2026-10-20, zero stars, zero dependents). Treat it as source code you adopt, not a dependency you install. Before wiring it into CI, budget an hour to read src/ and decide whether you are forking it into your own repo or pinning it with a hardened lockfile. Everything below assumes you've made that call.

Install (pinned, never floating):

composer require --dev nowo-tech/code-review-guardian:1.x.x

Pin the exact version — ^1.0 will happily resolve to a release nobody maintains. Better still, vendor it as a path repository from your own fork so you control patches.

Where to look first, in this order:

1. composer.json — confirm the PHP/Symfony constraint actually matches your app (bundle rules target PHP >=8.1, Symfony 6/7/8). If you're on Symfony 5 or PHP 8.0, stop here.
2. src/DependencyInjection/Configuration.php — this file is the documentation. It tells you every config key, its default, and whether a value is required. Read it before reading the README.
3. src/DependencyInjection/ extension + any compiler passes — shows what's tagged, which interfaces are autoconfigured, and what public extension points exist.
4. src/Command/ — the console surface. Then run:

bin/console list | grep -i guardian          # discover the real namespace
bin/console config:dump-reference <alias>    # alias from Configuration.php
bin/console debug:container --tag=<tag>      # if the bundle tags providers

First use case: review one branch locally, no CI, no host API. The whole value proposition is "provider-agnostic," so prove that on day one by pointing it at a local git range rather than a GitHub PR. Get a review report on stdout, read it, and only then start thinking about tokens and webhooks. If the bundle can't do a purely local diff review, that's a strong signal to abandon the evaluation.

Register the bundle if Flex doesn't (it won't — this package is not in the Flex recipe index):

// config/bundles.php
Nowo\CodeReviewGuardian\CodeReviewGuardianBundle::class => ['all' => true],

Sanity gate before adoption: does a single local run produce useful output on a real diff from your codebase? Run it against a recent merge commit that you know contained a subtle bug. If it doesn't flag anything you'd have cared about, no amount of CI wiring will save the investment.

Implementation Patterns

Report-only, then gate. The only sane adoption path for any automated review tool, and doubly so for an unmaintained one:

• Phase 1 — run it manually / on a cron, output to a file, nobody's PR is blocked.
• Phase 2 — post findings as a PR comment (advisory, non-blocking).
• Phase 3 — fail the build on a narrow, explicitly allowlisted rule class.

Never skip to phase 3. Exit codes and severity thresholds are the first thing to break when a review engine changes behavior, and with no upstream maintainer, "changed behavior" means your own edits.

Keep the git host and the review engine behind their own config. The provider-agnostic claim is the package's main asset. Structure your config so host selection and review-engine selection are independent and both overridable per environment:

# config/packages/code_review_guardian.yaml
code_review_guardian:
    # keys per src/DependencyInjection/Configuration.php — verify names
    provider: '%env(CRG_PROVIDER)%'
    token: '%env(CRG_TOKEN)%'
    # path/glob excludes so generated code and vendor never hit the engine
    exclude:
        - 'vendor/**'
        - 'var/**'
        - 'src/Resources/public/build/**'

Drive provider and token from env so a developer can run the same command locally against their own token while CI uses a bot account.

Wrap the invocation, don't scatter it. One Make target or composer script that every developer and every CI job calls:

review:
	bin/console <guardian-command> --base=origin/main --format=text

When you inevitably fork the bundle, this single call site is the only thing that has to keep working.

Custom rules as tagged services. If Configuration.php or the compiler pass reveals a rule/checker interface with autoconfiguration, implement it in src/Review/ of your app rather than patching the vendor tree:

final readonly class NoDebugStatements implements SomeRuleInterface
{
    public function check(Diff $diff): iterable { /* ... */ }
}

Autoconfigured tag = zero wiring. Confirm the interface exists before designing around it; if it doesn't, that's a fork-level feature, not an app-level one.

Monorepo: filter before you review. Unfiltered diffs are the #1 cause of both rate-limit exhaustion and noise. Restrict by path glob and, where supported, by changed-file count — a 400-file refactor should short-circuit to "skipped, too large" rather than burn an API budget.

CI sketch (host-agnostic): run on pull_request / merge_request events only, with concurrency groups to cancel superseded runs, a hard timeout-minutes, and continue-on-error: true during phases 1–2. Cache nothing sensitive.

Fork hygiene (do this early). If you fork: add the upstream remote, keep the MIT license and attribution, write a CHANGELOG entry for every local patch, and — per the repo's own conventions — keep changes small, final classes, strict types, constructor injection, English PHPDoc. That repo discipline is what makes rebasing onto a hypothetical future upstream release survivable.

Gotchas and Tips

• Abandonment is the dominant risk. No security patches, no Symfony 8.x support guarantees beyond what shipped, no fixes for host API changes. GitHub/GitLab API deprecations will silently break provider implementations. Pin, fork, and set a calendar reminder to re-evaluate in six months.
• "Provider-agnostic" ≠ "zero-config." Expect to create a dedicated bot account with the narrowest token scopes that still allow reading diffs and posting comments. Read-only tokens that can't comment are a common half-configured state — the bundle will run fine and post nothing.
• Nondeterministic output. If the review engine is LLM-backed, identical diffs produce different findings. Never assert on exact output in your own tests; assert on the command's exit code and the shape (count/severity) of findings.
• Non-zero exit codes bite CI. A "found issues" exit code and a "crashed" exit code often share the same non-zero value. Wrap the call and inspect stderr before letting it gate anything.
• Token leakage via -vvv. Verbose output in CI logs is the classic way to print an Authorization header. Mask the env var at the CI level, not just at the console level.
• Config cache confusion. After changing the YAML, bin/console cache:clear — Symfony caches the compiled container and the dump-reference shows stale keys otherwise.
• Debugging checklist, in order: config:dump-reference <alias> → debug:container for the provider service → -vvv on the command → a diff of one file with one obvious issue. If step 4 doesn't produce the expected finding, the problem is upstream of your config.
• Large diffs get truncated, not rejected. Silent truncation gives you a green build on a PR the tool never actually read. Prefer failing loudly on oversized diffs.
• Preserve extension points if you fork. Public service IDs, config keys, and tagged interfaces are your only upgrade path. Renaming them for cleanliness is how forks become unmaintainable — this applies equally when your own team reviews the fork.
• Pair with something maintained. Run PHPStan/Psalm and PHP-CS-Fixer alongside this. Those cover the deterministic 80% and are actively maintained; the guardian is the advisory 20%. If the guardian ever dies entirely, your quality gate shouldn't die with it.
• Nearest-test rule when patching the fork. One focused test per behavior change, in the existing style, in the nearest tests/ directory — not a new testing framework alongside whatever ships.