Guide de Compatibilité Rétroactive¶
Nous assurer que la mise à jour de vos applications se fasse facilement et en douceur est important à nos yeux. C’est pour cela que nous ne cassons la compatibilité que pour les versions majeures. Vous connaissez peut-être le versioning sémantique qui est la règle générale que nous utilisons pour tous les projets CakePHP. En résumé, le versioning sémantique signifie que seules les versions majeures (comme 2.0, 3.0, 4.0) peuvent casser la compatibilité rétroactive. Les versions mineures (comme 2.1, 3.1, 3.2) peuvent introduire de nouvelles fonctionnalités, mais ne cassent pas la compatibilité. Les versions de fix de Bug (comme 2.1.2, 3.0.1) n’ajoutent pas de nouvelles fonctionnalités, mais règlent seulement des bugs ou améliorent la performance.
Note
CakePHP a commencé à utiliser le versioning sémantique à partir de la version 2.0.0. Ces règles ne s’appliquent pas pour la version 1.x.
Pour clarifier les changements que vous pouvez attendre dans chaque version en entier, nous avons plus d’informations détaillées pour les développeurs utilisant CakePHP et pour les développeurs travaillant sur CakePHP qui définissent les attentes de ce qui peut être fait dans des versions mineures. Les versions majeures peuvent avoir autant de changements que nécessaires.
Guides de Migration¶
Pour chaque version majeure et mineure, l’équipe de CakePHP va fournir un guide de migration. Ces guides expliquent les nouvelles fonctionnalités et tout changement entraînant des modifications de chaque version. Ils se trouvent dans la section Annexes du cookbook.
Utiliser CakePHP¶
Si vous construisez votre application avec CakePHP, les conventions suivantes expliquent la stabilité que vous pouvez attendre.
Interfaces¶
En-dehors des versions majeures, les interfaces fournies par CakePHP ne vont pas connaître de modification des méthodes existantes. De nouvelles méthodes peuvent être ajoutées, mais aucune méthode existante ne sera changée.
Classes¶
Les classes fournies par CakePHP peuvent être construites et ont leurs méthodes public et les propriétés utilisées par le code de l’application et en-dehors des versions majeures, la compatibilité rétroactive est assurée.
Note
Certaines classes dans CakePHP sont marquées avec la balise de doc
@internal de l’API. Ces classes ne sont pas stables et
n’assurent pas forcément de compatibilité rétroactive.
Dans les versions mineures, les nouvelles méthodes peuvent être ajoutées aux classes, et les méthodes existantes peuvent avoir de nouveaux arguments ajoutés. Tout argument nouveau aura des valeurs par défaut, mais si vous surchargez des méthodes avec une signature différente, vous verrez peut-être des erreurs fatales. Les méthodes qui ont de nouveaux arguments ajoutés seront documentées dans le guide de migration pour cette version.
La table suivante souligne plusieurs cas d’utilisations et la compatibilité que vous pouvez attendre de CakePHP:
Si vous… |
Backwards compatibility? |
|---|---|
Typehint against the class |
Oui |
Crée une nouvelle instance |
Oui |
Etendre la classe |
Oui |
Access a public property |
Oui |
Appel d’une méthode publique |
Oui |
Etendre une classe et… |
|
Surcharger une propriété publique |
Oui |
Accéder à une propriété protégée |
Non [1] |
Surcharger une propriété protégée |
Non [1] |
Surcharger une méthode protégée |
Non [1] |
Apple d’une méthode protégée |
Non [1] |
Ajouter une propriété publique |
Non |
Ajouter une méthode publique |
Non |
Ajouter un argument pour une méthode qui surcharge |
Non [1] |
Ajouter une valeur d’argument par défaut pour une méthode existante |
Oui |
Travailler avec CakePHP¶
Si vous aidez à rendre CakePHP encore meilleur, merci de garder à l’esprit les conventions suivantes lors des ajouts/changements de fonctionnalités:
Dans une version mineure, vous pouvez:
Dans une versions mineure, pouvez-vous… |
|
|---|---|
Classes |
|
Retirer une classe |
Non |
Retirer une interface |
Non |
Retirer un trait |
Non |
Faire des final |
Non |
Faire des abstract |
Non |
Changer de nom |
Oui [2] |
Propriétés |
|
Ajouter une propriété publique |
Oui |
Retirer une propriété publique |
Non |
Ajouter une propriété protégée |
Oui |
Retirer une propriété protégée |
Oui [3] |
Méthodes |
|
Ajouter une méthode publique |
Oui |
Retirer une méthode publique |
Non |
Ajouter une méthode protégée |
Oui |
Déplacer une classe parente |
Oui |
Retirer une méthode protégée |
Oui [3] |
Réduire la visibilité |
Non |
Changer le nom de méthode |
Oui [2] |
Ajouter un nouvel argument avec la valeur par défaut |
Oui |
Ajouter un nouvel argument requis pour une méthode existante. |
Non |
Retirer une valeur par défaut à partir d’un argument existant |
Non |
Depréciations¶
Dans chaque version mineure, les fonctionnalités peuvent être dépréciées. Si les
fonctionnalités sont dépréciées, la documentation de l’API et des avertissements
à l’exécution seront ajoutés. Les erreurs à l’exécution vous aideront à
localiser le code qui doit être mis à jour avant qu’il ne casse. Si vous
souhaitez désactiver les avertissements à l’exécution, vous pouvez le faire en
utilisant la valeur de configuration Error.errorLevel:
// dans config/app.php
// ...
'Error' => [
'errorLevel' => E_ALL ^ E_USER_DEPRECATED,
]
// ...
Va désactiver les avertissements de dépréciation à l’exécution.