Documentation

Not recommended for new code but ok for existing code to continue using.

Calling civicrm_api() is functionally identical to civicrm_api3() or civicrm_api4() except:

1. It requires $params['version'].
2. It catches exceptions and returns an array like ['is_error' => 1, 'error_message' => ...]. This is disfavored for typical business-logic/hooks/forms/etc. However, if an existing caller handles civicrm_api()-style errors, then there is no functional benefit to reworking it.

api notice

• use the getoptions action instead

use the OptionValue api instead

use OptionValue api

api notice

Update a specified case. Use civicrm_api3_case_create() instead.

api notice

as of CiviCRM 4.4. It's recommended to use the api getoptions action instead

• this should be part of create but need to know we aren't missing something

api notice

api notice

it is highly unlikely this function is ever used because to use it someone needs to forward an email by clicking on a link rather than.. forwarding the email. Even the links are probably never generated.

Also - it would be poor email server reputation management. Function is nasty but can die with apiv4 whenever that is (along with surveyRespondant)

api notice

• should just use create

• calling this function directly is deprecated as 'set' is not a clear action use submit

• appears to be an internal function - should not be accessible via api Provide formatted values for profile fields.

api notice

api notice

• api currently not supported

• api currently not supported

DAO based retrieval is being phased out.

• DAO based retrieval is being phased out.

function.

This function has probably been defunct for quite a long time.

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

APIv3 only.

Given an entity which dynamically attaches itself to another entity, determine if one has permission to the other entity.

Example: Suppose one tries to manipulate a File which is attached to a Mailing. DynamicFKAuthorization will enforce permissions on the File by imitating the permissions of the Mailing.

Note: This enforces a constraint: all matching API calls must define "id" (e.g. for the file) or "entity_table+entity_id" or "field_name+entity_id".

Note: The permission guard does not exactly authorize the request, but it may veto authorization.

Just use the string instead of the constant when listening for this event

since 5.71 will be removed around 5.81

• You may simply use the event name directly. dev/core#1744

Not supported by some locking strategies. If you need to poll, better to use acquire(0).

Not supported by some locking strategies. If you need to poll, better to use acquire(0).

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

• You may simply use the event name directly. dev/core#1744

Unused - non-compliant namespace -see https://github.com/civicrm/civicrm-core/pull/25634

It is not recommended that new things depend on the group-name. However, the plumbing still passes-through the group-name.

• this bypasses hooks.

• this bypasses hooks.

Fetch object based on array of properties.

since 5.71.

This function has no core usage. There is some non-core usage. At some point we should add a suitable api & noisily deprecate this / set an tentative removal date.

• use the api instead.

Get the Activities of a target contact.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• do not add new settings here - the page to display settings on should be defined in the setting metadata.

• this bypasses hooks.

• this bypasses hooks.

since 5.71 will be removed around 5.85.

• this bypasses hooks.

use getCampaignID()

since 5.71 will be removed around 5.77

since 5.71 will be removed around 5.77

since 5.71 will be removed around 5.77

since 5.71 will be removed around 5.77

since 5.71 will be removed around 5.77

since 5.71 will be removed around 5.77

This is inconsistently set & likely to be replaced by a local variable or getter.

since 5.74 will be removed around 5.80

This is called from a few places but creates rather than solves complexity.

avoid this function, no planned removed at this stage as there are still core callers.

• this bypasses hooks.

Create a new group.

• this bypasses hooks.

since 5.71 - will be removed after all core usages are fully removed.

since 5.68. Will be removed around 5.74.

Only-used-by-user-dashboard.

since 5.68. Will be removed around 5.74.

Only-used-by-user-dashboard.

• this bypasses hooks.

see https://github.com/civicrm/civicrm-core/pull/29241 for preferred approach - basically

1. at the tpl layer use CRM/common/customDataBlock.tpl
2. to make the fields available for postProcess if ($this->isSubmitted()) { $this->addCustomDataFieldsToForm('FinancialAccount'); }
3. pass getSubmittedValues() to CRM_Core_BAO_CustomField::postProcess($this->getSubmittedValues(), $this->_id, 'FinancialAccount'); to ensure any money or number fields are handled for localisation

since 5.73 will be removed around 5.85

since 5.73 will be removed around 5.85

since 5.73 will be removed around 5.85

since 5.73 will be removed around 5.85

in CiviCRM 5.66, will be removed around CiviCRM 5.76.

in CiviCRM 5.66, will be removed around CiviCRM 5.76.

since 5.78 will be removed around 5.84

since 5.59 will be removed around 5.89.

since 5.71 will be removed around 5.77.

since 5.71 will be removed around 5.77.

