Ci Detector Laravel Package

Getting Started

Start by installing the package via Composer: composer require ondram/ci-detector. Then instantiate OndraM\CiDetector\CiDetector and call detect() to get a typed object representing the current CI environment (e.g., GitHubActions, GitLabCi, CircleCi). Use the isCi() method to gate CI-specific logic, and inspect methods like getName(), getBuildNumber(), or getCommitHash() to access contextual metadata.

Example first use case: in a Laravel test bootstrap file (tests/Bootstrap.php), detect CI to enable parallelized test execution or suppress interactive prompts:

$ci = (new CiDetector())->detect();
if ($ci?->isCi()) {
    config()->set('database.default', 'ci_testing'); // custom DB config
}

Review the src/Ci/ directory in the repo (or generated PHPDoc) to see which CI providers are supported and which metadata fields are reliably exposed.

Implementation Patterns

• Conditional Test Behavior: Skip slow database migrations or external API calls in CI via $ci?->isCi() guards, especially useful in feature tests.
• Build Metadata Logging: Enrich error reporting (e.g., Sentry context) or log entries with CI info (build URL, job ID, branch) for traceability.
• Deployment Safeguards: Prevent destructive artisan commands (e.g., php artisan db:wipe) outside CI by checking $ci?->isCi() and the provider type.
• Artifacts & Cache Tuning: Adjust cache drivers (e.g., use Redis in CI, file system locally) or artifact paths based on CI provider (e.g., GitHub Actions vs. Bitbucket Pipelines).
• CLI Commands: Create dedicated commands like php artisan ci:status to output build context for troubleshooting CI failures.

Common integration points: AppServiceProvider::boot(), PHPUnit bootstrap files, custom deployment scripts, or job-level commands in CI config (e.g., .github/workflows/ci.yml).

Gotchas and Tips

• False Positives: Local environments sometimes mimic CI variables (e.g., CI=true set manually), leading to incorrect detection. Always validate via isCi() first, and consider provider-specific checks (e.g., $ci instanceof GitHubActions) for critical logic.
• Incomplete Metadata: Some providers expose only partial data (e.g., no build URL in Travis Pro). Use method_exists() or has*() checks before accessing optional properties like getBuildUrl() or getJobId().
• Extensibility: Add support for internal/self-hosted CI systems by implementing CiInterface and registering custom detectors via CiDetector::addDetector(new YourCustomCiDetector()).
• Performance: detect() is idempotent and fast—safe to call repeatedly—but avoid instantiating CiDetector in hot loops.
• Testing Strategy: Mock environment variables in tests using putenv()/$_ENV overrides. Never rely on real CI detection in unit tests; instead, assert against concrete detector classes (e.g., isInstanceOf(GitLabCi::class)).
• Fallback Safety: detect() may return null in edge cases (e.g., invalid env state); default to safe behavior (e.g., non-CI mode) when detection fails.