Jean85 Pretty Package Versions

https://github.com/jean85/pretty-package-versions
Admin
Jean85 Pretty Package Versions is a small, independent PHP wrapper library designed to obtain...
Tokens:19,115
Snippets:296
Trust Score:9.6
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example usage of getRootPackageName

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Demonstrates retrieving the name of the root project.

```php
use Jean85\PrettyVersions;

$rootName = PrettyVersions::getRootPackageName();
// For this package itself: 'jean85/pretty-package-versions'
```

--------------------------------

### Example usage of getRootPackageVersion

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Demonstrates retrieving the version object for the root project.

```php
use Jean85\PrettyVersions;

$rootVersion = PrettyVersions::getRootPackageVersion();
echo $rootVersion->getPackageName();      // 'jean85/pretty-package-versions'
echo $rootVersion->getPrettyVersion();    // e.g., '2.1.0'
```

--------------------------------

### Version Usage Pattern

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Examples of instantiating the Version object and retrieving formatted strings.

```php
use Jean85\Version;

$version = new Version('symfony/console', '6.0.0', 'abc123def456789');

echo $version->getPrettyVersion();              // '6.0.0'
echo $version->getVersionWithShortReference();  // '6.0.0@abc123d'

$devVersion = new Version('package', 'dev-main', 'abc123def456789');
echo $devVersion->getPrettyVersion();           // 'dev-main@abc123d'
```

--------------------------------

### Install Pretty Package Versions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/README.md

Use Composer to add the library to your project dependencies.

```bash
composer require jean85/pretty-package-versions:^2.0
```

--------------------------------

### Instantiating the Version Class

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/configuration.md

Examples of creating a Version object with varying levels of parameter detail.

```php
use Jean85\Version;

// Standard usage with all parameters
$version = new Version(
    'phpunit/phpunit',
    '9.5.28',
    'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b'
);

// With minimal parameters
$version = new Version('my/package');

// With version but no reference
$version = new Version('my/package', '1.0.0');
```

--------------------------------

### Example usage of getVersion

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Demonstrates how to retrieve and display version information while handling potential exceptions for provided, replaced, or missing packages.

```php
use Jean85\PrettyVersions;

try {
    $version = PrettyVersions::getVersion('phpunit/phpunit');
    echo $version->getPrettyVersion();  // Output: '9.5.28'
    echo $version->getVersionWithShortReference(); // Output: '9.5.28@a8c47fe'
} catch (\Jean85\Exception\ProvidedPackageException $e) {
    echo 'Package is provided by another package';
} catch (\Jean85\Exception\ReplacedPackageException $e) {
    echo 'Package has been replaced';
} catch (\OutOfBoundsException $e) {
    echo 'Package not installed';
}
```

--------------------------------

### Install via composer.json

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/README.md

Add the package dependency to your project's composer.json file.

```json
{
    "require": {
        "jean85/pretty-package-versions": "^1.5 || ^2.0"
    }
}
```

--------------------------------

### Jean85\PrettyVersions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Static facade for retrieving version information for installed packages.

```APIDOC
## Jean85\PrettyVersions

### Methods
- `getVersion(string $packageName): Version` - Retrieves version information for a specific package.
- `getRootPackageName(): string` - Returns the name of the root package.
- `getRootPackageVersion(): Version` - Returns the version information for the root package.
```

--------------------------------

### Configure composer.json for Library Behavior

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/configuration.md

Example composer.json structure demonstrating how provide and name settings affect library exceptions and return values.

```json
{
    "name": "my/project",
    "version": "1.0.0",
    "require": {
        "jean85/pretty-package-versions": "^2.0"
    },
    "provide": {
        "psr/log-implementation": "1.0.0"
    }
}
```

--------------------------------

### Catching OutOfBoundsException

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/exceptions.md

Demonstrates handling the standard PHP OutOfBoundsException when a requested package is not installed.

```php
use Jean85\PrettyVersions;

try {
    $version = PrettyVersions::getVersion('nonexistent/package');
} catch (\OutOfBoundsException $e) {
    echo "Package not found: " . $e->getMessage();
}
```

--------------------------------

### Retrieve Development Versions with PrettyVersions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Access short, pretty, and full version strings for packages installed from development branches.

```php
use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('symfony/event-dispatcher');

// For a development version installed from a branch:
echo $version->getShortVersion();  // 'dev-main'
echo $version->getPrettyVersion(); // 'dev-main@a8c47fe' (with short reference)

// Get the full version with all details
echo $version->getFullVersion();   // 'dev-main@a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d'
```

--------------------------------

### Handle ProvidedPackageException

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/exceptions.md

Example of catching an exception when attempting to retrieve a version for a virtual or provided package.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\ProvidedPackageException;

