composer-package-hygienelisted

# Composer package hygiene — author-side discipline This skill applies whenever you are working on a PHP package that gets published to Packagist (or a private composer repository) and installed into other projects. Application code does not need this. > Mental model: every line in `composer.json`, every public class, every > tag is a **contract** with downstream consumers. Breaking the contract > requires a major bump. Hide implementation aggressively so you keep the > contract small. --- ## Semver — what counts as breaking | Change | Bump | |---|---| | Remove or rename a public class / method / function | major | | Add a required parameter to a public method | major | | Tighten a public parameter type (e.g. `string` → `int`) | major | | Loosen a public return type (e.g. `string` → `string\|null`) | major | | Raise PHP floor (`^7.4 \|\| ^8.0` → `^8.0`) | major | | Raise a runtime dependency's floor in a way that excludes existing supporters | major | | Add a new public class / method | minor | | Add an optional parameter with a default | minor | | Tighten a return type (e.g. `string\|null` → `string`) | minor | | Loosen a parameter type (e.g. `int` → `int\|string`) | minor | | Add a new optional dependency to `suggest` | minor | | Bug fix that doesn't change documented behaviour | patch | | Documentation, internal refactor, test-only change | patch | **Trap**: "we never documented this method as public — we can remove it". If the method has a `public` visibility modifi