如何在CakePHP中捕获JSON:API的null关联值并符合规范？

嗨，我刚好在Ember+CakePHP的JSON:API项目里遇到过一模一样的问题，下面给你几个合规的解决方案，既能让CakePHP捕获到Ember发送的null关联值，又严格遵循JSON:API规范：

首先要明确：Ember移除关联时发送的JSON:API格式是符合规范的，比如更新post的author关联时，请求体应该是这样的：

{
  "data": {
    "type": "posts",
    "id": "1",
    "relationships": {
      "author": {
        "data": null
      }
    }
  }
}

CakePHP默认的表单数据解析会过滤掉null值，导致你拿不到这个关联的null标记。解决办法是直接读取原始请求体，绕过自动过滤：

在你的资源控制器（比如PostsController）的更新方法里，这样处理：

public function update($id)
{
    $post = $this->Posts->get($id);
    // 直接解析原始请求体，避免CakePHP过滤null
    $rawPayload = json_decode($this->request->getBody(), true);
    
    // 检查关联字段是否为null
    if (isset($rawPayload['data']['relationships']['author']['data']) && $rawPayload['data']['relationships']['author']['data'] === null) {
        $post->set('author_id', null);
    } else {
        // 处理正常的关联设置逻辑
        $this->request->allowMethod(['patch', 'post', 'put']);
        $post = $this->Posts->patchEntity($post, $this->request->getData());
    }

    if ($this->Posts->save($post)) {
        // 返回符合JSON:API规范的响应
        $this->set('post', $post);
        $this->viewBuilder()->setOption('serialize', 'post');
    } else {
        $this->response->setStatus(400);
        $this->set('errors', $post->getErrors());
        $this->viewBuilder()->setOption('serialize', 'errors');
    }
}

如果你用的是CakePHP官方的cakephp/json-api插件，可以在资源类的update方法里做类似处理，直接从解析后的JSON:API数据中读取null关联。

有时候问题出在Ember端，默认的JSONAPI序列化器可能没有正确输出data: null。你可以自定义序列化器强制发送这个值：

// app/serializers/application.js
import JSONAPISerializer from '@ember-data/serializer/json-api';

export default class ApplicationSerializer extends JSONAPISerializer {
  serializeRelationships(snapshot, json, relationship) {
    super.serializeRelationships(snapshot, json, relationship);
    const { key } = relationship;
    // 当关联为null时，强制写入data: null
    if (snapshot.belongsTo(key) === null) {
      json.relationships[key] = { data: null };
    }
  }
}

这一步能确保Ember发送的请求体里确实包含null关联的标记，让CakePHP有数据可捕获。

最后要确保你的模型和验证规则允许关联字段为空：
在PostsTable.php里：

public function initialize(array $config): void
{
    parent::initialize($config);
    // 配置belongsTo关联，允许外键为null（注意joinType不要用INNER）
    $this->belongsTo('Authors', [
        'foreignKey' => 'author_id',
        'joinType' => 'LEFT',
    ]);
}

public function validationDefault(Validator $validator): Validator
{
    $validator
        ->integer('author_id')
        ->allowNull('author_id'); // 允许该字段为null

    return $validator;
}

这一步是基础，确保CakePHP在保存时接受null值的外键，不会因为验证规则或者关联配置拒绝保存。

• 不要依赖查询参数来标记移除操作，这不符合JSON:API规范，应该始终通过relationships字段来处理关联更新。
• 检查你的全局请求处理逻辑，避免在AppController里有过滤null值的代码，导致请求数据被提前处理掉。

内容的提问来源于stack exchange，提问作者Hariraman Radhakrishnan