Support CalVer

[ghostwriter]

Hey @theseer

Installing the phpactor.phar file from https://github.com/phpactor/phpactor/releases fails, but the error message is not clear on why.

phpactor, started shipping a phar file since 2023.06.17.

Manually adding the phar information in .phive/phars.xml, I found out that it was only parsing SemVer compliant version strings, and not CalVer.

---

[nifr]

First of all - thank you @theseer for all the hard work you put into phive. It's such a great tool that I and so many other PHP developers have been using for years. It has become an integral and very valuable part of the PHP ecosystem ❤️

Additional information:

phpactor can not be installed with phive (version v0.16.0).

The command:

phive install phpactor/phpactor

fails with:

[WARNING] phpactor/phpactor <Version>: No downloadable PHAR

If you try to add phpactor manually to phive.xml using the latest version 2025.10.17.0 as follows:

<?xml version="1.0" encoding="UTF-8"?>
<phive xmlns="https://phar.io/phive">
  <phar name="phpactor/phpactor" version="2025.10.17.0" installed="2025.10.17.0" location="./tools/phpactor" copy="true"/>
</phive>

phar-io/version throws an exception during phive install because given version constraint is not SemVer compliant.

Error / Exception

[ERROR]    An error occurred while processing your request:

          Version string '2025.10.17.0' does not follow SemVer semantics
          
          #0 vendor/phar-io/version/src/Version.php(201)
          #1 vendor/phar-io/version/src/Version.php(32): PharIo\Version\Version->ensureVersionStringIsValid()
          #2 src/shared/config/PhiveXmlConfig.php(225): PharIo\Version\Version->__construct()
          #3 src/shared/config/PhiveXmlConfig.php(129): PharIo\Phive\PhiveXmlConfig->nodeToConfiguredPhar()
          #4 src/commands/install/InstallCommandConfig.php(93): PharIo\Phive\PhiveXmlConfig->getPhars()
          #5 src/commands/install/InstallCommandConfig.php(71): PharIo\Phive\InstallCommandConfig->getPharsFromPhiveXmlConfig()
          #6 src/commands/install/InstallCommand.php(44): PharIo\Phive\InstallCommandConfig->getRequestedPhars()
          #7 src/shared/cli/Runner.php(241): PharIo\Phive\InstallCommand->execute()
          #8 src/shared/cli/Runner.php(95): PharIo\Phive\Cli\Runner->execute()
          #9 (355): PharIo\Phive\Cli\Runner->run()
          #10 {main}

          Environment: PHP 8.5.1-dev (on Darwin 24.6.0)
          Phive Version: 0.16.0

          This should not have happened and is most likely a bug.
          Please report it at https://github.com/phar-io/phive/issues, make sure you include
          the full output of this error message. Thank you!

Would you be open to support with a PR that adds CalVer support to phar-io/version ? Could you share some thoughts how a potential implementation could look like?

[theseer]

The crash is, to me, expected behavior as we explicitly do not support CalVer as a versioning scheme.

I also do not see a way to implement any meaningful support for it: While parsing its fragment could be easily implemented - it's a date format after all ;) -, there is no compatibility information encoded into the string.

With semver you get a BC promise: Ignoring 0.x-releases, we have an implicit statement that it should be risk free to update to the latest release within the same major version.

I fail to see how a date based version identifier could transport that information?

The main reason for phar-io/version to exist is to provide a means of mapping a version constraint to phive, so it can enforce it when installing and updating. While we could of course tell that a release is "later", no other statement can be made. Will it be compatible? Is it containing new features or only bugfixes? Nobody knows..

For me, Calver is pretty useless, as it opens more questions than it answers.

If you have a fixed product, it may seem like it could work: Like I can have a container or other distribution of something that bundles everything it needs. That could have a date based version. But when that something has an API or allows custom means to extend it, I'm already at a loss.

Let's take the example of an OS, since they used Ubuntu as a case in their page. That's exactly a bundle of things. And it's ubuntu's responsibility that all bundled packages work in the respective bundle. But this thing breaks apart when I install something that is not controlled by ubuntu. Fun fact: Most applications don't care about the ubuntu version but the respective libraries bundled - which usually use semver.

The only place where I consider Calver useful is for distribution data. Like the timezone database, or a zone file for DNS. Or Address-Data with zipcodes, street and city and such. There knowing how recent the information is, makes a lot of sense.

TL;DR: I do not believe CalVer makes any sense in an environment where compatibility is the relevant information to be transported and as such, I do not see a means of implementing it in either phive or our version library. PR or not.

Feel free to try to convince me otherwise ;)