since 5.71 will be removed around 5.77.

since 5.71 will be removed around 5.77.

since 5.69 will be removed around 5.75

since 5.69 will be removed around 5.75

since 5.69 will be removed around 5.75

will be removed around 5.75

since 5.69 will be removed around 5.75

For single creates use the api instead (it's tested). For multiple a new variant of this function needs to be written and migrated to as this is a bit nasty

since 5.68. Will be removed around 5.74.

Only-used-by-user-dashboard.

since 5.68. Will be removed around 5.74.

Only-used-by-user-dashboard.

This is called from a couple of places outside of core so it has been made unused and deprecated rather than having the now-obsolete parameter change. It should work much the same for the places that call it with a notice. It is not an api function & not supported for use outside core. Extensions should write their own functions.

since 5.72 will be removed around 5.90

since 5.75 will be removed around 5.99. Note some universe usages exist but may be in unused extensions.

since well before 5.75 will be removed around 5.99. Note some universe usages exist but may be in unused extensions.

Note that in theory it should be possible to retrieve these from the line_item table with the membership_payment table being deprecated. Attempting to do this here causes tests to fail as it seems the api is not correctly linking the line items when the contribution is created in the flow where the contribution is created in the API, followed by the membership (using the api) followed by the membership payment. The membership payment BAO does have code to address this but it doesn't appear to be working.

I don't know if it never worked or broke as a result of https://issues.civicrm.org/jira/browse/CRM-14918.

since 5.68 will be removed around 5.74.

since 5.75 will be removed around 5.99.

• this bypasses hooks.

assigning values to smarty like this is risky because

• it is hard to debug since $name is used in the assign
• it is potentially 'leaky' - it's better to do this on the form or close to where it is used / required. See CRM-17519 for leakage e.g.

since 5.76 will be removed around 5.90. Non-core users should all use the api.

since 5.76 will be removed around 5.96. Non-core users should all use the api. As of writing there are some core users.

use the api.

• this bypasses hooks.

since 5.69 will be removed around 5.75

since 5.68 will be removed around 5.78.

since 5.69 will be removed around 5.75

• use parent $this->contactID

use getContributionID()

• we are ditching this approach in favour of 'full form flow' = ie simulating postProcess.

unused

since 5.68 will be removed around 5.80.

Try something like use use \Civi\Test\FormTrait; $form = $this->getTestForm('CRM_Contribute_Form_Contribution', $submittedValues, [ 'id' => 4; 'action' => 'update', ]); $form->processForm();

use $this->isSeparateMembershipPayment() function.

• this bypasses hooks.

• just call the BAO / api directly.

This method was historically used to access civicrm_domain.config_backend. However, that has been fully replaced by the settings system since v4.7.

This method was historically used to access civicrm_domain.config_backend. However, that has been fully replaced by the settings system since v4.7.

• this bypasses hooks.

since 5.71

Use the API OptionGroup.get

Old function with weirdly ambiguous logic. Only used by APIv3. Use at your peril.

Old function only used by APIv3.

• this bypasses hooks.

since 5.71 will be removed around 5.85.

Function moved

Function demonstrates just how bad code can get from 20 years of entropy.

This function takes an overcomplicated set of params and returns an overcomplicated mix of custom groups, custom fields, custom values (if passed $entityID), and other random stuff.

only used by legacy function.

only used by legacy functions.

Legacy function

Legacy function

since 5.71, will be removed around 5.85

since 5.71 will be removed around 5.85

since 5.71 will be removed around 5.85

since 5.71 will be removed around 5.85

since 5.71 will be remvoed around 5.77

Silly function that does almost nothing.

Silly function that shouldn't exist.

as of 5.72 use getExtendsEntityColumnValueOptions - will be removed by 5.78

WARNING: Nonstandard params searches by tag_id rather than id!

This function basically calls CRM_Contribute_BAO_Contribution::getContributionBalance

• just do that. If need be we could have a fn to get the contribution id but chances are the calling functions already know it anyway.

use Apiv4.

• this bypasses hooks.

• this bypasses hooks.

since 5.72 will be removed around 5.82

to be removed.

since 5.71 will be removed around 5.85.

• this bypasses hooks.

• this bypasses hooks.

• use API

• use API

in favor of selectWhereClause

only called by deprecated APIv3

only called by deprecated APIv3

• this bypasses hooks.

• this bypasses hooks.

• refer docs https://docs.civicrm.org/dev/en/latest/framework/setting/

• this bypasses hooks.

• this bypasses hooks.

use getProfileFieldMetadata

Replaced by CRM_Core_CodeGen_PhpSchema. Delete this after civicrm-core and civix drop their references. Maybe allow grace-period of a couple months.

since 5.72 will be removed around 5.84

since 5.69 will be removed around 5.93. use getTemplateVars.

in 5.73 will be removed in 5.90

in 5.72 will be removed in 5.90.

in 5.72 will be removed in 5.90

in 5.72 will be removed in 5.96

in 5.72 will be removed in 5.102

in 5.54 will be removed in 5.85

use mysql DATABASE() within the query.

in 5.72 will be removed in 5.85

in 5.72 will be removed in 5.85

in 5.72 will be removed in 5.85

in 5.72 will be removed in 5.85

in 5.72 will be removed in 5.85

in 5.47 will be removed in 5.80

in favor of Civi::entity()->getOptions()

Overriding this function is no longer recommended as a way to customize options. Instead, option lists can be customized by either:

1. Using a pseudoconstant callback
2. Implementing hook_civicrm_fieldOptions

format separated by VALUE_SEPARATOR

format using php serialize()

This is a really annoying function. We ❤ exceptions. Be exceptional!

prefer Civi::log().

see https://docs.civicrm.org/dev/en/latest/framework/logging/

Use (e.g) Civi::log()->error() (priority dependent).

This function is no longer used by v3 api.

Remove in v6.0. Compatibility with older API_Exception/CiviCRM_API3_Exception contracts.

since 5.69 will be removed around 5.79

since 5.69 will be removed around 5.79

since 5.28 will be removed around 5.79

It can be - relative or absolute.

since 5.28 will be removed around 5.79

since 5.69 will be removed around 5.79

since 5.69 will be removed around 5.79

since 5.69 will be removed around 5.79

since 5.69 will be removed around 5.79

since 5.69 will be removed around 5.79

since 5.69 will be removed around 5.79

since 5.72 will be removed around 5.84

since 5.69 will be removed around 5.93. use getTemplateVars.

Use $this->addDatePickerRange() instead.

• use of this function assumes that an otherwise unavailable variable can be used form outside the class in question. However, the very fact it is otherwise unavailable means there is no contract that it will not be changed or become unused. This function is OK for temporary usage but should be accompanied with an effort to establish a more correct method or property tested hook / api interface if this is being done from outside of core.

• use of this function assumes that an otherwise unavailable variable can be used form outside the class in question. However, the very fact it is otherwise unavailable means there is no contract that it will not be changed or become unused. This function is OK for temporary usage but should be accompanied with an effort to establish a more correct method or property tested hook / api interface if this is being done from outside of core.

Use $this->add('datepicker', ...) instead.

Use $this->add('datepicker', ...) instead.

use getAuthenticatedContactID()

This variable has 1-2 references in contrib, which -probably- aren't functionally necessary. (Extensions don't load in pre-installation environments...) But we'll keep the property stub just to prevent crashes.

