Using exact version constraint when a composer.lock file is available

[drupol]

Hello,

I've been packaging PHPStan in Nix using the phpstan-src repository. Just a heads-up, we're all in on using source code instead of PHARs (nix recommandations). But let's not get sidetracked by that debate now; we can save it for another day if you really want to get into it.

I'm opening this discussion because while building PHPStan (just running composer install basically), we noticed that the composer validate step is failing:

❯ composer validate --strict --no-interaction
./composer.json is valid, but with a few warnings
See https://getcomposer.org/doc/04-schema.md for details on the schema
# General warnings
- The package "jetbrains/phpstorm-stubs" is pointing to a commit-ref, this is bad practice and can cause unforeseen issues.
- require.hoa/compiler : exact version constraints (3.17.08.08) should be avoided if the package follows semantic versioning
- require.hoa/file : exact version constraints (1.17.07.11) should be avoided if the package follows semantic versioning
- require.hoa/regex : exact version constraints (1.17.01.13) should be avoided if the package follows semantic versioning
- require.nette/di : exact version constraints (3.1.10) should be avoided if the package follows semantic versioning
- require.ondrejmirtes/better-reflection : exact version constraints (6.21.0) should be avoided if the package follows semantic versioning
- require.phpstan/phpdoc-parser : exact version constraints (1.26.0) should be avoided if the package follows semantic versioning
~/C/t/phpstan-src > 1.11.x > php ✘

This validation step is a blocker in the process of publishing a PHP app in Nix. To get around it for PHPStan, I added a specific flag composerStrictValidation and set it to false to chill out the validation step, making it not so strict. And guess what? It's been working out pretty well since then.

So, why am I bringing this up? I'm curious about the logic behind using exact version constraints in composer.json when we've already got a composer.lock to keep our dependencies in check. If composer.lock does the job, why double down in composer.json?

I'd love to hear your thoughts on this.

To give you an idea on the effort needed to fix the issue, this simple patch fixes it, let me know if you'd be keen to merge it.

From 9a8f7087576c76a9d0c093fa4377cddd3e529d66 Mon Sep 17 00:00:00 2001
From: Pol Dellaiera <pol.dellaiera@protonmail.com>
Date: Tue, 12 Mar 2024 11:56:24 +0100
Subject: [PATCH] fix: make `composer validate` happy

---
 composer.json | 16 ++++++++--------
 composer.lock |  2 +-
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/composer.json b/composer.json
index 61fe11a..49ed57a 100644
--- a/composer.json
+++ b/composer.json
@@ -11,21 +11,21 @@
 		"composer/ca-bundle": "^1.2",
 		"composer/xdebug-handler": "^3.0.3",
 		"fidry/cpu-core-counter": "^0.5.0",
-		"hoa/compiler": "3.17.08.08",
+		"hoa/compiler": "^3.17.08.08",
 		"hoa/exception": "^1.0",
-		"hoa/file": "1.17.07.11",
-		"hoa/regex": "1.17.01.13",
-		"jetbrains/phpstorm-stubs": "dev-master#9608c953230b08f07b703ecfe459cc58d5421437",
+		"hoa/file": "^1.17.07.11",
+		"hoa/regex": "^1.17.01.13",
+		"jetbrains/phpstorm-stubs": "dev-master",
 		"nette/bootstrap": "^3.0",
-		"nette/di": "3.1.10",
+		"nette/di": "^3.1.10",
 		"nette/neon": "^3.3.1",
 		"nette/schema": "^1.2.2",
 		"nette/utils": "^3.2.5",
 		"nikic/php-parser": "^4.17.1",
 		"ondram/ci-detector": "^3.4.0",
-		"ondrejmirtes/better-reflection": "6.21.0",
-		"phpstan/php-8-stubs": "0.3.84",
-		"phpstan/phpdoc-parser": "1.26.0",
+		"ondrejmirtes/better-reflection": "^6.21.0",
+		"phpstan/php-8-stubs": "^0.3.84",
+		"phpstan/phpdoc-parser": "^1.26.0",
 		"psr/http-message": "^1.1",
 		"react/async": "^3",
 		"react/child-process": "^0.6.4",
diff --git a/composer.lock b/composer.lock
index c9a7d60..014ebfb 100644
--- a/composer.lock
+++ b/composer.lock
@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "71a702eb8181ecb60c5b676f0070342c",
+    "content-hash": "095acb8b0b49b9670b527c947ee46234",
     "packages": [
         {
             "name": "clue/ndjson-react",
-- 
2.43.2

Thanks

[ondrejmirtes]

in Nix using the phpstan-src repository

No no no, that's completely unsupported. Because it simply does not work for analysing projects. Everybody should be using the PHAR from phpstan/phpstan.

I'm happy to help you with any PHAR-related questions, but you should really avoid using phpstan-src like that.

[drupol]

Thanks for the quick response. Just to clarify, the choice to use source code (phpstan-src) over PHARs wasn't mine, I was following instructions from long time knowledgeable maintainers. However, I've always been in favour of using official PHARs whenever they're available, even advocating for them about a year ago.

That said, myself and several other developers have been using PHPStan via Nix with the source code approach. I've been doing this for quite some time in my own projects without running into any issues. But I take your point seriously.

Could you elaborate on what exactly "it simply does not work for analysing projects" when not using the PHAR? I'm asking because I'd like to present a case to the other maintainers about the potential limitations of our current approach.

Thanks, looking forward to understanding more about the concerns you've raised.

[ondrejmirtes]

There's at least a dozen reasons in favour of PHAR files :) And it doesn't matter how severe or valid you see them, you should stop using phpstan-src for analysing projects anyway. Here are some off the top of my head, but it's definitely not a complete list.

• PHAR build process prefixes namespaces of dependencies that should not be propagated to the end-user, like Symfony or ReactPHP. Although PHPStan uses static reflection (https://phpstan.org/blog/zero-config-analysis-with-static-reflection), it will occasionally still load project dependencies (for example if you use things like objectManagerLoader, consoleApplicationLoader, or bootstrapFiles in phpstan.neon, or autoload.files in composer.json). And if the project uses same dependencies as phpstan-src does, but in different versions, 💥.
• PHPStan extensions (https://phpstan.org/user-guide/extension-library) are only compatible with phpstan/phpstan Composer package, which distributes PHPStan as a PHAR file. There's no phpstan/phpstan-src Composer package for all of the reasons in this comment.
• phpstan-src does not support the same PHP language version range as phpstan/phpstan. The built PHAR file supports PHP 7.2+, but phpstan-src is 8.1+ right now. I could change it to 8.3+ at any point, even in a patch version. Because it has no effect on PHPStan users, only contributors.
• Some PHPStan documentation does not apply when you're not running the PHAR file. For example: https://phpstan.org/blog/what-is-bleeding-edge
• phpstan-src simply installs jetbrains/phpstorm-stubs which has .php file extensions for all the stubs. On the other hand, the PHAR build process changes these file extensions to .stub so that the IDE index is not polluted with multiple declarations of the same classes which makes code autocompletion worse.
• Same point applies to phpstan/php-8-stubs.

[drupol]

Thank you very much for the comprehensive answer, I will push this further internally, and I'll let you know the outcome.