APIv4: Automatically add 'OR IS NULL' to 'NOT CONTAINS'

[aydun]

Overview

In APIv4 'NOT CONTAINS', automatically add a 'OR IS NULL' since we just want to know that a particular value is not present but don't care whether the field has any other value or is empty.

Before

1. On standard sample data, for one contact, set "Most Important Issue" to "Education" and on another contact set "Environment"
2. Create a SearchKit on Contacts with a WHERE of Constituent Information:Most Important Issue Contains Education
3. Confirm results include those in 1.
4. Change to Doesn't Contain
5. Note only the contact with "Environment" is shown - not all the other records with no value set for "Most Important Issue"

After

All contacts without 'Education' as the 'Most Important Issue' are returned.

Technical Details

Not sure whether there is a better way to implement this.

Comments

This can be worked around in SK by adding an 'OR' group with 'IS EMPTY' but this is cumbersome.

[civibot]

🤖 Thank you for contributing to CiviCRM! ❤️ We will need to test and review this PR. 👷

Introduction for new contributors...

• If this is your first PR, an admin will greenlight automated testing with the command ok to test or add to whitelist.
• A series of tests will automatically run. You can see the results at the bottom of this page (if there are any problems, it will include a link to see what went wrong).
• A demo site will be built where anyone can try out a version of CiviCRM that includes your changes.
• If this process needs to be repeated, an admin will issue the command test this please to rerun tests and build a new demo site.
• Before this PR can be merged, it needs to be reviewed. Please keep in mind that reviewers are volunteers, and their response time can vary from a few hours to a few weeks depending on their availability and their knowledge of this particular part of CiviCRM.
• A great way to speed up this process is to "trade reviews" with someone - find an open PR that you feel able to review, and leave a comment like "I'm reviewing this now, could you please review mine?" (include a link to yours). You don't have to wait for a response to get started (and you don't have to stop at one!) the more you review, the faster this process goes for everyone 😄
• To ensure that you are credited properly in the final release notes, please add yourself to contributor-key.yml
• For more information about contributing, see CONTRIBUTING.md.

Quick links for reviewers...

• ➡️ PR Demo site (can be rebuilt with the command test this please).
• 📖 Review standards
• 🗒️ Review template (brief or verbose)

➡️ Online demo of this PR 🔗

[colemanw]

I'm not sure we need to go with the full IS EMPTY here (which expands into a compound expression like field = "" OR field IS NULL) because if the field is already a string then the NOT CONTAINS ought to cover it, so we just need the IS NULL bit.

[aydun]

Ok ... updated

[colemanw]

@aydun this looks good. Probably a unit test could be added around here:

civicrm-core/tests/phpunit/api/v4/Action/ContactGetTest.php

Line 141 in 6dd43f0

public function testEmptyAndNullOperators(): void {

or here:

civicrm-core/tests/phpunit/api/v4/Action/ContactGetTest.php

Line 203 in 6dd43f0

public function testRegexpOperators(): void {

[aydun]

@colemanw Thanks - tests added