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

Мы обеспечиваем то, чтобы вы могли легко и плавно обновлять свои приложения. Вот почему мы нарушаем совместимость на основных этапах релиза. Вы можете быть знакомы с семантическим версированием, это общее руководство, которое мы используем для всех проектов 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,
]
// ...

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