Skip to content

Configuration

Jump to bottom
Ahmed Anbar edited this page Apr 25, 2026 · 1 revision

Configuration

DevGuard's defaults reflect production-Laravel best practices. When they don't match your project, configure them in config/devguard.php.

This page covers everything you can tune: enabling/disabling tools, per-rule impact values, custom paths for service/repository layers, output preferences, and where the config file is loaded from.

Where the config lives

DevGuard ships its defaults at config/devguard.php in its own package. To override, create a config/devguard.php file in your project root with the keys you want to change.

your-laravel-project/
├── app/
├── config/
│   └── devguard.php   ← your overrides here
└── ...

Your file is merged with DevGuard's defaults — you only need to specify the keys you're changing. Missing keys use defaults.

<?php

// config/devguard.php (in your Laravel project root)
return [
    'tools' => [
        'architecture' => [
            'rules' => [
                'fat_controller' => ['max_lines' => 400],   // raise from 300
            ],
        ],
    ],
];

Full default config

Here's everything DevGuard ships with — copy what you want to override into your project's config/devguard.php:

<?php

return [
    'tools' => [
        'deploy' => [
            'enabled' => true,
            'fail_on' => 'fail',          // or 'warning' to fail on warnings too
            'checks' => [
                'env_file_exists'    => ['impact' => 20],
                'debug_mode'         => ['impact' => 15],
                'cache_configured'   => ['impact' => 10],
                'queue_configured'   => ['impact' => 10],
                'rate_limit'         => ['impact' => 10],
                'https_enforced'     => ['impact' => 10],
                'logging_configured' => ['impact' => 5],
            ],
        ],
        'architecture' => [
            'enabled' => true,
            'rules' => [
                'fat_controller'    => ['max_lines' => 300],
                'service_layer'     => ['path' => 'app/Services'],
                'repository_layer'  => ['path' => 'app/Repositories'],
            ],
        ],
    ],
    'output' => [
        'colors' => true,
        'icons'  => true,
    ],
];

The env and deps tools currently have no per-rule configuration — they use sensible defaults for everything. Their tools-level enabled flag still works.

Per-tool toggles

Disable a whole tool:

return [
    'tools' => [
        'architecture' => ['enabled' => false],
    ],
];

When a tool is disabled, devguard run all skips it entirely — no runtime cost, no findings, no score impact. Useful when the tool is firing on patterns you've decided to accept (e.g., a project using a non-standard architecture deliberately).

For finer control (silencing one rule, not the whole tool), use the baseline file — that's the recommended path for individual exceptions.

Tuning impact values

Each deploy check has an impact value (0–100). Adjusting them re-weights the readiness score.

Reducing a check's importance

return [
    'tools' => [
        'deploy' => [
            'checks' => [
                'rate_limit' => ['impact' => 5],   // was 10, now 5
            ],
        ],
    ],
];

Common reasons:

  • The check fires on something your project structurally can't fix (e.g., a legacy auth flow that bypasses Laravel's standard rate-limiter).
  • You want the report message but a smaller score deduction so the overall number reflects your priorities.

Silencing a check (impact = 0)

'rate_limit' => ['impact' => 0],

The check still runs (you still see the message in the report), but the score isn't deducted. This is the cleanest way to keep visibility without penalty.

Making a check more important

'debug_mode' => ['impact' => 30],   // was 15, now 30 — fail this and you can't get above 70

Useful when you want to push a specific concern up the priority list — for instance, raising debug_mode impact in a security-sensitive project.

