Document table structure filter

changelog.md

@@ -1,7 +1,11 @@
 Changelog
 =========
 
-* 2.2.12 (2025-)
+* 2.2.13 (2025-)
+	* Plugin status: Plugin status: as before, this plugin doesn't currently have official maintainers. I try to check in occasionally if anyone submits pull requests or major issues and merge/address them if I can do so rather quickly. Updates will be given within the plugin if/when that status changes.
+	* Developers: Thanks to @phschmanau for adding the `object_sync_for_salesforce_wordpress_table_structure` filter, which allows plugins to override or extend the database table structure, and the methods to work with it, of any mapped WordPress object with their own structures. See [the documentation](https://github.com/MinnPost/object-sync-for-salesforce/blob/master/docs/extending-mapping-options.md#wordpress-object-database-table-structure) for how to use it.
+
+* 2.2.12 (2025-08-03)
 	* Plugin status: Plugin status: as before, this plugin doesn't currently have official maintainers. I try to check in occasionally if anyone submits pull requests or major issues and merge/address them if I can do so rather quickly. Updates will be given within the plugin if/when that status changes.
 	* Bug fix: Fix warning triggered in WordPress 6.7 and newer due to translation functions being called too early in the plugin lifecycle. Thanks to GitHub user @alessandrocarrera for the report and @richaber for additional context.
 	* Bug fix: Check for createable attribute on Salesforce fields so that the mapping enables operations where there are createable fields but not updateable ones. Thanks to GitHub user @jose-dvm for the report.

docs/all-developer-hooks.md

@@ -120,6 +120,10 @@ This page lists all developer hooks available in this plugin, with links to wher
     - description: allow plugins to add filename or parent data when creating attachment objects.
     - code: [classes/class-object-sync-sf-wordpress.php](../classes/class-object-sync-sf-wordpress.php)
     - documentation: [extending wordpress](./extending-wordpress.md#for-attachments)
+- `object_sync_for_salesforce_wordpress_table_structure`:
+    - description: when getting the database table structure for any WordPress object, allow plugins to override or extend it, as well as the methods used to work with it, with their own.
+    - code: [classes/class-object-sync-sf-wordpress.php](../classes/class-object-sync-sf-wordpress.php)
+    - documentation: [extending mapping options](./extending-mapping-options.md#wordpress-object-database-table-structure)
 - `object_sync_for_salesforce_wordpress_object_fields`:
     - description: when getting the fields for a WordPress object, allow plugins to add more (and also cache the array).
     - code: [classes/class-object-sync-sf-wordpress.php](../classes/class-object-sync-sf-wordpress.php)

docs/extending-mapping-options.md

@@ -30,6 +30,65 @@ function remove_types( $types_to_remove ) {
 
 In the above examples, an object called `foo` would be added to the dropdown, and an existing object called `acme_product` would be removed.
 
+## WordPress object database table structure
+
+The `object_sync_for_salesforce_wordpress_table_structure` hook populates an array of the database structure, as well as the methods used to work with it, of any WordPress object type, and allows plugins to modify any of these.
+
+Example of `$object_table_structure` array:
+
+```php
+$user_meta_methods = array(
+    'create' => 'update_user_meta',
+    'read'   => 'get_user_meta',
+    'update' => 'update_user_meta',
+    'delete' => 'delete_user_meta',
+);
+
+$object_table_structure = array(
+    'object_name'     => 'user',
+    'content_methods' => array(
+        'create' => 'wp_insert_user',
+        'read'   => 'get_user_by',
+        'update' => 'wp_update_user',
+        'delete' => 'wp_delete_user',
+        'match'  => 'get_user_by',
+    ),
+    'meta_methods'    => $user_meta_methods,
+    'content_table'   => $this->wpdb->prefix . 'users',
+    'id_field'        => 'ID',
+    'meta_table'      => $this->wpdb->prefix . 'usermeta',
+    'meta_join_field' => 'user_id',
+    'where'           => '',
+    'ignore_keys'     => array( // Keep it simple and avoid security risks.
+        'user_pass',
+        'user_activation_key',
+        'session_tokens',
+    ),
+);
+// Check for Multisite installation. Sitewide User table uses base site prefix across all sites.
+if ( is_multisite() ) {
+    $object_table_structure['content_table'] = $this->wpdb->base_prefix . 'users';
+    $object_table_structure['meta_table']    = $this->wpdb->base_prefix . 'usermeta';
+}
+```
+
+To modify the array, you can use the `object_sync_for_salesforce_wordpress_table_structure` hook.
+
+Code example:
+
+```php
+add_filter( 'object_sync_for_salesforce_wordpress_table_structure', 'object_table_structure', 10, 2 );
+function add_field( $object_table_structure, $wordpress_object_type ) {
+    if ( 'user' === $object_table_structure ) {
+        $object_table_structure['id_field']      = 'my_custom_id_field';
+        $object_table_structure['content_table'] = 'my_custom_table';
+    }
+    return $object_table_structure;
+}
+```
+
+By default, this plugin tries to use the built in WordPress table structure, and methods for retrieving and modifying data, for any built in data patterns. But given enough work, this hook should support any other structure and method an object might need.
+
 ## Available WordPress fields
 
 The `object_sync_for_salesforce_wordpress_object_fields` hook populates an array of fields for a given object, which is then added to the list in the dropdown. This array is also used in several other parts of the plugin, so its structure is more complex.

docs/initial-setup.md

@@ -8,8 +8,8 @@ To install the plugin in WordPress, your PHP environment needs the following:
 
 #### To run the plugin on a website
 
-1. At least version 5.6.20 of PHP.
-2. At least version 5.2 of WordPress.
+1. At least version 7.2 of PHP.
+2. At least version 6.5 of WordPress.
 3. SSL support (this is required to connect to Salesforce). Contact your web host if you aren't sure if your website meets this requirement.
 4. If you'll be using the SOAP API, PHP needs to be compiled with SOAP web services and
   OpenSSL support, as per: