Version Laravel Package

Product Decisions This Supports

• Standardized Versioning for APIs/SDKs: Enables consistent SemVer 2.0.0 compliance across Laravel-based APIs, SDKs, or microservices, ensuring backward compatibility and clear deprecation policies for consumers.
• Automated CI/CD Versioning: Accelerates release pipelines by programmatically incrementing versions (e.g., incrementMajor()) in deployment scripts, reducing manual errors in Git tags or Docker labels.
• Dependency Validation: Integrates with Composer or custom workflows to validate version strings in composer.json or API requests, preventing incompatible deployments (e.g., rejecting 1.0.0-beta for production).
• Feature Flag & Canary Releases: Supports pre-release versions (1.2.3-alpha) and build metadata (+commit-hash) for gradual rollouts or rollback tracking in Laravel applications.
• Build vs. Buy Decision:
  • Buy for teams needing lightweight, compliant SemVer handling without reinventing parsing/comparison logic. Ideal for Laravel projects where versioning is a secondary concern but critical for compatibility.
  • Build only if requiring custom extensions (e.g., non-SemVer schemas like date-based versions) or active maintenance. Consider forking if PHP 8.x compatibility is needed.
• Roadmap Use Cases:
  • API Versioning: Dynamically compare client/server versions to enforce deprecation policies (e.g., reject requests with version < 2.0.0).
  • Plugin Ecosystems: Validate plugin compatibility by comparing version ranges (e.g., ^1.2.3) in Laravel’s service container or package managers.
  • Release Notes Automation: Extract version components (major/minor/patch) to auto-generate changelogs or Slack notifications (e.g., "Breaking: Major v2.0.0 released").
  • Database Migrations: Track schema versions with SemVer-compliant timestamps (e.g., schema_migrations table with version column).

When to Consider This Package

• Adopt if:
  • Your Laravel/PHP project requires strict SemVer compliance (e.g., public APIs, open-source packages, or SaaS platforms with versioned endpoints).
  • You need programmatic version manipulation (e.g., auto-incrementing versions in CI/CD scripts, parsing user-provided version strings).
  • Your team lacks dedicated versioning tooling but needs validation/comparison logic for dependencies or feature flags.
  • You’re working with pre-release builds (e.g., 1.0.0-beta.1) or build metadata (e.g., +git-sha) for canary releases or artifact tracking.
  • You prioritize lightweight dependencies and can tolerate an archived package (no active maintenance required for core SemVer functionality).
• Look Elsewhere if:
  • You need active maintenance or PHP 8.x+ compatibility (consider php-semver/php-semver or ramsey/uuid).
  • Your use case involves non-SemVer schemas (e.g., date-based versions like 2023.10.1 or custom formats like v1.2.3-rc1).
  • You require high-performance version comparisons (e.g., millions of comparisons/second; this library is lightweight but not optimized for scale).
  • Your stack is non-PHP (e.g., Node.js, Go, or Python; use native tools like npm version or setuptools).
  • You’re using Laravel’s built-in versioning (e.g., Artisan::version()) and only need simple version strings without SemVer features.

How to Pitch It (Stakeholders)

For Executives:

"This package standardizes version management in our Laravel products, reducing release errors and ensuring compatibility across APIs, plugins, and SDKs. By automating version increments (e.g., 1.2.3 → 2.0.0) and validation in CI/CD, we cut manual effort and enforce SemVer best practices—critical for scaling developer tools or SaaS platforms. The MIT license and zero dependents mean no vendor lock-in, while the archived status signals stability (last updated in 2014 with no breaking changes). For negligible cost, it’s a low-risk way to professionalize our release workflows and improve developer productivity."

For Engineering (Laravel Teams):

*"This library gives us a batteries-included SemVer toolkit for Laravel:

• Parse/Validate: Quickly check if 1.0.0-rc.1+build123 is valid or extract components (major/minor/patch) for changelogs.
• Compare: Enforce version constraints in APIs (e.g., Comparator::isGreaterThan($clientVersion, '1.2.0')) or feature flags.
• Build: Auto-increment versions in scripts (e.g., incrementPatch() in post-deploy hooks) or Laravel commands.
• Dump: Convert version objects to strings for logging or Git tags (Dumper::toString($version)). Tradeoffs:
• Pros: Lightweight, compliant with SemVer 2.0.0, and easy to integrate into Laravel’s service container.
• Cons: Archived (last release 2014), so we’d need to fork for PHP 8.x compatibility. Alternatives like php-semver/php-semver are more popular but heavier. Recommendation: Use this for Laravel-specific SemVer needs (e.g., plugin ecosystems, API versioning) and pair it with a modern fork or polyfills for PHP 8.x."*

For Developers:

*"If you’re tired of manually parsing version strings or guessing SemVer rules, this library handles it for you:

// Before: Manual parsing (error-prone)
$parts = explode('.', '1.2.3-alpha');
if ($parts[0] < 2) { /* ... */ }

// After: Library usage (safe and compliant)
$version = Parser::toVersion('1.2.3-alpha');
if (Comparator::isLessThan($version, '2.0.0')) { /* ... */ }

Key use cases in Laravel:

• Validate version strings in API requests or composer.json.
• Auto-generate versioned artifacts (e.g., app-v1.2.3.zip).
• Compare plugin versions in the service container. Gotchas:
• May need a fork for PHP 8.x (e.g., add #[ReturnTypeWillChange]).
• No Laravel-specific helpers (e.g., config('app.version') binding), so wrap it in a service class."*