try {
    $version = PrettyVersions::getVersion('psr/log-implementation');
} catch (ProvidedPackageException $e) {
    echo "Error: " . $e->getMessage();
    // Output: "Cannot retrieve a version for package psr/log-implementation since it is provided, probably a metapackage"
}
```

--------------------------------

### Retrieve root package version

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Gets the Version object for the current project.

```php
$version = PrettyVersions::getRootPackageVersion();
echo $version->getPrettyVersion();
```

--------------------------------

### Get formatted version string

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns the version for display, including the short reference for development versions.

```php
echo $version->getPrettyVersion();  // '1.0.0' or 'dev-main@abc123d'
```

--------------------------------

### Get root project version information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Retrieve the package name and version for the root project.

```php
$root = PrettyVersions::getRootPackageVersion();
echo $root->getPackageName();      // Project name
echo $root->getPrettyVersion();    // Project version
```

--------------------------------

### Report dependency versions in PHP

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Fetches the version of a specific installed dependency and displays it in a pretty format.

```php
$version = PrettyVersions::getVersion('symfony/console');
echo "Using symfony/console " . $version->getPrettyVersion();
```

--------------------------------

### Handle Version Exceptions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/README.md

Catch specific exceptions when a package version cannot be resolved or the package is not installed.

```php
use Jean85\Exception\VersionMissingExceptionInterface;

try {
    $version = PrettyVersions::getVersion('package/name');
} catch (VersionMissingExceptionInterface $e) {
    // Handles ProvidedPackageException and ReplacedPackageException
} catch (\OutOfBoundsException $e) {
    // Package not installed
}
```

--------------------------------

### PrettyVersions::getVersion

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Retrieves the version information for a specific installed Composer package.

```APIDOC
## PrettyVersions::getVersion(string $packageName)

### Description
Retrieves the version object for a given package name.

### Parameters
- **$packageName** (string) - Required - The name of the package (e.g., 'vendor/pkg').

### Returns
- **Version** - An object containing version details.
```

--------------------------------

### Get package name

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns the name of the package associated with the Version object.

```php
echo $version->getPackageName();  // 'symfony/console'
```

--------------------------------

### Get version with full reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns the version string appended with the full commit reference.

```php
echo $version->getFullVersion();  // '1.0.0@abc123def456789...'
```

--------------------------------

### Retrieve root package name

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Gets the name of the current project as defined in composer.json.

```php
$name = PrettyVersions::getRootPackageName();
```

--------------------------------

### Handle Specific Version Exceptions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Catch distinct exceptions for virtual packages, replaced packages, or missing installations.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\ProvidedPackageException;
use Jean85\Exception\ReplacedPackageException;

$packageName = 'some/package';

try {
    $version = PrettyVersions::getVersion($packageName);
    echo "Version: " . $version->getShortVersion();
} catch (ProvidedPackageException $e) {
    // Package is a virtual package (metapackage)
    echo "This is a virtual package, cannot determine version";
} catch (ReplacedPackageException $e) {
    // Package has been replaced
    echo "This package has been replaced, use another package instead";
} catch (\OutOfBoundsException $e) {
    // Package is not installed
    echo "Package not installed in this project";
}
```

--------------------------------

### Functional Testing with Real Packages

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Perform integration tests by retrieving version information from real installed packages.

```php
// In functional tests
use Jean85\PrettyVersions;

public function testVersionRetrieval()
{
    $version = PrettyVersions::getVersion('phpunit/phpunit');
    $this->assertNotNull($version->getShortVersion());
    $this->assertNotEquals('', $version->getPrettyVersion());
}
```

--------------------------------

### Get full commit reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns the full commit hash associated with the version.

```php
echo $version->getReference();  // 'abc123def456789012345678901234567890'
```

--------------------------------

### Get short commit reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns the first 7 characters of the commit hash.

```php
echo $version->getShortReference();  // 'abc123d'
```

--------------------------------

### Get version with short reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns the version string appended with the short commit reference.

```php
echo $version->getVersionWithShortReference();  // '1.0.0@abc123d'
```

--------------------------------

### Check for Missing Reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/configuration.md

Example of using the NO_REFERENCE_TEXT constant to detect missing package reference data.

```php
use Jean85\Version;

$version = new Version('test/package', '1.0.0');

// Check for missing reference
if ($version->getReference() === Version::NO_REFERENCE_TEXT) {
    echo 'Reference is not available';
}
```

--------------------------------

### Collect dependency versions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Iterate through installed Composer packages to retrieve and display their pretty version strings.

```php
use Jean85\PrettyVersions;
use Composer\InstalledVersions;

// Get a list of all installed packages
$installed = InstalledVersions::getInstalledPackages();

// Get pretty version for each
$versions = [];
foreach ($installed as $packageName) {
    try {
        $version = PrettyVersions::getVersion($packageName);
        $versions[$packageName] = $version->getPrettyVersion();
    } catch (\Exception $e) {
        // Skip packages that can't be versioned
    }
}

// Display or process
foreach ($versions as $package => $version) {
    echo "$package: $version\n";
}
```

--------------------------------

### Differentiating Between Specific Errors

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/exceptions.md

Catch specific exception types to provide tailored feedback based on whether a package is virtual, replaced, or simply not installed.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\ProvidedPackageException;
use Jean85\Exception\ReplacedPackageException;

