Detalhes.md

Antes de algo, parabéns por se preocupar em como seu projeto ficará organizacionalmente orgânico.

Todo projeto precisa de organização, afinal, nenhum projeto nasce pra morrer, e não é porque você esta perdendo tempo ai na frente do seu computador, que seu código merece ser tratado com pouco dignidade, lembre-se, entregamos valores para pessoas que acreditam em nós e nós trabalharemos muito, para não trabalhar muito, esse sempre, deveria ser um bom mecanismo para nos guiar na jornada dev.

AppController

Como todos sabemos, controles derivam de um controle maior, então nele foi implementado algumas funções, que serviram de ajudadores para uma melhor compreensão e formatação sem muita reescrita de código. Algumas delas são:

protected function responseJson($json, int $code = 200)

Essa função nos ajuda a darmos saída de dados no formato json, ela quem suporta as duas funções abaixo.

protected function responseWithSuccess($data, $additional = [], $meta = [])

Uma forma clara e legível de dizer para o requisitador que tudo ocorreu bem com a solicitação, responda com um status 200 e algumas informações, tente passar uma entidade do cakephp direto pra essa função e veja que incrivel.

protected function responseWithErrors(
    InvalidPropertyInterface $entity,
    string $message = 'Houve um erro ao validar essa requisição',
    array $meta = [],
    int $status = 400
)

Mesmo efeito da de cima, com diferença que responde com um 400 ou a seu gosto, porém ele entra em pouco desuso, conforme PersistenceOrmFailedMiddleware vai fazendo seu papel.

protected function responseNotImplemented()

Em dias de desempenho, sua cabeça parece entender exatamente todos os endpoints e procedimentos que devem ocorrer numa determinado recurso a ser lançado, eu me sinto bem em colocar essa função numa ação do controle, porque já tenho como testar e saber, que tudo parece ok, além da vantagem de no proximo tempo, eu lembrar o que deveria fazer a mais no controle de um recurso.

protected function responseOk()

Sempre que um conteúdo é atualizado, ou simplesmente deletado, desejamos as vezes dizer pro requisitador que tudo ocorreu bem, tente usar esta função sempre.

PS* Lembre-se, isto é uma abstração, então, todo o fluxo que sai por aqui, pode ser facilmente modificado e impactará qualquer saida de reuso desse código, isso é excelente, mas também pode ser ruim, caso deseje altera-las, sinta-se a vontade, só lembre dos efeitos colaterais, que podem ou não serem causados.

Model/Table

Há algumas maneiras de se fazer comunicação Model->Controller um deles sem dúvida, seria por meio de retorno direto de uma função e posterior direcionamento do fluxo de execução no próprio controle, mas, outro modo, é gerando exceções no Table/Repository e capturando elas por meio de middlewares, você deixa o código do controle mais enxuto, e ainda faz o tratamento de erros duma maneira bem limpa e clara, veja a baixo como foi implementado uma.

// App\Model\Table\CompaniesTable.php
use App\Model\Traits\CreateRecordTrait

Esse camarada, expõe duas funções públicas:

instanceAndValidate($requestData, $options = [], string $messageValidation = ''): EntityInterface

Como o proprio nome já disse, ele instancia uma entidade e tenta validar ela, com alguns adicionais, você pode passar configuração para o newEntity e também uma mensagem basica pro validador, caso deseje ser genérico, em suma, ele gera o exception capaz de ser manipulador pelo PersistenceOrmFailedMiddleware gerando erros em json já tratados.

createOrFail(EntityInterface $entity, bool $generateUuid = true, string $messageValidation = '')

Ao tentar criar, ela é capaz de pegar erros ao tentar persistir dados no banco, então lança uma exceção para ser tratada no mesmo processo acima.

Porque ?

Ao olhar para essas metodologias você deve se perguntar porque tais implementações, ficou claro ao longo do tempo, que há melhor forma de fazer um bom código é primeiro escrever código simples e legivel, todas essas implementações lhe darão a oportunidade de deixar seu controle legível, a medida que você consegue facilmente saber onde qual rota vai chegar, no controle, você facilmente saberá entender o que ocorre nele:

App\Controller\CompaniesController.php

/**
 * Esse fluxo é tratado pelo PersistenceOrmFailedMiddleware
 * validate um exception caso tenha erros,
 * create outro exception caso tenha erros de persistencia
 * @return \Cake\Http\Response
 */
public function add()
{
    $company = $this->Companies->instanceAndValidate(
        $this->request->getData() // implementar melhorias de dados aqui
    );

    $this->Companies->createOrFail($company, true);
    
    // Porque não disparar um email ?
    // Porque não agendar uma tarefa de execução de um novo container Docker ?

    return $this
        ->responseWithSuccess($company);
}

a maioria das ações de seus controles, poderá seguir essa linha de raciocinio, elas ficarão simples.

Esclarecimento

Se pra você pareceu que essas descrições adotou algum tom de arrogancia, peço lhe minhas sinceras desculpas, abra uma issue, mande um pr, ficarei grato em discutirmos, você também é um ótimo programador.