Getting Started

Minimal Steps

Installation: Add Janus to your project via Composer:
```
composer require --dev 21torr/janus
```
Ensure your composer.json specifies either "type": "project" (Symfony/Laravel) or "type": "library" for non-framework projects.
First Run: Initialize Janus with the correct package type (auto-detected or manually specified):
```
vendor/bin/janus init
```
This generates config files for:
- PHPStan (phpstan.neon)
- PHP-CS-Fixer (.php-cs-fixer.dist.php)
- Doctrine schema validation
- Custom scripts in composer.json

Run Checks: Execute static analysis and style checks:

vendor/bin/janus check

Or run individual tools:

vendor/bin/phpstan analyse
vendor/bin/php-cs-fixer fix

CI Integration: Add to your GitHub Actions (.github/workflows/ci.yml):
```
- name: Run Janus
  run: vendor/bin/janus check
```

Where to Look First

Documentation for tool-specific configurations.
janus.php (auto-generated) for package-specific rules.
phpstan.neon for PHPStan exclusions/extensions (e.g., Doctrine, PHPUnit).
composer.json for merged scripts (e.g., janus:check).

First Use Case

Onboarding a New Developer: Run vendor/bin/janus check locally to catch style issues early. The -v flag in PHPStan shows error identifiers, helping developers resolve issues faster.

Implementation Patterns

Usage Patterns

Project Initialization:
- Use janus init during project setup or when migrating to a new Laravel/Symfony version.
- Override auto-detection with --type=library or --type=symfony if needed.
Daily Workflow:
- Pre-commit: Add to .git/hooks/pre-commit or use a tool like husky:
```
vendor/bin/janus check --no-fix
```
- Fix Issues: Run vendor/bin/janus fix to auto-correct style issues.
- Custom Rules: Extend janus.php to add project-specific exclusions (e.g., for legacy code):
```
return [
    'phpstan' => [
        'exclude' => ['app/OldLegacyCode/**'],
    ],
];
```
CI/CD Pipeline:
- GitHub Actions: Use the janus check command as a quality gate:
```
jobs:
  janus:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: vendor/bin/janus check
```
- Fail Fast: Configure Janus to exit with non-zero status on errors (default behavior).
Symfony/Laravel-Specific Workflows:
- Doctrine Schema Validation: Run in CI to catch DB migration issues early:
```
vendor/bin/janus doctrine:validate
```
- PHPStan with Tests: Use the pre-configured PHPUnit extension to ignore test-specific rules.

Custom Composer Scripts: Merge Janus scripts into your composer.json:

{
  "scripts": {
    "janus": "janus",
    "lint": "janus check --no-fix",
    "fix": "janus fix"
  }
}

Run with:

composer janus

Integration Tips

Laravel Mix/Webpack: Add Janus checks to your build process:
```
mix.scripts.push('vendor/bin/janus check --no-fix');
```
PHPStorm Integration:
- Use Janus’s phpstan.neon as your IDE’s PHPStan config (File > Settings > PHP > Quality Tools > PHPStan).
- Disable PHPStorm’s built-in inspections for attributes (Janus auto-handles these).
Monorepos: Run Janus per-package by setting the JANUS_PACKAGE_ROOT env var:
```
JANUS_PACKAGE_ROOT=packages/my-package vendor/bin/janus check
```

Parallelization: Split PHPStan analysis by directory for large projects:

vendor/bin/phpstan analyse app/ --memory=1G
vendor/bin/phpstan analyse tests/ --memory=2G

Gotchas and Tips

Pitfalls

Auto-Run Disabled by Default:

Janus does not auto-run on composer install (since v2.0.1). Enable with:

composer require --dev 21torr/janus --with-all-dependencies --no-scripts
vendor/bin/janus init --auto-run

Workaround: Add to composer.json:

"scripts": {
  "post-install-cmd": "janus init --auto-run"
}

Symfony 8+ Path Issues:
- If using Symfony 8+, ensure config/bundles.php exists (Janus v2.1.0+ fixes this).
- Debug: Run with --verbose to see resolved paths.
False Positives:
- Doctrine.columnType: Disabled by default (v2.0.0+) due to false positives with Symfony forms.
- PHPStan Tests: Rules like missingType.iterableValue are globally disabled (v1.3.3+).
- Customize: Override in phpstan.neon:
```
includes:
    - vendor/21torr/janus/phpstan.neon
rules:
    Doctrine\DBAL\Types\Type:
        doctrine.columnType: false
```
Composer Plugin Conflicts:
- If using other Composer plugins (e.g., humbug/box), ensure Janus runs last:
```
"scripts": {
  "post-install-cmd": [
    "@humbug/box",
    "janus init --auto-run"
  ]
}
```
PHPStan v2 Migration:
- Janus v1.5.0+ supports PHPStan v2, but some rules may behave differently.
- Tip: Run vendor/bin/phpstan analyse --debug to compare v1/v2 outputs.

Legacy Code:

Janus may flag deprecated Laravel/Symfony patterns (e.g., Route::controller()).

Solution: Use janus.php to exclude directories or suppress specific rules:

return [
    'phpstan' => [
        'exclude' => ['app/Http/Controllers/Old/**'],
        'rules' => [
            'Laravel\Rules\Deprecated' => false,
        ],
    ],
];

Debugging

Verbose Output: Use --verbose for detailed logs:
```
vendor/bin/janus check --verbose
```
Look for:
- Resolved config paths.
- Skipped files/directories.
- PHPStan error identifiers (e.g., missingReturnType).

Dry Runs: Test changes without modifying files:

vendor/bin/php-cs-fixer fix --dry-run
vendor/bin/phpstan analyse --no-progress

Isolated Testing: Run Janus on a single file/directory:
```
vendor/bin/janus check app/Models/User.php
```

CI Debugging: Cache Composer dependencies to avoid flaky CI runs:

- name: Cache Composer
  uses: actions/cache@v3
  with:
    path: vendor
    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}

Tips

Custom PHPStan Rules: Add project-specific rules to phpstan.neon:

includes:
    - vendor/21torr/janus/phpstan.neon
    - phpstan-rules.neon

Example phpstan-rules.neon:

rules:
    MyApp\Rules\CustomRule: true

PHP-CS-Fixer Customization: Extend the default config in .php-cs-fixer.dist.php:

$finder = PhpCsFixer\Finder::create()
    ->in(__DIR__)
    ->exclude('vendor')
    ->exclude('storage')
    ->name('*.php')
    ->notName('*.blade.php'); // Add Blade exclusions

Doctrine Schema Validation: Validate schema in CI even if no migrations exist:
```
vendor/bin/janus doctrine:validate --no-migrations
```
Performance:

Janus Laravel Package