Add documentation and interface for marshalling behaviors.

- Fix rebase mistake.
- Add missing docs
- Add interface.

src/ORM/Behavior/TranslateBehavior.php

@@ -22,6 +22,7 @@
 use Cake\ORM\Behavior;
 use Cake\ORM\Entity;
 use Cake\ORM\Locator\LocatorAwareTrait;
+use Cake\ORM\MarshalParticipantInterface;
 use Cake\ORM\Query;
 use Cake\ORM\Table;
 use Cake\Utility\Inflector;
@@ -38,7 +39,7 @@
  * If you want to bring all or certain languages for each of the fetched records,
  * you can use the custom `translations` finders that is exposed to the table.
  */
-class TranslateBehavior extends Behavior
+class TranslateBehavior extends Behavior implements MarshalParticipantInterface
 {
 
     use LocatorAwareTrait;
@@ -327,7 +328,14 @@ public function afterSave(Event $event, EntityInterface $entity)
         $entity->unsetProperty('_i18n');
     }
 
-    public function marshalPropertyMap($marshaller, $map, $options)
+    /**
+     * Add in _translations marshalling handlers if translation marshalling is
+     * enabled. You need to specifically enable translation marshalling by adding
+     * `'translations' => true` to the options provided to `Table::newEntity()` or `Table::patchEntity()`.
+     *
+     * {@inheritDoc}
+     */
+    public function buildMarhshalMap($marshaller, $map, $options)
     {
         if (isset($options['translations']) && !$options['translations']) {
             return [];

src/ORM/MarshalParticipantInterface.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
+ * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * For full copyright and license information, please see the LICENSE.txt
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ * @link          http://cakephp.org CakePHP(tm) Project
+ * @since         3.4.0
+ * @license       http://www.opensource.org/licenses/mit-license.php MIT License
+ */
+namespace Cake\ORM;
+
+/**
+ * Behaviors implementing this interface can participate in entity marshalling.
+ *
+ * This enables behaviors to define behavior for how the properties they provide/manage
+ * should be marshalled.
+ */
+interface MarshalParticipantInterface
+{
+    /**
+     * Build a set of properties that should be included in the marshalling process.
+     *
+     * @param \Cake\ORM\Marhshaller $marshaller The marhshaller of the table the behavior is attached to.
+     * @param array $map The property map being built.
+     * @param array $options The options array used in the marshalling call.
+     * @return array A map of `[property => callable]` of additional properties to marshal.
+     */
+    public function buildMarhshalMap($marshaller, $map, $options);
+}

src/ORM/Marshaller.php

@@ -20,6 +20,7 @@
 use Cake\Database\Type;
 use Cake\Datasource\EntityInterface;
 use Cake\Datasource\InvalidPropertyInterface;
+use Cake\ORM\MarshalParticipantInterface;
 use RuntimeException;
 
 /**
@@ -88,7 +89,7 @@ protected function _buildPropertyMap($data, $options)
             $assoc = $this->_table->association($key);
             // If the key is not a special field like _ids or _joinData
             // it is a missing association that we should error on.
-            if (!$assoc)
+            if (!$assoc) {
                 if (substr($key, 0, 1) !== '_') {
                     throw new \InvalidArgumentException(sprintf(
                         'Cannot marshal data for "%s" association. It is not associated with "%s".',
@@ -117,9 +118,8 @@ protected function _buildPropertyMap($data, $options)
         $behaviors = $this->_table->behaviors();
         foreach ($behaviors->loaded() as $name) {
             $behavior = $behaviors->get($name);
-            // TODO use an interface here.
-            if (method_exists($behavior, 'marshalPropertyMap')) {
-                $map = $behavior->marshalPropertyMap($this, $map, $options);
+            if ($behavior instanceof MarshalParticipantInterface) {
+                $map = $behavior->buildMarhshalMap($this, $map, $options);
             }
         }