Guia de retrocompatibilidade

Garantir que você possa atualizar suas aplicações facilmente é importante para nós. Por esse motivo, apenas quebramos compatibilidade nos major releases. Você deve estar familiarizado com versionamento semântico, orientação usada em todos os projetos do CakePHP. Resumindo, significa que apenas major releases (tais como 2.0, 3.0, 4.0) podem quebrar retrocompatibilidades. Minor releases (tais como 2.1, 3.1, 4.1) podem introduzir novos recursos, mas não podem quebrar retrocompatibilidades. Releases de correção de bugs (tais como 2.1.2, 3.0.1) não incluem novos recursos, são destinados apenas à correção de erros e melhora de desempenho.

Nota

O CakePHP começou a seguir o versionamento semântico na versão 2.0.0. Essas regras não se aplicam às versões 1.x.

Para esclarecer que mudanças você pode esperar em cada ciclo de release, nós temos mais informações detalhadas para desenvolvedores usando o CakePHP, e para desenvolvedores trabalhando Não CakePHP que ajudam a definir espectativas do que pode ser feito em minor releases. Major releases podem ter tantas quebras quanto forem necessárias.

Guia de migração

Para cada major ou minor releases, a equipe do CakePHP vai disponibilizar um guia de migração. Esses guias explicam os novos recursos e qualquer quebra de compatibilidade. Eles podem ser encontrados na seção Apêndices do manual.

Usando o CakePHP

Se você está construindo sua aplicação com o CakePHP, as orientações a seguir vão demonstrar a estabilidade que você pode esperar.

Interfaces

Com exceção dos major releases, interfaces oferecidas pelo CakePHP não irão ter alterações em qualquer método. Novos métodos podem ser incluídos, mas nenhum método existente será alterado.

Classes

Classes oferecidas pelo CakePHP podem ser construidas e ter seus métodos públicos e propriedades usados Não código da aplicação e com exceção de major releases a retrocompatibilidade é garantida.

Nota

Algumas classes Não CakePHP são marcadas com a tag da documentação da API @internal. Essas classes não são estáveis e não tem garantias de retrocompatibilidade.

Em minor releases, novos métodos podem ser adicionados a classes, e métodos existentes podem passar a receber novos argumentos. Qualquer novo argumento vai ter valores padrões, mas se você sobrescrever métodos com uma assinatura diferente, é possível que você receba erros fatais. Métodos que recebem novos argumentos serão documentados Não guia de migração correspondente ao release.

A tabela a seguir descreve quais casos de uso e que tipo de compatibilidade você pode esperar do CakePHP.

Se você…

Retrocompatibilidade?

Typehint referente à classe

Sim

Criar uma nova instância

Sim

Estender a classe

Sim

Acessar uma propriedade pública

Sim

Chamar um método público

Sim

Estender uma classe e…

Sobrescrever uma propriedade pública

Sim

Acessar uma propriedade protegida

Não [1]

Sobrescrever uma propriedade protegida

Não [1]

Sobrescrever um método

Não [1]

Chamar um método protegido

Não [1]

Adicionar uma propriedade pública

Não

Adicionar um método público

Não

Adicionar um argumento a um método sobrescrito

Não [1]

Adicinar um valor padrão a um argumento de método existente

Sim

Trabalhando no CakePHP

Se você está ajudando a fazer o CakePHP ainda melhor, por favor, siga as orientações a seguir quando estiver adicionando/alterando funcionalidades:

Em um minor release você pode:

Em um minor release você pode…

Classes

Remover uma classe

Não

Remover uma interface

Não

Remover um trait

Não

Tornar final

Não

Tornar abstract

Não

Trocar o nome

Sim [2]

Properties

Adicionar uma propriedade pública

Sim

Remove a public property

Não

Adicionar uma propriedade protegida

Sim

Remover uma propriedade protegida

Sim [3]

Métodos

Adicionar um método público

Sim

Remover um método público

Não

Adicionar um método público

Sim

Mover para uma classe parente

Sim

Remover um método protegido

Sim [3]

Reduzir visibilidade

Não

Mudar nome do método

Sim [2]

Adicionar um novo argumento com valor padrão

Sim

Adicionar um novo argumento a um método existente.

Não

Remover um valor padrão de um argumento existente

Não