try {
    $version = PrettyVersions::getVersion('some/package');
} catch (ProvidedPackageException $e) {
    echo "This is a virtual package (metapackage)";
    // Provided packages don't have actual installations
} catch (ReplacedPackageException $e) {
    echo "This package has been replaced by another package";
    // The replacement package should be used instead
} catch (\OutOfBoundsException $e) {
    echo "Package is not installed in this project";
    // Package might need to be installed via Composer
}
```

--------------------------------

### Access various version formats and metadata

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Demonstrates methods to retrieve different string representations of a version and underlying package reference data.

```php
use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('monolog/monolog');

// Different version representations
$short = $version->getShortVersion();              // '3.0.0' or 'dev-main'
$pretty = $version->getPrettyVersion();            // '3.0.0' or 'dev-main@a8c47fe'
$withRef = $version->getVersionWithShortReference(); // '3.0.0@a8c47fe'
$full = $version->getFullVersion();               // '3.0.0@a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c'

// Reference information
$packageName = $version->getPackageName();        // 'monolog/monolog'
$reference = $version->getReference();            // Full commit hash
$shortRef = $version->getShortReference();        // First 7 chars of hash
```

--------------------------------

### Log Application Version

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Utilize the root package version object to log application startup details including the package name and short commit reference.

```php
use Jean85\PrettyVersions;

$rootVersion = PrettyVersions::getRootPackageVersion();

// Log with useful detail
error_log(sprintf(
    'Application %s started (version %s)',
    $rootVersion->getPackageName(),
    $rootVersion->getVersionWithShortReference()
));
```

--------------------------------

### Retrieve pretty version string

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Returns a formatted version string, using the version as-is for tagged releases or appending a short reference for development versions.

```php
public function getPrettyVersion(): string
```

```php
// Tagged version
$version = new Version('package', '1.0.0', 'abc123def456');
echo $version->getPrettyVersion();  // Output: '1.0.0'

// Development version
$version = new Version('package', 'dev-main', 'abc123def456');
echo $version->getPrettyVersion();  // Output: 'dev-main@abc123d'

// Pre-release version (still considered tagged)
$version = new Version('package', '2.0.0-RC1', 'abc123def456');
echo $version->getPrettyVersion();  // Output: '2.0.0-RC1'
```

--------------------------------

### Instantiate Version objects manually

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Create Version instances directly with full or minimal package information.

```php
use Jean85\Version;

// Create with all information
$version = new Version(
    'my/package',
    '1.0.0',
    'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b'
);

echo $version->getPrettyVersion();  // '1.0.0'

// Create with minimal information
$version = new Version('my/package');
echo $version->getShortVersion();   // '{no version}'
echo $version->getReference();      // '{no reference}'
```

--------------------------------

### Version::__construct

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Initializes a new Version object with package metadata.

```APIDOC
## __construct(string $packageName, ?string $prettyVersion = null, ?string $reference = null)

### Description
Creates a new Version object with package name, version, and reference information.

### Parameters
- **$packageName** (string) - Required - The package name (e.g., vendor/package)
- **$prettyVersion** (string) - Optional - The version string (e.g., 1.0.0, v1.2.3, dev-master). Defaults to {no version}.
- **$reference** (string) - Optional - The commit reference/hash. Defaults to {no reference}.

### Example
```php
use Jean85\Version;

$version = new Version('phpunit/phpunit', '9.5.28', 'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b');
```
```

--------------------------------

### Get version without reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns the version string excluding any commit reference.

```php
echo $version->getShortVersion();  // '1.0.0'
```

--------------------------------

### Display version in CLI applications

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Output root package details including name, version, and reference to the standard output.

```php
use Jean85\PrettyVersions;

// Display version information
echo "Application Version\n";
echo "====================\n";

$version = PrettyVersions::getRootPackageVersion();
echo "Name:     " . $version->getPackageName() . "\n";
echo "Version:  " . $version->getPrettyVersion() . "\n";
echo "Reference: " . $version->getShortReference() . "\n";
```

--------------------------------

### Log application version in PHP

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Retrieves the root package version and logs it with a short reference hash.

```php
$version = PrettyVersions::getRootPackageVersion();
error_log("Application started: " . $version->getVersionWithShortReference());
```

--------------------------------

### Compare package versions with external libraries

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Use an external library like composer/semver for comparisons, as this library only handles retrieval and formatting.

```php
use Jean85\PrettyVersions;

// Get version strings
$version1 = PrettyVersions::getVersion('package/one');
$version2 = PrettyVersions::getVersion('package/two');

// To compare, use a dedicated library like composer/semver
$v1String = $version1->getShortVersion();
$v2String = $version2->getShortVersion();

// With composer/semver:
// $comparison = Comparator::compare($v1String, '>', $v2String);
```

--------------------------------

### Retrieve package version information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Demonstrates fetching a package version and handling potential exceptions like missing packages or provided/replaced package errors.

```php
use Jean85\PrettyVersions;

// Get a specific package version
$phpunitVersion = PrettyVersions::getVersion('phpunit/phpunit');
echo (string) $phpunitVersion;  // Will output pretty version or version@reference

