riesenia/persist-related-data

CakePHP ORM plugin for persisting selected fields of related tables

v2.0.0 2025-12-02 20:24 UTC

Requires

• php: >=8.0
• cakephp/orm: ^4.0

Requires (Dev)

• cakephp/cakephp: ^4.0
• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^8.5|^9.3
• rshop/php-cs-fixer-config: ^3.0

MIT

• Tomas Saghy

• orm
• cakephp
• related
• materialize

README

This plugin is for CakePHP 4.x and contains behavior that handles saving selected fields of related data (redundantly).

Installation

Update composer.json file to include this plugin

{
    "require": {
        "riesenia/persist-related-data": "~1.0"
    }
}

Load plugin in config/bootstrap.php

Plugin::load('PersistRelatedData');

Usage

Good example for using this behavior is Invoices model that is related to Contacts. You can provide select box with contacts and save only contact_id when creating new invoice. But when contact data are modified later, your invoice should be left intact.

Example below assumes the invoices table has fields contact_id, contact_name and contact_address, while the contacts table has fields name and address. When you save Invoice entity with provided contact_id, fields contact_name and contact_address will be filled automatically.

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

        // add PersistRelatedData behavior
        $this->addBehavior('PersistRelatedData.PersistRelatedData', [
            'fields' => [
                'contact_name' => 'Contacts.name',
                'contact_address' => 'Contacts.address'
            ]
        ]);

        // associations
        $this->belongsTo('Contacts', [
            'foreignKey' => 'contact_id',
            'className' => 'Contacts'
        ]);
    }
}

Changeable fields

By default, all fields are automatically overwritten with related data when the foreign key changes. If you want to allow manual edits to persisted fields while still populating them automatically when empty, use the changeable configuration option:

$this->addBehavior('PersistRelatedData.PersistRelatedData', [
    'fields' => [
        'contact_name' => 'Contacts.name',
        'contact_address' => 'Contacts.address'
    ],
    'changeable' => [
        'contact_name'  // this field can be manually edited
    ]
]);

With this configuration:

• contact_name will be populated from related data only if it's empty
• contact_address will always be overwritten with related data when the foreign key changes