Руководство по совместимости

Мы обеспечиваем то, чтобы вы могли легко и плавно обновлять свои приложения. Вот почему мы нарушаем совместимость на основных этапах релиза. Вы можете быть знакомы с семантическим версированием, это общее руководство, которое мы используем для всех проектов CakePHP. Короче говоря, семантическое управление версиями означает, что только основные выпуски (например, 2.0, 3.0, 4.0) могут иметь обратную совместимость. Незначительные релизы („Minor releases“)(например, 2.1, 3.1, 3.2), добавляющие функциональность, могут нарушать обратную совместимость. Исправления ошибок („Bug fix releases“)(например, 2.1.2, 3.0.1) не добавляют новых функций, но исправляют ошибки или повышают производительность.

Примечание

Устаревшее („Deprecations“) удаляется со следующей основной версией фреймворка. Вам рекомендуется на раннем этапе адаптировать ваш код уже к каждому незначительному релизу, как указано в комментарии к устареванию и руководстве по миграции.

Чтобы уточнить, какие изменения вы можете ожидать в каждом следующем выпуске, мы публикуем множнество подробной информации для разработчиков, использующих CakePHP, а также для разработчиков, работающих над CakePHP. Она помогает оправдать ожидания того, что можно сделать в небольших выпусках. Главные релизы („Major releases“) будут иметь наибольшее число изменений.

Руководства по миграции

Для каждого крупного и мелкого выпуска команда CakePHP обеспечивает руководство по миграции. Эти руководства объясняют новые функции и любые нарушения, которые есть в каждом выпуске. Их можно найти в разделе Приложение.

Использование CakePHP

Если вы создаёте своё приложение с помощью CakePHP, следующие рекомендации объяснят стабильность, которую вы можете ожидать.

Интерфейсы

Вне основных выпусков („мajor releases“), интерфейсы предоставляемые CakePHP, не будут содержать существенно изменившиеся методы. Могут быть добавлены новые методы, но никакие существующие методы не будут изменен.

Классы

Классы, предоставляемые CakePHP, могут быть построены и иметь свои общедоступные методы и свойства, используемые кодом приложения и вне основных выпусков, обеспечивая обратную совместимость.

Примечание

Некоторые классы в CakePHP помечены тегом API doc @internal. Эти классы не являются стабильными и не имеют обещаний обратной совместимости.

В небольших выпусках, могут быть добавлены новые классы, а в существующие методы могут быть добавлены новые аргументы. Любые новые аргументы будут иметь значения по умолчанию, но если вы переопределили методы с другой подписью(сигнатурой), это можете вызвать фатальные ошибки. Методы добавления новых аргументов будут описаны в руководстве по миграции для этой версии.

В следующей таблице приведены несколько вариантов использования и какую совместимость вы можете ожидать от CakePHP:

If you… Backwards compatibility?
Typehint against the class Yes
Create a new instance Yes
Extend the class Yes
Access a public property Yes
Call a public method Yes
Extend a class and…
Override a public property Yes
Access a protected property No [1]
Override a protected property No [1]
Override a protected method No [1]
Call a protected method No [1]
Add a public property No
Add a public method No
Add an argument to an overridden method No [1]
Add a default argument value to an existing method argument Yes

Работающим над CakePHP

Если вы помогаете сделать CakePHP еще лучше, соблюдайте следующие рекомендации при добавлении/изменении функциональности:

В незначительном выпуске вы можете:

In a minor release can you…
Classes
Remove a class No
Remove an interface No
Remove a trait No
Make final No
Make abstract No
Change name Yes [2]
Properties
Add a public property Yes
Remove a public property No
Add a protected property Yes
Remove a protected property Yes [3]
Methods
Add a public method Yes
Remove a public method No
Add a protected method Yes
Move to parent class Yes
Remove a protected method Yes [3]
Reduce visibility No
Change method name Yes [2]
Add a new argument with default value Yes
Add a new required argument to an existing method. No
Remove a default value from an existing argument No
Change method type void Yes
[1](1, 2, 3, 4, 5) Ваш код может быть нарушен небольшими выпусками. Проверьте руководство по миграции для уточнения деталей.
[2](1, 2) Вы можете изменить имя класса/метода, пока остаётся его прежнее имя. Этого обычно избегают, если переименование не имеет значительной выгоды.
[3](1, 2) Избегайте, когда это возможно. Любые удаления должны быть задокументированы в руководство по миграции.

Устаревшее

В каждом незначительном выпуске функции могут быть устаревшими. Если функции устарели, будет добавлена документация API и предупреждения времени выполнения. Ошибки выполнения помогают вам найти код, который необходимо обновить до его „смерти“. Если вы захотите отключить ошибки времени выполнения, вы можете сделать это с помощью конфигурации Error.errorLevel:

// in config/app.php
// ...
'Error' => [
    'errorLevel' => E_ALL ^ E_USER_DEPRECATED,
]
// ...

Отключит предупреждения об устаревании во время выполнения.