// Handle all possible errors
try {
    $version = PrettyVersions::getVersion('some/package');
} catch (\Jean85\Exception\VersionMissingExceptionInterface $e) {
    // Handles both ProvidedPackageException and ReplacedPackageException
    echo 'Cannot retrieve version: ' . $e->getMessage();
} catch (\OutOfBoundsException $e) {
    // Package not installed
    echo 'Package not found: ' . $e->getMessage();
}
```

--------------------------------

### Display version in web templates

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Retrieve the root package version and output it within HTML templates, ensuring proper escaping.

```php
use Jean85\PrettyVersions;

// In a template or view
?>
<footer>
    <?php 
        $version = PrettyVersions::getRootPackageVersion();
    ?>
    <p>Running <?php echo htmlspecialchars($version->getPackageName()); ?> 
       version <?php echo htmlspecialchars($version->getPrettyVersion()); ?></p>
</footer>
```

--------------------------------

### Check Version Availability

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Verify if version or reference information is available using NO_VERSION_TEXT and NO_REFERENCE_TEXT constants.

```php
use Jean85\Version;

$version = new Version('package', null, null);

if ($version->getShortVersion() === Version::NO_VERSION_TEXT) {
    echo 'Version is unknown';
}

if ($version->getReference() === Version::NO_REFERENCE_TEXT) {
    echo 'Reference is unknown';
}
```

--------------------------------

### PrettyVersions Usage Pattern

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Standard implementation for retrieving package version information.

```php
use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('vendor/package');
echo $version->getPrettyVersion();
```

--------------------------------

### Importing PrettyVersions Classes

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Essential import statements for accessing the main API and exception handling classes.

```php
// Main API
use Jean85\PrettyVersions;
use Jean85\Version;

// Exception handling
use Jean85\Exception\VersionMissingExceptionInterface;
use Jean85\Exception\ProvidedPackageException;
use Jean85\Exception\ReplacedPackageException;

// Or use built-in
use OutOfBoundsException;
```

--------------------------------

### Retrieve short version string

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Returns the version string exactly as provided without reference information.

```php
public function getShortVersion(): string
```

```php
$version = new Version('package', '9.5.28', 'a8c47fe');
echo $version->getShortVersion();  // Output: '9.5.28'

$version = new Version('package', 'dev-master');
echo $version->getShortVersion();  // Output: 'dev-master'
```

--------------------------------

### Format Version for Display

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Retrieve package versions and format them based on whether they are development or stable releases.

```php
use Jean85\PrettyVersions;

// Get a package version
$version = PrettyVersions::getVersion('symfony/console');

// Display appropriate format based on version type
if (str_contains($version->getShortVersion(), 'dev')) {
    echo "Development version: " . $version->getVersionWithShortReference();
} else {
    echo "Stable version: " . $version->getPrettyVersion();
}
```

--------------------------------

### Static Facade Pattern Implementation

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

The PrettyVersions class acts as a static facade over Composer's InstalledVersions.

```php
class PrettyVersions
{
    public static function getVersion(string $packageName): Version
    {
        // Facade logic: validation + object wrapping
    }
}
```

--------------------------------

### Retrieve version with short reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Returns the version string formatted with the short reference appended.

```php
public function getVersionWithShortReference(): string
```

```php
$version = new Version('package', '1.0.0', 'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b');
echo $version->getVersionWithShortReference();  // Output: '1.0.0@a8c47fe'

$version = new Version('package', 'dev-master', 'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b');
echo $version->getVersionWithShortReference();  // Output: 'dev-master@a8c47fe'
```

--------------------------------

### Check for missing version or reference information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Verify if a version or reference is unavailable by comparing against predefined constants.

```php
if ($version->getShortVersion() === Version::NO_VERSION_TEXT) {
    // No version available
}

if ($version->getReference() === Version::NO_REFERENCE_TEXT) {
    // No reference available
}
```

--------------------------------

### NO_VERSION_TEXT constant usage

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Defines the placeholder for missing version information and demonstrates checking for it.

```php
public const NO_VERSION_TEXT = '{no version}';
```

```php
if ($version->getShortVersion() === Version::NO_VERSION_TEXT) {
    echo 'Version information is not available';
}
```

--------------------------------

### Display project documentation file structure

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/MANIFEST.md

Visual representation of the generated documentation directory tree.

```text
output/
├── INDEX.md                           (Navigation index)
├── README.md                          (Overview & quick start)
├── library-overview.md                (Deep introduction)
├── api-reference-prettyversions.md    (PrettyVersions API)
├── api-reference-version.md           (Version API)
├── exceptions.md                      (Exception reference)
├── types.md                           (Types and interfaces)
├── configuration.md                   (Configuration)
├── module-architecture.md             (Architecture)
├── usage-guide.md                     (Usage examples)
├── quick-reference.md                 (Quick reference)
└── MANIFEST.md                        (This file)
```

--------------------------------

### Log Version Information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Include package version details in application logs using the short reference format.

```php
use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('monolog/monolog');

// Log entry includes package and version
error_log("Using monolog " . $version->getVersionWithShortReference());
```

--------------------------------

### Project Source Files Structure

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Overview of the library's directory structure and main classes.

```text
src/
├── PrettyVersions.php                          # Main public API
├── Version.php                                 # Version value object
└── Exception/
    ├── VersionMissingExceptionInterface.php    # Exception interface
    ├── ProvidedPackageException.php            # For virtual packages
    └── ReplacedPackageException.php            # For replaced packages
