CakePHP 4 多文件上传：避免表单字段与关联属性名称冲突

// Articles/edit.php
echo $this->Form->control('pieces_jointes', ['type' => 'file', 'multiple' => true, 'name' => 'pieces_jointes[]']);

// Articles/edit.php 或 Articles/add.php
echo $this->Form->create($article, ['type' => 'file']);
echo $this->Form->control('title', /*[...]*/);
echo $this->Form->control('body', /*[...]*/);
// 将文件上传字段名称修改为 'new_attachments'
echo $this->Form->control('new_attachments', ['type' => 'file', 'multiple' => true, 'name' => 'new_attachments[]']);

// src/Model/Behavior/AttachmentBehavior.php
namespace App\Model\Behavior;

use Cake\Datasource\EntityInterface;
use Cake\Event\EventInterface;
use Cake\ORM\Behavior;
use Cake\ORM\Table;
use Laminas\Diactoros\UploadedFile;

class AttachmentBehavior extends Behavior
{
    // 默认配置，可根据需要调整
    protected $_defaultConfig = [
        'uploadField' => 'new_attachments', // 表单中上传字段的名称
        'association' => 'PiecesJointes',   // 对应的 hasMany 关联名称
        'path' => WWW_ROOT . 'uploads' . DS, // 文件存储的根路径
        'fileModel' => 'FileManager.Attachments', // 关联的文件模型
        'foreignKey' => 'article_id', // 关联的外键
    ];

    /**
     * 初始化行为，确保关联已定义
     * @param array $config 配置数组
     */
    public function initialize(array $config): void
    {
        parent::initialize($config);
        $associationName = $this->getConfig('association');
        $fileModel = $this->getConfig('fileModel');
        $foreignKey = $this->getConfig('foreignKey');

        // 如果主表尚未定义此关联，则定义它
        if (!$this->_table->hasAssociation($associationName)) {
            $this->_table->hasMany($associationName, [
                'className' => $fileModel,
                'foreignKey' => $foreignKey,
                'dependent' => true, // 如果主实体被删除，关联文件也随之删除
            ]);
        }
    }

    /**
     * 在数据被封送（marshal）到实体之前处理上传文件
     * 这是在 patchEntity() 之前拦截和转换请求数据的理想位置
     * @param \Cake\Event\EventInterface $event 事件对象
     * @param \ArrayObject $data 待处理的请求数据
     * @param \ArrayObject $options 选项
     */
    public function beforeMarshal(EventInterface $event, \ArrayObject $data, \ArrayObject $options)
    {
        $uploadFieldName = $this->getConfig('uploadField');
        $associationName = $this->getConfig('association');

        // 检查是否存在新的上传文件数据
        if (isset($data[$uploadFieldName]) && is_array($data[$uploadFieldName])) {
            $newAttachmentsData = [];
            foreach ($data[$uploadFieldName] as $file) {
                // 确保是有效的UploadedFile对象且没有上传错误
                if ($file instanceof UploadedFile && $file->getError() === UPLOAD_ERR_OK) {
                    // 处理文件上传：移动文件，并获取文件信息
                    $attachmentInfo = $this->processUpload($file);
                    if ($attachmentInfo) {
                        $newAttachmentsData[] = $attachmentInfo;
                    }
                }
            }

            // 如果有新的附件数据，将其合并到关联属性中
            if (!empty($newAttachmentsData)) {
                // 如果关联属性已存在数据（例如，编辑时已有的附件），则合并
                if (isset($data[$associationName]) && is_array($data[$associationName])) {
                    $data[$associationName] = array_merge($data[$associationName], $newAttachmentsData);
                } else {
                    $data[$associationName] = $newAttachmentsData;
                }
            }
            // 移除原始的上传字段数据，避免 patchEntity 再次处理它
            unset($data[$uploadFieldName]);
        }
    }

    /**
     * 处理单个文件上传：移动文件并返回其元数据
     * @param \Laminas\Diactoros\UploadedFile $file 上传文件对象
     * @return array|null 包含文件元数据的数组，或 null（如果处理失败）
     */
    protected function processUpload(UploadedFile $file): ?array
    {
        $targetPath = $this->getConfig('path');
        // 确保目标目录存在
        if (!is_dir($targetPath)) {
            mkdir($targetPath, 0775, true);
        }

        // 生成唯一文件名，防止冲突
        $filename = uniqid('file_') . '_' . $file->getClientFilename();
        $destination = $targetPath . $filename;

        try {
            $file->moveTo($destination);
            return [
                'filename' => $file->getClientFilename(),
                'filepath' => 'uploads/' . $filename, // 存储相对路径
                'mimetype' => $file->getClientMediaType(),
                'size' => $file->getSize(),
                // ... 其他你希望保存的文件信息
            ];
        } catch (\Exception $e) {
            // 记录错误或抛出异常
            $this->log('文件上传失败: ' . $e->getMessage(), 'error');
            return null;
        }
    }

    // 您还可以添加 afterSave 方法来清理临时文件或执行其他操作
}

// src/Model/Table/ArticlesTable.php
namespace App\Model\Table;

use Cake\ORM\Table;
use Cake\Validation\Validator;

class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        parent::initialize($config);

        $this->setTable('articles');
        $this->setDisplayField('title');
        $this->setPrimaryKey('id');

        $this->addBehavior('Timestamp');
        // 加载并配置 AttachmentBehavior
        $this->addBehavior('Attachment', [
            'uploadField' => 'new_attachments', // 对应表单中的字段名
            'association' => 'PiecesJointes',   // 对应的 hasMany 关联名
            'path' => WWW_ROOT . 'uploads' . DS, // 文件存储路径
            'fileModel' => 'FileManager.Attachments', // 如果附件有单独的模型
            'foreignKey' => 'article_id', // 外键
        ]);

        // 定义 hasMany 关联
        $this->hasMany('PiecesJointes', [
            'className' => 'FileManager.Attachments', // 确保这个模型存在
            'foreignKey' => 'article_id',
            'dependent' => true,
        ]);
    }

    public function validationDefault(Validator $validator): Validator
    {
        $validator
            ->requirePresence('title', 'create')
            ->notEmptyString('title');

        $validator
            ->allowEmptyString('body');

        // 对于文件上传字段，通常不需要直接在验证器中验证，因为行为会处理
        // 如果需要验证文件类型或大小，可以在行为中或自定义验证规则中实现
        return $validator;
    }
}

// src/Controller/ArticlesController.php
namespace App\Controller;

use App\Controller\AppController;
use Cake\Http\Exception\NotFoundException;

class ArticlesController extends AppController
{
    public function edit($id = null)
    {
        try {
            $article = $this->Articles->findById($id)
                                      ->contain(['PiecesJointes']) // 包含现有附件
                                      ->firstOrFail();
        } catch (NotFoundException $e) {
            $this->Flash->error(__('文章未找到。'));
            return $this->redirect(['action' => 'index']);
        }

        if ($this->request->is(['post', 'put'])) {
            // patchEntity 会触发 AttachmentBehavior 的 beforeMarshal 方法
            // 该方法会处理 'new_attachments' 并将其数据