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.
Note
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.
Note
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 |