Docs for XML vs JSON requests (#1044)

Author: thomascorthals

README.md

@@ -53,6 +53,26 @@ setlocale(LC_NUMERIC, $currentLocale);
 PHP 8.0 has made the float to string conversion locale-independent and will always use the `.` decimal separator.
 The workaround is no longer necessary with PHP versions ≥ 8.0.
 
+### Future pitfall when upgrading to 7.x
+
+Solarium 7 will change the default request format for update queries from XML to JSON.
+
+You can already test your code with JSON requests to ensure a seamless transition.
+
+```php
+// get an update query instance
+$update = $client->createUpdate();
+
+// set JSON request format
+$update->setRequestFormat($update::REQUEST_FORMAT_JSON);
+```
+
+If you do require XML specific functionality, set the request format to XML explicitly instead to avoid issues when upgrading.
+
+```php
+$update->setRequestFormat($update::REQUEST_FORMAT_XML);
+```
+
 ### Pitfalls when upgrading from 3.x or 4.x or 5.x
 
 #### Setting a timeout

docs/documents.md

@@ -223,16 +223,28 @@ $doc->reaction = $reaction;
 $doc->setField('reaction', $reaction);
 ```
 
-**Note:** Solarium can't index this single nested child correctly at the moment. For more info see [known limitations](#known-limitations).
+**Note:** You have to use the JSON request format to index a labelled single nested child document. For more info see [known limitations](#known-limitations).
 
 #### Anonymous children
 
 If you use `_childDocuments_` as the field name, the child documents are indexed anonymously. This is not recommended by Solr.
 
 #### Known limitations
 
-- It's currently impossible to index a labelled single nested child document with Solarium because of [SOLR-16183](https://issues.apache.org/jira/browse/SOLR-16183). Any child document you index this way will end up as an anonymous nested child.
-- Atomic updates of child documents aren't fully supported in Solarium because of [SOLR-12677](https://issues.apache.org/jira/browse/SOLR-12677).
+Some child document functionality isn't supported by XML formatted update requests.
+
+- It's impossible to index a labelled single nested child document because of [SOLR-16183](https://issues.apache.org/jira/browse/SOLR-16183). Any child document you index this way will end up as an anonymous nested child.
+- Atomic updates of child documents aren't fully supported because of [SOLR-12677](https://issues.apache.org/jira/browse/SOLR-12677).
+
+Make sure to set the request format to JSON if you require this functionality.
+
+```php
+// get an update query instance
+$update = $client->createUpdate();
+
+// set JSON request format
+$update->setRequestFormat($update::REQUEST_FORMAT_JSON);
+```
 
 ### Atomic updates
 
@@ -330,7 +342,7 @@ The document has `getVersion` and `setVersion` methods. By default no version is
 
 But you can also set a custom version (specific ID).
 
-For more info on versioning please see this blogpost: <http://yonik.com/solr/optimistic-concurrency/>
+For more info on versioning please see this blogpost: <https://yonik.com/solr/optimistic-concurrency/>.
 
 ### Boosts
 
@@ -340,6 +352,7 @@ You can set the document boost with the `setBoost` method.
 
 Field boosts can be set with the `setFieldBoost` method, or with optional parameters of the `setField` and `addField` methods. See the API docs for details.
 
+Index-time boosts have been removed from Solr 7 and will be ignored. Even with older Solr versions, they aren't supported by JSON formatted update requests.
 
 Custom document
 ---------------

docs/queries/update-query/best-practices-for-updates.md

@@ -28,6 +28,10 @@ If you need to use rollbacks (outside of testing) that usually indicates there i
 
 While 'optimizing' sounds like it's always a good thing to do, you should use it with care, as it can have a negative performance impact *during the optimize process*. If possible use try to use it outside peak hours / at intervals.
 
+### XML vs JSON formatted update requests
+
+Solarium issues XML formatted update requests by default. This will change to JSON format when Solarium 7 is released. You can set this to JSON if you want to test your code in advance. If you require XML specific functionality, you should already set this to XML explicitly to ensure a seamless transition.
+
 ### Raw XML update commands
 
 Solarium makes it easy to build update commands without having to know the underlying XML structure. If you already have XML formatted update commands, you can add them directly to an update query. Make sure they are valid as Solarium will not check this.

docs/queries/update-query/building-an-update-query/building-an-update-query.md

@@ -10,7 +10,7 @@ However, if you do need to customize them for a special case, you can.
 
 ### RequestFormat
 
-Solarium sends XML formatted update requests by default. You can change this to JSON formatted requests.
+Solarium issues XML formatted update requests by default. This will change to JSON format when Solarium 7 is released. You can set this to JSON if you want to test your code in advance. If you require XML specific functionality, you should already set this to XML explicitly to ensure a seamless transition.
 
 ### ResultClass
 

docs/queries/update-query/building-an-update-query/rawxml-command.md

@@ -2,6 +2,8 @@ You can use this command to add XML formatted update commands to an update query
 
 Make sure the XML is valid as Solarium will not check this. If you are constructing these strings in your own code, you should probably be using the other commands Solarium provides to build your update query.
 
+This command can only be used with the XML request format.
+
 Options
 -------
 
@@ -22,6 +24,9 @@ $client = new Solarium\Client($adapter, $eventDispatcher, $config);
 // get an update query instance
 $update = $client->createUpdate();
 
+// set XML request format
+$update->setRequestFormat($update::REQUEST_FORMAT_XML);
+
 // create an XML string with a valid update command
 $xml = '
 <add>

docs/queries/update-query/update-query.md

@@ -1,7 +1,7 @@
 Update queries allow you to add, delete, commit, optimize and rollback commands. For all the details about the Solr update handler please see the Solr documentation, but some important notes:
 
 -   Solr has no 'update' command. But if you add a document with a value for the 'unique key' field that already exists in the index that existing document will be overwritten by your new document.
--   You can only add complete documents. If you want to update only a single field you still need to 'add' the whole document.
+-   If you want to update only a single field you either need to 'add' the whole document or use atomic updates if your schema is configured to support this.
 -   Always use a database or other persistent storage as the source for building documents to add. Don't be tempted to emulate an update command by selecting a document, altering it and adding it. Almost all schemas will have fields that are indexed and not stored. You will lose the data in those fields.
 -   The best way to use update queries is also related to your Solr config. If you are for instance using the autocommit feature of Solr you probably don't want to use a commit command in your update queries. Make sure you know the configuration details of the Solr core you use.
-
+-   Some functionality is only available with XML formatted or JSON formatted update queries, but not both. Set the appropriate request format if necessary.

examples/2.2.6-rawxml.php

@@ -9,6 +9,9 @@
 // get an update query instance
 $update = $client->createUpdate();
 
+// set XML request format
+$update->setRequestFormat($update::REQUEST_FORMAT_XML);
+
 // create an XML string with a valid update command
 $xml = '
 <add>