Package Versions Laravel Package

Product Decisions This Supports

• Dependency Versioning for Dynamic Asset Generation Enable runtime access to installed package versions (e.g., for versioned API endpoints, changelog generation, or compliance metadata) without runtime composer show calls or filesystem reads. Critical for:

  • Self-documenting systems (e.g., /version endpoints for APIs).
  • Build pipelines (e.g., embedding dependency versions in compiled assets like JS/CSS manifests).
  • Security/compliance tools (e.g., auditing known-vulnerable versions at deploy time).

• Build vs. Buy: Avoid Custom Solutions Replaces ad-hoc scripts parsing composer.lock or shelling out to composer show. Reduces technical debt by leveraging a battle-tested, zero-I/O library.

• Roadmap: Scalable Dependency Tracking Foundation for future features like:

  • Version-based feature flags (e.g., "Enable X if laravel/framework ≥ 10.0").
  • Automated changelog generation (e.g., "This release updates monolog/monolog to v3.0").
  • CI/CD gating (e.g., block deploys if a dependency has unpatched CVEs).

• Use Cases in Laravel Ecosystem

  • Laravel Packages: Dynamically expose package versions in /vendor metadata.
  • SaaS Platforms: Embed dependency versions in support tickets or audit logs.
  • CLI Tools: Add --show-versions flags to commands (e.g., php artisan vendor:versions).

When to Consider This Package

• Adopt When:

  • You need zero-I/O access to dependency versions during runtime (e.g., in web requests, CLI tools, or build steps).
  • Your system generates artifacts (code, docs, or assets) that must reflect installed package versions (e.g., frontend bundles with versioned filenames).
  • You’re using Composer and want to avoid parsing composer.lock manually or shelling out to composer show.
  • Your team prioritizes performance (avoids filesystem reads during critical paths).

• Look Elsewhere If:

  • You’re not using Composer (e.g., npm, Go modules, or custom dependency management).
  • You need real-time version updates (this package reads composer.lock at install time; use composer show for live updates).
  • Your use case requires version ranges or constraints (this returns exact versions; use Composer\Semver for comparisons).
  • You’re on HHVM (package explicitly unsupported).
  • You need enterprise support (MIT license; consider Tidelift for commercial use).

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us automatically embed dependency versions into our system—without slowing down performance. For example:

• APIs: Expose /version endpoints to show all installed package versions (critical for support and debugging).
• Builds: Generate versioned assets (e.g., app-v1.2.3.css) during deployment, reducing cache conflicts.
• Compliance: Audit dependency versions at runtime for security scans or audits.

It’s free, MIT-licensed, and used by thousands of projects. We avoid reinventing the wheel while gaining reliability and speed."*

For Engineering:

*"Problem: Accessing dependency versions at runtime (e.g., for logs, APIs, or builds) is slow if we parse composer.lock or shell out to composer show. This package solves it by:

• Pre-compiling versions during composer install (zero I/O at runtime).
• Supporting Laravel/Composer natively (works with optimize-autoloader).
• Being lightweight (3KB, no external dependencies).

Use Cases:

1. Dynamic Version Endpoints: Return ocramius/package-versions:2.12.0 in /version without filesystem reads.
2. Build Optimization: Embed versions in compiled assets (e.g., mix-manifest.json).
3. CI/CD Checks: Fail builds if a dependency has known vulnerabilities (via getVersion() + CVE API).

Trade-offs:

• Versions are static (reflect composer.lock at install time).
• Not for real-time updates (use composer show for live queries).

Implementation:

composer require ocramius/package-versions

Add to composer.json:

"config": { "optimize-autoloader": true }

Then use:

$version = \PackageVersions\Versions::getVersion('laravel/framework');
// Returns '10.42.0' (or hash if needed).

Alternatives: Custom composer.lock parsing (slower) or shelling out (less secure). This is the de facto standard for this use case."*