Replaced by $GLOBALS['CIVICRM_SQL_ESCAPER'].

Historically pages alternate between $_contactID and $_contactId. We'll standardise on one

since 5.72 will be removed around 5.84

since 5.69 will be removed around 5.93. use getTemplateVars.

use the api.

The intended replacement code is

Contribution::update(FALSE)->setValues([ 'cancel_date' => 'now', 'contribution_status_id:name' => 'Cancelled', ])->addWhere('id', '=', $contribution->id)->execute();

Jumbled up function.

The purpose of this function is to transition a pending transaction to Completed including updating any related entities.

It has been overloaded to also add recurring transactions to the database, cloning the original transaction and updating related entities.

It is recommended to avoid calling this function directly and call the api functions:

• contribution.completetransaction
• contribution.repeattransaction

These functions are the focus of testing efforts and more accurately reflect the division of roles (the job of the IPN class is to determine the outcome, transaction id, invoice id & to validate the source and from there it should be possible to pass off transaction management.)

This function has been problematic for some time but there are now several tests via the api_v3_Contribution test and the Paypal & Authorize.net IPN tests so any refactoring should be done in conjunction with those.

This function needs to have the 'body' moved to the CRM_Contribute_BAO_Contribute class and to undergo refactoring to separate the complete transaction and repeat transaction functionality into separate functions with a shared function that updates related components.

Note that it is not necessary payment processor extension to implement an IPN class now. In general the code on the IPN class is better accessed through the api which de-jumbles it a bit.

e.g the payment class can have a function like (based on Omnipay extension):