Caps and floors

  • Score is max(0, 100 - sum_of_deductions) — you can't go negative.
  • There's no hard cap on individual impact values, but values >100 don't make sense (a single failure couldn't drop the score below 0 anyway).

Architecture rule customization

Adjusting the fat_controller threshold

'architecture' => [
    'rules' => [
        'fat_controller' => ['max_lines' => 500],
    ],
],

The default 300 is opinionated — many production codebases have controllers in the 400–500 range that are arguably fine. Raise the limit if you've already done a fat-controller refactor pass and just want to prevent regression.

Custom service/repository paths

If your project doesn't follow Laravel's default app/Services/ and app/Repositories/ layout (e.g., DDD-style with app/Domain/<Aggregate>/Services/), tell DevGuard where to look:

'architecture' => [
    'rules' => [
        'service_layer'    => ['path' => 'app/Domain/Services'],
        'repository_layer' => ['path' => 'app/Domain/Repositories'],
    ],
],

Or disable these checks entirely if your project doesn't use the pattern:

'architecture' => [
    'rules' => [
        'service_layer'    => ['enabled' => false],
        'repository_layer' => ['enabled' => false],
    ],
],

fail_on behavior

Each tool can set when it considers itself "failed":

'deploy' => [
    'fail_on' => 'fail',     // default — only fail-severity findings cause the tool to fail
    // 'fail_on' => 'warning',   // any warning causes the tool to fail (strict mode)
],

fail_on: 'warning' is a strict mode — it makes warnings effectively fail. Useful when you want zero compromises but probably overly aggressive for most teams.

The Action also exposes a top-level fail-on-warning input that affects the whole run regardless of per-tool config; see GitHub Actions.

Output preferences

'output' => [
    'colors' => true,
    'icons'  => true,
],
Key Effect when false
colors Disables ANSI color codes (every output is plain)
icons Replaces ✓ ⚠ ✗ with [OK], [WARN], [FAIL] text

These also respect runtime flags — --no-ansi and --ansi override colors. For some terminals (looking at you, Windows cmd.exe), turning icons off makes the output far more readable.

Environment variable overrides

A few config knobs respect environment variables for CI convenience:

Env var Effect
CI=true Disables HTML auto-open (set automatically by GitHub Actions, GitLab CI, CircleCI, Jenkins, etc.)
NO_COLOR=1 Standard env var (no-color.org) — disables ANSI colors regardless of config
FORCE_COLOR=1 Standard env var — forces ANSI colors even when piped

You don't usually set these directly; they come from your CI environment.

Multi-project / monorepo configurations

For a monorepo with several Laravel projects, DevGuard reads config/devguard.php relative to the --path argument, not your shell's cwd:

devguard run all --path=apps/api      # reads apps/api/config/devguard.php
devguard run all --path=apps/admin    # reads apps/admin/config/devguard.php

This lets each sub-project set its own thresholds. To share config across them, use a PHP require from a shared file:

// apps/api/config/devguard.php
return require __DIR__ . '/../../../shared/devguard-config.php';

What you can't override via config

A few behaviors are intentionally not configurable, because making them config keys creates more confusion than they solve:

  • Which env-family files exist — DevGuard auto-discovers .env* files; you can't add .env.weird-staging to the union manually. (If you have an actual need for this, it's worth a feature request.)
  • Rule names — used as IDs in baseline files and SARIF; renaming would break every existing baseline.
  • Severity per finding — a rule's RuleResult::fail() vs ::warn() is decided in the rule's PHP code, not config. To downgrade, use the baseline.

For these cases, baseline and extending DevGuard are the escape hatches.

Worked example: a "permissive" config

For a legacy project that hasn't done a refactor pass, you might want a more lenient config:

<?php

return [
    'tools' => [
        'deploy' => [
            'checks' => [
                'rate_limit'         => ['impact' => 0],   // we know, will fix later
                'logging_configured' => ['impact' => 0],   // will set when we have time
            ],
        ],
        'architecture' => [
            'rules' => [
                'fat_controller'   => ['max_lines' => 500],
                'service_layer'    => ['enabled' => false],   // not using that pattern
                'repository_layer' => ['enabled' => false],
            ],
        ],
    ],
];

Combined with a baseline (devguard baseline), this makes adopting DevGuard on a legacy codebase a 1-day exercise instead of a 1-month one. Fix the new issues; keep the rest in baseline; tighten the config over time.

Worked example: a "strict" config

For a green-field project that wants the bar set high:

<?php

return [
    'tools' => [
        'deploy' => [
            'fail_on' => 'warning',           // any warning fails the build
            'checks' => [
                'debug_mode'   => ['impact' => 30],
                'env_file_exists' => ['impact' => 30],   // foundational
            ],
        ],
        'architecture' => [
            'rules' => [
                'fat_controller' => ['max_lines' => 200],   // tighter than default
            ],
        ],
    ],
];

Where to next

DevGuard for Laravel · MIT licensed · Maintained by Ahmed Anbar

Source · Action · Packagist · Issues · Wiki source

🛡️ DevGuard

Getting Started

Reference

Workflows

Advanced

Help

Links

Clone this wiki locally