Our backwards Compatibility Promise

Using our Interfaces¶

All interfaces shipped with Symfony can be used in type hints. You can also call any of the methods that they declare. We guarantee that we won’t break code that sticks to these rules.

If you want to implement an interface, you should first make sure that the interface is an API interface. You can recognize API interfaces by the @api tag in their source code:

/**
 * HttpKernelInterface handles a Request to convert it to a Response.
 *
 * @author Fabien Potencier <fabien@symfony.com>
 *
 * @api
 */
interface HttpKernelInterface
{
    // ...
}

If you implement an API interface, we promise that we won’t ever break your code. Regular interfaces, by contrast, may be extended between minor releases, for example by adding a new method. Be prepared to upgrade your code manually if you implement a regular interface.

The following table explains in detail which use cases are covered by our backwards compatibility promise:

Using our Classes¶

All classes provided by Symfony may be instantiated and accessed through their public methods and properties.

Just like with interfaces, we also distinguish between regular and API classes. Like API interfaces, API classes are marked with an @api tag:

/**
 * Request represents an HTTP request.
 *
 * @author Fabien Potencier <fabien@symfony.com>
 *
 * @api
 */
class Request
{
    // ...
}

The difference between regular and API classes is that we guarantee full backwards compatibility if you extend an API class and override its methods. We can’t give the same promise for regular classes, because there we may, for example, add an optional argument to a method. Consequently, the signature of your overridden method wouldn’t match anymore and generate a fatal error.

In some cases, only specific properties and methods are tagged with the @api tag, even though their class is not. In these cases, we guarantee full backwards compatibility for the tagged properties and methods (as indicated in the column “API” below), but not for the rest of the class.

To be on the safe side, check the following table to know which use cases are covered by our backwards compatibility promise:

Changing Interfaces¶

This table tells you which changes you are allowed to do when working on Symfony’s interfaces:

Changing Classes¶

This table tells you which changes you are allowed to do when working on Symfony’s classes: