APIv4 - Add shorthand for setCheckPermissions()

[colemanw]

Overview

This adds a much-requested shorthand for setting $checkPermissions in APIv4.

• For api consumers, the change is backward compatible and does not require any updates to your code.
• As with any API changes, any extensions taking advantage of the shorter syntax will need to update their core version dependency (in this case to 5.29).
• For api authors, you will need to update the factory functions in any api classes that extend AbstractAction, BasicAction or DAOAction. Until you do so, a php warning will be generated about function signatures not matching.

Before

\Civi\Api4\Contact::get()
  ->setCheckPermissions(FALSE)
  ->execute();

After

\Civi\Api4\Contact::get(FALSE)
  ->execute();

Technical Details

This required updating every API factory method, so it's a big PR.

It's also going to generate on-screen PHP warnings for any extensions with built-from-scratch APIs (of which there are very few in existence and most if not all of them were written by me) until those function signatures get updated. I can take care of that shortly after this PR gets accepted. Extensions with regular DAO-based APIv4 entities are not affected if they just inherit all their factory functions from the base class.

Comments

Also updated the API Explorer:

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[seamuslee001]

Jenkins re test this please

[seamuslee001]

This looks good to me @eileenmcnaughton

[eileenmcnaughton]

I think we can still get away with making this change in that custom v4 apis haven't taken off and it helps usability a lot - but we need to think about communications around it - ie. email dev-list? release notes (@agh1 ) docs updates & change log

[colemanw]

@eileenmcnaughton I've submitted https://lab.civicrm.org/extensions/api4example/-/merge_requests/1 and also updated the dev docs to prominently point to those examples. I can also send out an email once this is merged.

[eileenmcnaughton]

@colemanw so it's still not clear to me what has changed from a consumer POV - what will break & how

[eileenmcnaughton]

@colemanw so for example will this api break? https://github.com/eileenmcnaughton/civi-data-translate/blob/master/Civi/Api4/Action/Message/Render.php

[colemanw]

@eileenmcnaughton it's not going to break, just generate some annoying PHP warnings because the base class function takes 1 param ($checkPermissions) and your overridden class does not until you merge my PR.

I'm trying this out now with the patched Example extension + unpatched civicrm master, and PHP is fine with it. So warnings get generated if core is updated before extensions, but no warnings if extensions are updated before core.

So I can put out a dev email now asking extension maintainers to update any ad-hoc v4 APIs now & release before september 5th (which is when this will be released in core if we merge it now).

[eileenmcnaughton]

@colemanw my inclination is to send the email out now & merge on Monday. I'm just not comfortable that we will have thought through all the implications of this. ( this is a breaking change although the case is that the impact of the breakage is minimal).

I think some screenshots of the warnings would help

[colemanw]

@eileenmcnaughton actually now I'm not able to get php to generate any warnings from the example extension or from your extension. The only warnings I can generate is one from the contactLayout extension because it overrides a dao action. That's pretty unusual for an api; I really don't think this is going to affect much of anyone but I'll send out a notice to the dev list anyway.

[eileenmcnaughton]

@colemanw ah that makes sense - OK happy to merge this then but yes do email the list