```

--------------------------------

### Common One-Line API Operations

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Quick reference for common tasks like retrieving package versions, root information, and formatting version strings.

```php
PrettyVersions::getVersion('vendor/pkg')->getPrettyVersion()
```

```php
PrettyVersions::getRootPackageVersion()->getPrettyVersion()
```

```php
PrettyVersions::getRootPackageName()
```

```php
$v->getShortVersion() !== Version::NO_VERSION_TEXT
```

```php
$version->getShortReference()
```

```php
$version->getVersionWithShortReference()
```

```php
(string)$version or "$version"
```

--------------------------------

### Version::__construct

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Creates a new Version object.

```APIDOC
## Version::__construct(string $packageName, ?string $prettyVersion = null, ?string $reference = null)

### Description
Creates a new Version object.

### Parameters
- **$packageName** (string) - Required - Package name
- **$prettyVersion** (?string) - Optional - Version string
- **$reference** (?string) - Optional - Commit hash
```

--------------------------------

### Check Version Availability

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/types.md

Use the defined sentinel constants to verify if version or reference data is present before accessing it.

```php
use Jean85\Version;
use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('some/package');

// Check if version information exists
$hasVersion = $version->getShortVersion() !== Version::NO_VERSION_TEXT;
$hasReference = $version->getReference() !== Version::NO_REFERENCE_TEXT;

if ($hasVersion) {
    echo "Version: " . $version->getShortVersion();
}

if ($hasReference) {
    echo "Reference: " . $version->getShortReference();
}
```

--------------------------------

### Retrieve and display a package version

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Fetches a package version object and outputs it using either the getPrettyVersion method or direct string casting.

```php
use Jean85\PrettyVersions;

// Get version of an installed package
$version = PrettyVersions::getVersion('symfony/console');

// Get the pretty-printed version string
echo $version->getPrettyVersion();  // e.g., "6.0.0"

// Or use string casting (equivalent to getPrettyVersion())
echo "Using " . $version;  // e.g., "Using 6.0.0"
```

--------------------------------

### Run library tests and quality checks

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Commands for executing local test suites, static analysis, and code style verification.

```bash
# Run tests locally
composer test

# Run type checking
composer phpstan

# Run code quality checks
composer cs-check
```

--------------------------------

### PrettyVersions::getRootPackageVersion()

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Retrieves the version information for the root (current) project.

```APIDOC
## public static function getRootPackageVersion()

### Description
Retrieves the version information for the root (current) project as a Version object.

### Return Type
- **Version** - A Version object containing the root package's version and reference information.
```

--------------------------------

### Access root project information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Retrieves the name and version information for the current root project.

```php
use Jean85\PrettyVersions;

// Identify the current project
$projectName = PrettyVersions::getRootPackageName();

// Get version info about the current project
$projectVersion = PrettyVersions::getRootPackageVersion();

// Log or display version information
echo "Running {$projectName} version {$projectVersion->getShortVersion()}";
```

--------------------------------

### Version::getVersionWithShortReference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns version with short reference appended.

```APIDOC
## Version::getVersionWithShortReference()

### Description
Returns version with short reference appended.

### Returns
- **string** - Format: version@shortref
```

--------------------------------

### Retrieve Root Project Information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Access the root package name and version details directly from the composer.json context.

```php
use Jean85\PrettyVersions;

// Get the name of the current project (from composer.json)
$projectName = PrettyVersions::getRootPackageName();
// e.g., "my-vendor/my-application"

// Get version information about the current project
$projectVersion = PrettyVersions::getRootPackageVersion();

echo "Project: " . $projectName;
echo "Version: " . $projectVersion->getPrettyVersion();
```

--------------------------------

### Retrieve root package version

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Defines the signature for fetching version details of the current root project.

```php
public static function getRootPackageVersion(): Version
```

--------------------------------

### Mocking PrettyVersions via Wrapper

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Use a wrapper class to inject version information, facilitating easier mocking in unit tests.

```php
// When testing code that uses PrettyVersions, either:
// 1. Refactor to inject the version information
// 2. Use a test environment where real packages are installed
// 3. Create a wrapper class that can be mocked more easily

class VersionProvider {
    public function getVersion(string $package) {
        return \Jean85\PrettyVersions::getVersion($package);
    }
}

// Now you can mock VersionProvider in tests
```

--------------------------------

### Directory Structure

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Visual representation of the package file organization.

```text
jean85/pretty-package-versions/
├── src/
│   ├── PrettyVersions.php                 # Main public API (static facade)
│   ├── Version.php                        # Value object for version data
│   └── Exception/
│       ├── VersionMissingExceptionInterface.php   # Exception interface
│       ├── ProvidedPackageException.php           # Provided package error
│       └── ReplacedPackageException.php           # Replaced package error
├── composer.json                          # Package metadata
└── README.md                              # Documentation
```

--------------------------------

### Handling All Possible Errors

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/exceptions.md

Implement a comprehensive catch block to handle specific package issues, missing packages, and general Composer errors.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\VersionMissingExceptionInterface;

try {
    $version = PrettyVersions::getVersion('some/package');
} catch (VersionMissingExceptionInterface $e) {
    // Provided or replaced package
    echo "Package issue: " . $e->getMessage();
} catch (\OutOfBoundsException $e) {
    // Package not installed
    echo "Package not found: " . $e->getMessage();
} catch (\Throwable $e) {
    // Any other error from Composer
    echo "Unknown error: " . $e->getMessage();
}
```

