Add Bidirectional Relationships convenience method (#161)

* Fix Key::resolveParentKey traversal process * add customFormat method to Field class * add Bidirectional trait * Apply Bidirectional trait to Relationship, PostObject, Taxonomy, and User fields * add Bidirectional documentation to README * remove remnant of previous open PR * fix: order traits * chore: update bidirectional comment * chore: sort imports * docs: updated bidirectional * docs: bidirectional * docs: update order --------- Co-authored-by: Vincent Klaiber <[email protected]>
vinkla · Feb 22, 2025 · a910468 · a910468
1 parent fd50308
commit a910468
Show file tree

Hide file tree

Showing 6 changed files with 64 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ Extended ACF provides an object-oriented API to register groups and fields with
   - [Layout](#layout)
 - [Location](#location)
 - [Conditional Logic](#conditional-logic)
+- [Bidirectional Relationships](#bidirectional-relationships)
 - [Non-standards](#non-standards)
     - [`helperText`](#helperText)
     - [`column`](#column)
@@ -680,6 +681,31 @@ Text::make('Sub Title')
     ]),
 ```
 
+## Bidirectional Relationships
+
+The `bidirectional` method establishes a bidirectional relationship between two or more fields. Each field involved in this relationship must use the `key` method to set a custom key. Then, the keys of these related fields should be passed to the `bidirectional` method.
+
+```php
+use Extended\ACF\Fields\Relationship;
+
+// This field is attached to a "Project" post type.
+Relationship::make('Related Testimonial')
+  ->postTypes(['testimonial'])
+  ->key('field_related_testimonial')
+  ->bidirectional('field_related_project'),
+
+// This field is attached to a "Testimonial" post type.
+Relationship::make('Related Project')
+  ->postTypes(['project'])
+  ->key('field_related_project')
+  ->bidirectional('field_related_testimonial'),
+```
+
+To learn more about ACF bidirectional relationships and their caveats, please consult the [official ACF documentation](https://www.advancedcustomfields.com/resources/bidirectional-relationships/).
+
+> [!IMPORTANT]
+We [usually recommend avoiding](#key) the use of custom field keys. This is an exception to that rule. When using bidirectional relationships, you must set custom field keys.
+
 ## Non-standards
 
 ### `helperText`

diff --git a/src/Fields/PostObject.php b/src/Fields/PostObject.php
@@ -13,6 +13,7 @@
 
 namespace Extended\ACF\Fields;
 
+use Extended\ACF\Fields\Settings\Bidirectional;
 use Extended\ACF\Fields\Settings\ConditionalLogic;
 use Extended\ACF\Fields\Settings\FilterBy;
 use Extended\ACF\Fields\Settings\HelperText;
@@ -25,6 +26,7 @@
 class PostObject extends Field
 {
     use ConditionalLogic;
+    use Bidirectional;
     use FilterBy;
     use HelperText;
     use Multiple;

diff --git a/src/Fields/Relationship.php b/src/Fields/Relationship.php
@@ -13,6 +13,7 @@
 
 namespace Extended\ACF\Fields;
 
+use Extended\ACF\Fields\Settings\Bidirectional;
 use Extended\ACF\Fields\Settings\ConditionalLogic;
 use Extended\ACF\Fields\Settings\FilterBy;
 use Extended\ACF\Fields\Settings\HelperText;
@@ -23,6 +24,7 @@
 class Relationship extends Field
 {
     use ConditionalLogic;
+    use Bidirectional;
     use FilterBy;
     use HelperText;
     use Required;

diff --git a/src/Fields/Settings/Bidirectional.php b/src/Fields/Settings/Bidirectional.php
@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * Copyright (c) Vincent Klaiber
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @see https://github.com/vinkla/extended-acf
+ */
+
+declare(strict_types=1);
+
+namespace Extended\ACF\Fields\Settings;
+
+trait Bidirectional
+{
+    /**
+     * Create a bidirectional relationship between two or more fields. This requires setting a custom key for each
+     * related field using the `key` method and passing the keys of those related fields to this method.
+     * @see https://www.advancedcustomfields.com/resources/bidirectional-relationships/
+     */
+    public function bidirectional(array|string $keys): static
+    {
+        $this->settings['bidirectional'] = 1;
+        $this->settings['bidirectional_target'] = is_array($keys) ? $keys : [$keys];
+
+        return $this;
+    }
+}
diff --git a/src/Fields/Taxonomy.php b/src/Fields/Taxonomy.php
@@ -13,6 +13,7 @@
 
 namespace Extended\ACF\Fields;
 
+use Extended\ACF\Fields\Settings\Bidirectional;
 use Extended\ACF\Fields\Settings\ConditionalLogic;
 use Extended\ACF\Fields\Settings\HelperText;
 use Extended\ACF\Fields\Settings\Nullable;
@@ -23,6 +24,7 @@
 class Taxonomy extends Field
 {
     use ConditionalLogic;
+    use Bidirectional;
     use HelperText;
     use Nullable;
     use Required;

diff --git a/src/Fields/User.php b/src/Fields/User.php
@@ -13,6 +13,7 @@
 
 namespace Extended\ACF\Fields;
 
+use Extended\ACF\Fields\Settings\Bidirectional;
 use Extended\ACF\Fields\Settings\ConditionalLogic;
 use Extended\ACF\Fields\Settings\HelperText;
 use Extended\ACF\Fields\Settings\Multiple;
@@ -24,6 +25,7 @@
 class User extends Field
 {
     use ConditionalLogic;
+    use Bidirectional;
     use HelperText;
     use Multiple;
     use Nullable;