breaking_change_in_php_framework_skill

Overview

This skill reviews PHP framework changes to detect breaking changes for public, externally visible APIs and verifies that any breaking changes are documented and handled. It applies rules that treat classes tagged @internal differently from public classes. The goal is to prevent accidental API disruptions for external consumers and ensure proper changelog entries when breaking changes occur.

How this skill works

The skill inspects PHP source and docblocks to identify classes and methods, focusing on public methods and their signatures. It flags changes such as argument removals, type alterations, return-value modifications, and unexpected response changes. Classes marked with @internal are treated as internal implementation and their public API changes are not considered breaking. When a breaking change is detected, the skill checks for a clear entry in CHANGELOG.md or the pull request notes.

When to use it

• During pull request reviews for libraries and frameworks intended for external use
• Before releasing a new minor or major version to confirm compatibility guarantees
• When refactoring public classes or altering method signatures
• When changing serialization, output formats, or API response structures
• When adding abstraction layers or altering return types

Best practices

• Treat any public, non-@internal class API changes as potential breaking changes unless only safe additions (optional args with defaults) are made
• Document every confirmed breaking change in the changelog and link it in the pull request
• Use @internal on implementation-only classes to reduce churn in external APIs
• Prefer additive changes (new methods, optional parameters) over removals or narrowing types
• Include unit/integration tests that demonstrate preserved behavior for common external use cases

Example use cases

• Adding a required parameter to a public method — flag as breaking and require changelog entry
• Refactoring internals of a @internal class — do not treat as breaking for external users
• Changing a method's return structure that affects JSON responses — mark as breaking and update docs
• Widening type hints where existing use cases still work — treat as non-breaking if compatibility preserved
• Removing a public method used by consumers — always a breaking change and must be documented