Interfaces and Service Contracts
Interfaces are used for many models, services and validators where it may be beneficial to application integrating the SDK to replace functionality entirely, or implement alternative / additional versions (such as with validators or providers).
Replacing a concrete implementation of an interface should be avoided if possible; if necessary, the native class should be extended rather than replaced entirely. Dependency injection should be used to replace the smallest possible component to enable customisations, especially in composite classes such as the UserAgentProvider.
Interface will often be found as close to the aplicable implementations as possible, many times in the same folder. An exception to this is the root Api directory, which defines contracts for the primary models and services used in the php-sdk package.
Interfaces within the Api directory - as well as classes tagged @api should be considered stable within the major version in which they appear. This means that the class will not be removed or have its method signatures changed without bumping the major version of the application (eg from 1.x to 2.x). This includes the addition of new methods or interfaces.
Note, changes to non-api classes will still occur within minor and, occasionally, patch releases. This may include adding new classes / methods / optional arguments in public methods. Any potentially breaking changes will always accompany a major version upgrade. This may include removing classes or methods, or adding new mandatory arguments to existing public methods.