public function handlePaymentNotification() { $response = $this->getValidatedOutcome(); if ($response->isSuccessful()) { try { // @todo check if it is a repeat transaction & call repeattransaction instead. civicrm_api3('contribution', 'completetransaction', array('id' => $this->transaction_id)); } catch (CRM_Core_Exception $e) { if (!stristr($e->getMessage(), 'Contribution already completed')) { $this->handleError('error', $this->transaction_id . $e->getMessage(), 'ipn_completion', 9000, 'An error may have occurred. Please check your receipt is correct'); $this->redirectOrExit('success'); } elseif ($this->transaction_id) { civicrm_api3('contribution', 'create', array('id' => $this->transaction_id, 'contribution_status_id' => 'Failed')); }

Get site billing ID.

Set payment Instrument id - see note on getPaymentInstrumentID.

By default we actually ignore the form value. The manual processor takes it more seriously.

Does a server to server payment transaction.

• use $paymentProcessor->supports(array('cancelRecurring');

in favor of Civi::entity()->getOptions()

generic populate method. All pseudoconstant functions that use this method are also @deprecated

The static array $var is populated from the db using the $name DAO.

Note: any database errors will be trapped by the DAO.

Please use the buildOptions() method in the appropriate BAO object.

Please use the buildOptions() method in the appropriate BAO object.

Get all groups from database

The static array group is returned, and if it's called the first time, the Group DAO is used to get all the groups.

Note: any database errors will be trapped by the DAO.

Please use the buildOptions() method in the appropriate BAO object.

Please use the buildOptions() method in the appropriate BAO object. Get all active payment processors

The static array paymentProcessor is returned

Please use the buildOptions() method in the appropriate BAO object.

The static array paymentProcessorType is returned

Please use the buildOptions() method in the appropriate BAO object.

Get all Activity Statuses.

Please use the buildOptions() method in the appropriate BAO object.

Get all Visibility levels.

The static array visibility is returned

This is called from table.tpl but we aim to remove from there.

since 5.69 will be removed around 5.79

since 5.72 will be removed around 5.92

• preferred code now is to add to ensure the tpl loads custom data using the ajax template & add code to buildForm() like this

if ($this->isSubmitted()) {
  $this->addCustomDataFieldsToForm('Membership', array_filter([
  'id' => $this->getMembershipID(),
  'membership_type_id' => $this->getSubmittedValue('membership_type_id')
]));
}

$this->getDefaultEntity() must be defined for the form class for this to work.

If the postProcess form cannot use the api & instead uses a BAO function it will need. $params['custom'] = CRM_Core_BAO_CustomField::postProcess($submitted, $this->_id, $this->getDefaultEntity());

see https://github.com/civicrm/civicrm-core/pull/29241 for preferred approach - basically

1. at the tpl layer use CRM/common/customDataBlock.tpl
2. to make the fields available for postProcess if ($this->isSubmitted()) { $this->addCustomDataFieldsToForm('FinancialAccount'); }
3. pass getSubmittedValues() to CRM_Core_BAO_CustomField::postProcess($this->getSubmittedValues(), $this->_id, 'FinancialAccount'); to ensure any money or number fields are handled for localisation

since 5.65 will be removed around 5.80.

this was introduced in https://github.com/civicrm/civicrm-svn/commit/15136b07013b3477d601ebe5f7aa4f99f801beda as an awkward way to avoid fatalling on an invalid rule set with no rules.

Passing around a property is a bad way to do that check & we will work to remove.

Function demonstrates just how bad code can get from 20 years of entropy.

This function takes an overcomplicated set of params and returns an overcomplicated mix of custom groups, custom fields, custom values (if passed $entityID), and other random stuff.

• this bypasses hooks.

since 5.74 will be removed around 5.86

• this bypasses hooks.

since 5.69 will be removed around 5.74

• never set.

since 5.72 will be removed around 5.78.

since 5.72 will be removed around 5.78.

since 5.72 will be removed around 5.78.

since 5.72 will be removed around 5.78.

since 5.72 will be removed around 5.78.

unused

use $this->getPriceFieldMetadata()

use getParticipantID().

access via getEventID

This is only called from one place in the code & it is unclear whether it is a function on the way in or on the way out

functions. Use the API instead.

Use the API instead

• this bypasses hooks.

• only called by tests - to be replaced with $trxn = (array) EntityFinancialTrxn::get() ->addWhere('id', '=', $contributionID) ->addWhere('entity_table', '=', 'civicrm_contribution') ->addSelect('*')->execute();

• this bypasses hooks.

since 5.68 not part of core - to be removed 5.74

since 5.75 will be removed around 5.90 Generally you should call hooks & allow the extension to engage but if you need to then check the extension status directly - do not use a helper.

these template variables no longer used in the core template from 5.69 - stop assigning them.

• this bypasses hooks.

• this bypasses hooks.

since 5.69 will be removed around 5.80

• working to remove this in favour of addSavedMappingFields

since 5.68 expected removal time to be added when we add noisy deprecation.

since 5.68 expected removal time to be added when we add noisy deprecation.

copy of renamed class.

since 5.71 will be removed around 5.77

This is used by CiviMail but will be made redundant by FlexMailer/TokenProcessor.

• this bypasses hooks.

since 5.71 will be removed around 5.85

This is not used anywhere and should be removed soon! Function for updating a membership record's contribution_recur_id.

• this bypasses hooks.

• this bypasses hooks.

use getAllMembershipTypes.

use getMembershipType.

this should be updated to align with the other forms that use getOrder()

This function was shared with Batch_Entry which had limited overlap & needs rationalising.

use getPriceSetID()

since 5.68 will be removed around 5.74

• use the api which will use create (soon).

• this bypasses hooks.

since 5.75 will be removed around 5.95 - it is unclear why this function does not set tax for default contribution tax rate & hence it should be avoided.

• this bypasses hooks.

Use writeRecord

• this bypasses hooks.

since 5.69 will be removed around 5.85. This function is still in use but marking deprecated to make it clear that we are moving away from it. There is no function that has the guaranteed stable signature that would allow us to support if from outside of core so if using this or the core alternative from an extension you need to rely on unit tests to keep your code stable. Within core we already have good test cover on code that calls this.

The recommended approach within core is something like

private function initializeOrder(): void { $this->order = new CRM_Financial_BAO_Order(); $this->order->setForm($this); $this->order->setPriceSelectionFromUnfilteredInput($this->>getSubmittedValues()); }

$lineItems = $this->order->getLineItems();

since 5.68. Will be removed around 5.80.

Use getStatistic(string $name) instead. The definition of numberOfItems() has become conflicted among different subclasses.

in favor of buildPermissionClause

Note that if the buildPermissionClause function is called (which most reports do from buildQuery then the results of this function are re-calculated and overwritten.

• use getAddressColumns which is a more accurate description and also accepts an array of options rather than a long list

adding address fields to construct function in reports

• use getColumns('Contact') instead

• this bypasses hooks.

since 5.73 will be removed around 5.95

Links should point directly to civicrm/admin/uf/group/preview

Links should point directly to civicrm/admin/uf/group/preview

In most cases this can be replaced with $list[$key] ?? $default with the minor difference that when $list[$key] exists and is NULL, this function will always return NULL.

use convertCheckboxInputToArray instead (after testing) https://github.com/civicrm/civicrm-core/pull/8169

since 5.70 will be removed around 5.80.

At time of deprecation only usages were in CiviHR & CiviProspect in classes that appeared to be otherwise unmaintained & broken.

since 5.71 will be removed sometime after all core uses are fully removed.

in favor of hook_civicrm_fieldOptions

since 5.67 will be removed around 5.85 .

since 5.72

We should use a function that checks url values.

This is a replacement for $_REQUEST which includes $_GET/$_POST but excludes $_COOKIE / $_ENV / $_SERVER.

This method is deprecated as tables should be assumed to have UTF-8 as the default character set and collation; some other character set or collation may be specified in the column definition.

The system will attempt to use the same as your other tables, and if you really need something else then use createWithColumns and specify it per-column there.

This function should be removed in favor of linking to the CMS's logout page

TRUE, if the CMS is Drupal.

TRUE, if the CMS is Joomla!.

TRUE, if the CMS is WordPress.

Prefer CRM_Utils_Time::date(), whose name looks similar to the stdlib work-a-like.

Prefer CRM_Utils_Time::time(), whose name looks similar to the stdlib work-a-like.

This is used by CiviMail but will be made redundant by FlexMailer.

since 5.78 will be removed around 5.90

since ages ago will be removed around 5.90

since 5.78 will be removed around 5.90.

since 5.65 will be removed around 5.71

Do not use this function - it still needs full removal from active code in CRM_Contribute_Form_Task_PDFLetter.

Replace tokens for an entity.

Only used from deprecated functions not called by core.

• You may simply use the event name directly. dev/core#1744

unused function

copy of previously shared code.

Not recommended for new extensions.

As of Feb 2024, still used by Mosaico releases. Need at least a year to phase-out.

• only called by tests - to be replaced with $trxn = (array) EntityFinancialTrxn::get() ->addWhere('id', '=', $contributionID) ->addWhere('entity_table', '=', 'civicrm_contribution') ->addSelect('*')->execute();

• this was used so much in tests I copied it over - but it should go.... the tests just need to use the api.

see testSeparatePaymentWithTax for preferred way to get valid config.

use SubmitForm