Ocular Laravel Package

Getting Started

Download the ocular.phar file from https://scrutinizer-ci.com/ocular.phar (recommended for stability and simplicity), or install via composer require --dev scrutinizer/ocular. Your first step is to generate a coverage report—e.g., run PHPUnit with --coverage-clover=coverage.xml in your CI or local environment—then upload it with ocular.phar phar:upload coverage.xml. Ensure the SCRUTINIZER_TOKEN environment variable is set (via CI secrets or local .env) with a valid token from your Scrutinizer CI project; without it, uploads fail with a clear 401 error.

Implementation Patterns

• CI Pipeline Orchestration: In .github/workflows/ci.yml or GitLab CI, add a post-test step: curl -sS https://scrutinizer-ci.com/ocular.phar -o ocular.phar && php ocular.phar phar:upload build/logs/clover.xml. This keeps tooling self-contained and avoids installing extra dependencies.
• Cross-Tool Coverage Aggregation: Use external tools (e.g., nyc report --reporter clover for JavaScript, or gcovr --cobertura for C++) to produce Clover/CSV format, then pipe directly to ocular. Ideal for Laravel monorepos where backend (PHP) and frontend (JS/TS) coverage must appear in Scrutinizer’s unified dashboard.
• Dry-Run Validation: Before committing, test upload readiness with php ocular.phar phar:upload coverage.xml --dry-run -v—this verifies authentication, repository metadata, and file validity without consuming API quota.
• Pipeline Skew Prevention: For projects using multiple PHP versions or CI runners (e.g., Ubuntu vs Windows), pin a known PHAR version (curl -L -o ocular.phar https://scrutinizer-ci.com/ocular.phar?version=1.8.1) to eliminate runtime variability.

Gotchas and Tips

• Shallow Clone Pitfalls: CI jobs using fetch-depth: 1 (e.g., GitHub Actions) may fail with cryptic Git errors. Upgrade to ocular ≥1.8.1 (or use the latest PHAR) for graceful fallback—older versions lack clear diagnostics.
• Windows Quirks: Versions before 1.3.2 misparse Windows-style paths (e.g., C:\path\to\file.xml). Avoid by using the PHAR (bundled with paths normalized) or upgrading if using Composer.
• Token gotchas: SCRUTINIZER_TOKEN must be project-specific (found in Scrutinizer’s “Settings > CI/CD > API Token”). A global account token fails silently; always validate with --dry-run.
• Dependency Conflicts: If installing via Composer, jms/serializer:^3.0 may clash with Laravel’s symfony/serializer (used in ORM/OXM). Prefer PHAR over Composer unless you lock all versions (composer require --lock).
• Debugging Upload Failures: Add -vvv for full Guzzle debug output—this reveals HTTP status codes (e.g., 422 = malformed report, 404 = invalid repo/branch). Inspect coverage.xml’s <directory> attributes; Scrutinizer expects absolute paths (use --coverage-clover=coverage.xml --force in PHPUnit to ensure path normalization).
• Maintenance Note: With no releases since 2022 and zero dependents, assume this is feature-frozen. For new projects, verify Scrutinizer’s current docs still reference ocular—many teams now prefer Codecov’s codecov CLI for broader support and active development.