--------------------------------

### Version Constructor Signature

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/configuration.md

The constructor signature for the Version class.

```php
public function __construct(string $packageName, ?string $prettyVersion = null, ?string $reference = null)
```

--------------------------------

### PrettyVersions Public Interface

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Public static methods available on the PrettyVersions facade.

```php
public static function getVersion(string $packageName): Version
public static function getRootPackageName(): string
public static function getRootPackageVersion(): Version
```

--------------------------------

### Jean85\Version Methods

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/README.md

Methods available on the Version object returned by PrettyVersions::getVersion.

```APIDOC
## Jean85\Version Methods

### Methods
- **getPrettyVersion()**: string - Returns the short version or version with short commit.
- **getShortVersion()**: string - Returns the package version (e.g., '6.0.0').
- **getReference()**: string - Returns the full Git commit hash.
- **getShortReference()**: string - Returns the shortened Git commit hash.
- **getVersionWithShortReference()**: string - Returns version followed by short reference (e.g., '6.0.0@fa5711').
- **getPackageName()**: string - Returns the original package name.
- **getFullVersion()**: string - Returns the raw version string.
- **__toString()**: string - Returns the pretty version string.
```

--------------------------------

### Retrieve root package name

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Defines the signature for fetching the name of the current root project.

```php
public static function getRootPackageName(): string
```

--------------------------------

### Accessing Package Versions Statically

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/configuration.md

Public methods are static and do not require constructor configuration, as state is managed directly by the Composer environment.

```php
use Jean85\PrettyVersions;

// No constructor needed
// No configuration objects
// All state is managed by Composer
$version = PrettyVersions::getVersion('vendor/package');

// Multiple calls with same package return equivalent objects
$v1 = PrettyVersions::getVersion('vendor/package');
$v2 = PrettyVersions::getVersion('vendor/package');
// $v1->getPrettyVersion() === $v2->getPrettyVersion() (same content, different objects)
```

--------------------------------

### Retrieve full reference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Returns the full 40-character commit hash or a placeholder if no reference is available.

```php
public function getReference(): string
```

```php
$version = new Version('package', '1.0.0', 'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b');
echo $version->getReference();  // Output: 'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b'

$version = new Version('package', '1.0.0');
echo $version->getReference();  // Output: '{no reference}'
```

--------------------------------

### Retrieve package version information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-prettyversions.md

Defines the signature for fetching version details of a specific package.

```php
public static function getVersion(string $packageName): Version
```

--------------------------------

### Version::getPackageName

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns package name.

```APIDOC
## Version::getPackageName()

### Description
Returns package name.

### Returns
- **string** - Package name (e.g., 'symfony/console')
```

--------------------------------

### Retrieve package version information

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/README.md

Use PrettyVersions::getVersion to obtain a Version object for a specific package, which can then be queried for version strings and references.

```php
use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('phpunit/phpunit');
$version->getPrettyVersion(); // '6.0.0'
$version->getShortVersion(); // '6.0.0'
$version->getVersionWithShortReference(); // '6.0.0@fa5711'

$version = PrettyVersions::getVersion('roave/security-advisories');
$version->getPrettyVersion(); // 'dev-master@7cd88c8'
$version->getShortVersion(); // 'dev-master'
$version->getVersionWithShortReference(); // 'dev-master@7cd88c8'
```

--------------------------------

### Version::getPrettyVersion

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns formatted version for display.

```APIDOC
## Version::getPrettyVersion()

### Description
Returns formatted version for display. Returns version only for tagged releases, or version@shortref for development versions.

### Returns
- **string** - Formatted version string
```

--------------------------------

### Version Instance Methods

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/README.md

Methods available on the Version object returned by PrettyVersions to access specific version details.

```APIDOC
## Version Instance Methods

### Methods
- **getPrettyVersion()** (string) - Returns version only (tagged) or version@ref (dev).
- **getShortVersion()** (string) - Returns version string without reference.
- **getReference()** (string) - Returns full commit hash or {no reference}.
- **getShortReference()** (string) - Returns first 7 characters of hash or {no reference}.
- **getVersionWithShortReference()** (string) - Returns format: version@shortref.
- **getFullVersion()** (string) - Returns format: version@fullref.
- **getPackageName()** (string) - Returns the package name.
- **__toString()** (string) - Returns the pretty version string.
```

--------------------------------

### Handle Missing Version References

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Check for the existence of reference or version information before accessing them to avoid errors with packages lacking commit data.

```php
use Jean85\Version;
use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('some/package');

// Check if reference information exists
if ($version->getReference() !== Version::NO_REFERENCE_TEXT) {
    echo "Reference available: " . $version->getShortReference();
} else {
    echo "No reference information available";
}

// Similarly for version information
if ($version->getShortVersion() !== Version::NO_VERSION_TEXT) {
    echo "Version: " . $version->getShortVersion();
} else {
    echo "Version information not available";
}
```

