doc: add warning about composer bug

doc/languages-frameworks/php.section.md

@@ -214,6 +214,12 @@ code, while others choose not to.
 
 In Nix, there are multiple approaches to building a Composer-based project.
 
+::: {.warning}
+`buildComposerProject2` has a [known bug](https://github.com/NixOS/nixpkgs/issues/451395)
+where the `vendorHash` changes every a Composer release happens that changes the
+`autoload.php` or vendored composer code.
+:::
+
 One such method is the `php.buildComposerProject2` helper function, which serves
 as a wrapper around `mkDerivation`.
 

pkgs/development/php-packages/composer/default.nix

@@ -14,6 +14,13 @@
   versionCheckHook,
 }:
 
+/*
+    XXX IMPORTANT
+
+    Make sure to check if the `vendorHash` of `buildComposerProject2` changes when updating!
+    See https://github.com/NixOS/nixpkgs/issues/451395
+*/
+
 stdenvNoCC.mkDerivation (finalAttrs: {
   pname = "composer";
   version = "2.8.12";