Product Decisions This Supports
- Git Integration for PHP Applications: Enables programmatic Git operations (commits, branches, merges, diffs, tags) from inside PHP services, removing the need for shelling out to
git or depending on a hosting provider's REST API.
- Roadmap for DevOps/Automation Tooling: Accelerates internal tooling — CI/CD helpers, commit-policy enforcement, changelog generation, code-review automation — without building a bespoke Git abstraction layer.
- Build vs. Buy: Buying (adopting) remains the right call over building a Git wrapper in-house, but v5.0.0 adds a platform-modernization prerequisite: it now requires PHP >= 8.1 and Symfony ^6.4 || ^7.0 || ^8.0. Treat the upgrade as a joint decision with your PHP/Symfony upgrade roadmap, not an isolated dependency bump.
- Platform Baseline Decision (new): v5.0.0 is effectively a "modern stack" signal. If your roadmap already targets PHP 8.1+ and Symfony 6.4+, adopting v5 keeps you on a supported, tooling-current branch (PHPStan 2, Rector 2, PHPUnit 10/11, PSR-4). If you are still on PHP 7.4/8.0 or Symfony <6.4, you are choosing to pin v4.6.0 and accept an unmaintained branch — a deliberate support-risk decision to surface to stakeholders.
- Use Cases:
- Automated Code Review: Inspect commits and diffs to enforce conventions or auto-generate changelogs.
- Git Workflow Enforcement: Validate branch naming, commit messages, or merge strategy in code rather than in brittle shell hooks.
- Legacy System Modernization: Embed Git operations into existing PHP monoliths without exposing teams to CLI complexity — but note this now implies the monolith is on PHP 8.1+.
- Custom Git Hooks: Replace shell-based hooks with PHP logic tied to business rules (e.g. dynamic commit-message validation).
When to Consider This Package
- Adopt if:
- Your PHP application needs programmatic Git control (reacting to commits, branches, merges) inside the app rather than via CI shell steps.
- You are building internal developer tooling where Git is a first-class dependency.
- Your team prefers PHP-native abstractions over
git CLI calls, libgit2 bindings, or GitHub/GitLab REST APIs.
- Your platform meets the v5.0.0 baseline: PHP >= 8.1 and Symfony ^6.4 || ^7.0 || ^8.0. This is the key new gate — confirm it early, because it drives whether you can take v5 at all.
- Look Elsewhere if:
- You are on non-PHP stacks (Node.js, Python, Go) where native Git libraries or CLI wrappers are the norm.
- Your needs are simple, occasional Git interactions (
pull/push) already covered by CLI or HTTP APIs.
- You need hosting-provider integrations (PRs, reviews, webhooks, permissions) — GitHub/GitLab SDKs are a better fit.
- Your project has licensing constraints incompatible with LGPL-3.0 (e.g. proprietary distribution requiring different terms).
- You cannot move to PHP 8.1+ / Symfony 6.4+ in the near term. Staying on v4.6.0 is possible but leaves you on an abandoned branch with no security or tooling updates — plan an exit or an upgrade date rather than drifting.
- Migration considerations for existing v4.x adopters (new):
- PSR-0 → PSR-4 autoloading: audit anything that referenced legacy class paths or extended the package's autoloading assumptions; this is the most likely source of hard breaks in custom integrations.
- Annotations → PHP 8 attributes: if you subclass or reflect over package classes expecting docblock annotations, update your readers (or migrate to attributes).
- PHPUnit 10/11 config schema: your own test suite's XML config and any inherited test bootstrap need updating to run against v5.
- Transitive constraint widening (Symfony ^8.0, PHPStan 2, Rector 2): expect to align your dev-tooling versions; budget a short spike rather than assuming a drop-in upgrade.
How to Pitch It (Stakeholders)
For Executives:
"GitElephant lets us automate Git workflows in plain PHP — 'GitHub Actions, but self-hosted and inside our own codebase.' It cuts dependence on external APIs and shell scripts for internal tooling like commit-policy enforcement, changelog generation, and release automation. The new v5.0.0 release is a maintenance and modernization release: no new product features, but it drops end-of-life PHP 7.x/8.0 and Symfony <6.4 support and moves the project onto current tooling (PSR-4 autoloading, PHPUnit 10/11, PHPStan 2). Read it as a platform alignment release: it keeps the package healthy and supported, and the only cost is that adopting it ties us to the same PHP 8.1+/Symfony 6.4+ baseline we are already moving toward. Low risk, LGPL-3.0, high leverage for developer productivity — the one decision to make is timing it with our PHP upgrade rather than before it."
For Engineering:
"v5.0.0 is a breaking, tooling-only release — no new Git features. Concretely: minimum PHP is now >=8.1, Symfony support is ^6.4 || ^7.0 || ^8.0, PHPUnit is ^10.5 || ^11.0 with a migrated config schema, autoloading moved from PSR-0 to PSR-4, and annotations were converted to PHP 8 attributes; Rector 2, PHPStan 2, and EasyCodingStandard 12/13 were picked up along the way. The public API surface (commit(), merge(), getBranches(), etc.) is unchanged, so the risk is concentrated in autoloading assumptions, any annotation reflection in our code, and our own PHPUnit config. Recommended path: pin to v4.6.0 only as a short-term stopgap, then upgrade PHP/Symfony and take v5 in one move; validate with a small spike against a real repo before committing. Tradeoff remains unchanged — raw Git control in PHP, no GUI or hosting-provider features."