--------------------------------

### Create Version object

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Instantiates a new immutable Version object.

```php
$v = new Version('vendor/package', '1.0.0', 'abc123def456');
```

--------------------------------

### Batch retrieve package versions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Iterate through a list of packages and handle potential VersionMissingExceptionInterface or OutOfBoundsException errors individually.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\VersionMissingExceptionInterface;

$packages = [
    'symfony/console',
    'monolog/monolog',
    'phpunit/phpunit',
];

$versions = [];

foreach ($packages as $packageName) {
    try {
        $versions[$packageName] = PrettyVersions::getVersion($packageName);
    } catch (VersionMissingExceptionInterface | \OutOfBoundsException $e) {
        echo "Skipping {$packageName}: " . $e->getMessage() . "\n";
        $versions[$packageName] = null;
    }
}

// Display results
foreach ($versions as $name => $version) {
    if ($version) {
        echo "{$name}: " . $version->getPrettyVersion() . "\n";
    }
}
```

--------------------------------

### Root Package Utilities

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/README.md

Utility methods for retrieving information about the root project package.

```APIDOC
## Root Package Utilities

### Methods
- **PrettyVersions::getRootPackageName()**: string - Returns the name of the root project from composer.json.
- **PrettyVersions::getRootPackageVersion()**: Version - Returns the Version object for the root project.
```

--------------------------------

### PrettyVersions::getVersion(string $packageName)

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/README.md

Retrieves a Version object for the specified package name.

```APIDOC
## PrettyVersions::getVersion(string $packageName)

### Description
Fetches the version information for a given composer package.

### Parameters
- **packageName** (string) - Required - The name of the package (e.g., 'phpunit/phpunit').

### Returns
- **Version** (Object) - An instance of Jean85\Version containing the package details.
```

--------------------------------

### Accessing PrettyVersions Statically

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

The library uses static methods exclusively, requiring no constructors or dependency injection.

```php
// No constructors needed
$v = PrettyVersions::getVersion('vendor/pkg');

// No instance state
$root = PrettyVersions::getRootPackageName();

// No configuration
// (use Version constructor if needed)
```

```php
// Always use the static methods directly
$version = PrettyVersions::getVersion('symfony/console');

// Not: $service->getVersion() or similar
```

--------------------------------

### NO_VERSION_TEXT

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Constant representing the placeholder string when no version information is available.

```APIDOC
## NO_VERSION_TEXT

### Description
The placeholder string used when no version information is available.

### Value
`'{no version}'`
```

--------------------------------

### Usage of VersionMissingExceptionInterface

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/types.md

Demonstrates creating an exception instance and catching it using the interface type.

```php
use Jean85\Exception\VersionMissingExceptionInterface;
use Jean85\Exception\ProvidedPackageException;

// Called internally by PrettyVersions::getVersion()
$exception = ProvidedPackageException::create('psr/log-implementation');

// Can be caught as the interface type
try {
    throw $exception;
} catch (VersionMissingExceptionInterface $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Retrieve Package Versions

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/README.md

Access version information for specific packages or the root project using static methods.

```php
use Jean85\PrettyVersions;

// Get version of a package
$version = PrettyVersions::getVersion('symfony/console');
echo $version->getPrettyVersion();  // e.g., "6.0.0"

// Get root project version
$myVersion = PrettyVersions::getRootPackageVersion();
echo $myVersion->getVersionWithShortReference();  // e.g., "1.0.0@a8c47fe"
```

--------------------------------

### Define ProvidedPackageException create method

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/exceptions.md

The static factory method signature for creating a ProvidedPackageException instance.

```php
public static function create(string $packageName): VersionMissingExceptionInterface
```

--------------------------------

### Implement Unified Exception Handling

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Use the VersionMissingExceptionInterface to catch multiple related package exceptions in a single block.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\VersionMissingExceptionInterface;

try {
    $version = PrettyVersions::getVersion('some/package');
} catch (VersionMissingExceptionInterface $e) {
    // Catches both ProvidedPackageException and ReplacedPackageException
    echo "Cannot retrieve version: " . $e->getMessage();
} catch (\OutOfBoundsException $e) {
    // Package not installed
    echo "Package not found";
}
```

--------------------------------

### __toString()

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Converts the Version object to a string.

```APIDOC
## __toString()

### Description
Converts the Version object to a string, equivalent to calling getPrettyVersion().

### Return Type
string
```

--------------------------------

### Version Constants

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Default text values used when version or reference data is missing.

```php
public const NO_VERSION_TEXT = '{no version}';
public const NO_REFERENCE_TEXT = '{no reference}';
```

--------------------------------

### Retrieve package name

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Returns the package name as provided during object construction.

```php
public function getPackageName(): string
```

```php
$version = new Version('phpunit/phpunit', '9.5.28');
echo $version->getPackageName();  // Output: 'phpunit/phpunit'
```

--------------------------------

### Expose version info in API responses

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Extracts package name and short version string for use in API response payloads.

```php
$version = PrettyVersions::getRootPackageVersion();
return [
    'name' => $version->getPackageName(),
    'version' => $version->getShortVersion(),
];
```

--------------------------------

### Static Factory Pattern

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Exceptions utilize static create methods for instantiation.

```php
interface VersionMissingExceptionInterface
{
    public static function create(string $packageName): self;
}
```

--------------------------------

### Display source code structure

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/INDEX.md

Visual representation of the library's source directory layout.

```text
src/
├── PrettyVersions.php
├── Version.php
└── Exception/
    ├── VersionMissingExceptionInterface.php
    ├── ProvidedPackageException.php
    └── ReplacedPackageException.php
```

--------------------------------

### Version::__construct

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/configuration.md

Constructor for the Version class used to represent a package version.

```APIDOC
## Version::__construct

### Description
Initializes a new instance of the Version class. This is typically used to represent a specific package version.

### Signature
`public function __construct(string $packageName, ?string $prettyVersion = null, ?string $reference = null)`

### Parameters
- **$packageName** (string) - Required - The package name (vendor/package format)
- **$prettyVersion** (string) - Optional - The version string. If null, defaults to '{no version}'
- **$reference** (string) - Optional - The commit reference. If null, defaults to '{no reference}'

### Example
```php
use Jean85\Version;

// Standard usage with all parameters
$version = new Version(
    'phpunit/phpunit',
    '9.5.28',
    'a8c47fe12d3e4f8b2c1a9e6d5f3b2a1c9e8d7c6b'
);

// With minimal parameters
$version = new Version('my/package');
```
```

--------------------------------

### PrettyVersions Protected Methods

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Internal validation methods used by the facade.

```php
protected static function checkProvidedPackages(string $packageName): void
protected static function checkReplacedPackages(string $packageName): void
```

--------------------------------

### Jean85\Version

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Value object representing package version information with formatting methods.

```APIDOC
## Jean85\Version

### Methods
- `getPrettyVersion(): string` - Returns the formatted version string.
- `getShortVersion(): string` - Returns the version without the reference.
- `getReference(): string` - Returns the full commit hash.
- `getShortReference(): string` - Returns the first 7 characters of the commit hash.
- `getVersionWithShortReference(): string` - Returns the version combined with the short reference.
- `getFullVersion(): string` - Returns the version combined with the full reference.
- `getPackageName(): string` - Returns the package name.
- `__toString(): string` - Returns the string representation of the version.
```

--------------------------------

### Catching ReplacedPackageException

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/exceptions.md

Demonstrates how to catch the ReplacedPackageException when a package has been superseded by another.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\ReplacedPackageException;

try {
    $version = PrettyVersions::getVersion('monolog/monolog');
} catch (ReplacedPackageException $e) {
    echo "Error: " . $e->getMessage();
    // Output: "Cannot retrieve a version for package monolog/monolog since it is replaced by some other package"
}
```

--------------------------------

### getPackageName()

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/api-reference-version.md

Returns the package name.

```APIDOC
## getPackageName()

### Description
Returns the package name exactly as provided in the constructor.

### Return Type
string
```

--------------------------------

### Version::getShortVersion

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns version without reference.

```APIDOC
## Version::getShortVersion()

### Description
Returns version without reference.

### Returns
- **string** - Version string (e.g., '1.0.0', 'dev-main', '{no version}')
```

--------------------------------

### Convert Version to string

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Implicitly converts the Version object to a string, equivalent to calling getPrettyVersion().

```php
echo "Version: $version";  // Uses __toString() automatically
```

--------------------------------

### Handle VersionMissingExceptionInterface

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/module-architecture.md

Catching the interface allows unified handling of both provided and replaced package exceptions.

```php
use Jean85\PrettyVersions;
use Jean85\Exception\VersionMissingExceptionInterface;

try {
    $version = PrettyVersions::getVersion('some/package');
} catch (VersionMissingExceptionInterface $e) {
    // Handles both ProvidedPackageException and ReplacedPackageException
}
```

--------------------------------

### Leverage Composer caching

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/usage-guide.md

Utilize Composer's internal in-memory cache by calling getVersion repeatedly for the same package.

```php
use Jean85\PrettyVersions;

// Both calls hit Composer's cache, no repeated disk I/O
$v1 = PrettyVersions::getVersion('symfony/console');
$v2 = PrettyVersions::getVersion('symfony/console');

// These are different objects but have identical content
assert($v1->getPrettyVersion() === $v2->getPrettyVersion());
```

--------------------------------

### Collect version data for debugging

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/library-overview.md

Aggregates multiple package versions into an array for inclusion in error reports or support tickets.

```php
$versions = [
    'app' => PrettyVersions::getRootPackageVersion()->getPrettyVersion(),
    'symfony' => PrettyVersions::getVersion('symfony/console')->getPrettyVersion(),
];
```

--------------------------------

### Version::getReference

Source: https://github.com/jean85/pretty-package-versions/blob/2.x/_autodocs/quick-reference.md

Returns full commit reference/hash.

```APIDOC
## Version::getReference()

### Description
Returns full commit reference/hash.

### Returns
- **string** - Full hash or '{no reference}'
```
Tokens:
Raw