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.

Update a specified case. Use civicrm_api3_case_create() instead.

api notice

api notice

api notice

• should just use create

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

api notice

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.

use CRM_Admin_Form_Generic instead.

use CRM_Admin_Form_Generic instead.

• 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()

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

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

since 6.3 will be removed around 6.10

since 6.3 will be removed around 6.10

since 6.3 will be removed around 6.10

since 6.3 will be removed around 6.10

since 5.78 will be removed around 5.84

since 6.3 will be removed around 6.15

since 6.3 will be removed around 6.15

since 6.3 will be removed around 6.15

since 6.3 will be removed around 6.15

since 6.3 will be removed around 6.15

since 5.59 will be removed around 5.89.

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.

since 5.80 will be removed around 5.90

since 5.80 will be removed around 5.90

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 6.2 will be removed when core callers fully removed.

since 5.68 will be removed around 5.74.

• 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.

since 6.10 will be removed around 6.22

• this bypasses hooks.

since 6.0 will be removed around 6.6.

since 6.0 will be removed around 6.6.

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.

• try to use getContributionValue() instead as it is strictly a cached lookup on the contribution values, rather than a grab-bag.

use $this->isSeparateMembershipPayment() function.

• this bypasses hooks.

• just call the BAO / api directly.

Deprecated Jun 2025 in favor of Civi::rebuild(). Reassess after Jun 2026. For an extension bridging before+after, suggest guard like: if (version_compare(CRM_Utils_System::version(), 'X.Y.Z', '>=')) Civi::rebuild(...)->execute() else CRM_Core_BAO_Cache::resetCaches(); Choose an 'X.Y.Z' after determining that your preferred rebuild-target(s) are specifically available in X.Y.Z.

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.

Does anyone use this function? Does it do what you expect?

• 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

Silly function that does almost nothing.

Silly function that shouldn't exist.

as of 5.72 use getExtendsEntityColumnValueOptions - will be removed by 5.78

since 6.3 will be removed around 6.13.

WARNING: Nonstandard params searches by tag_id rather than id!

use Apiv4.

• this bypasses hooks.

• this bypasses hooks.

since 5.72 will be removed around 5.82

to be removed.

since 6.6 will be removed around 6.12

since 5.71 will be removed around 5.85.

• this bypasses hooks.

• this bypasses hooks.

• use API

• use API

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/

in 6.9 will be removed around 6.21

• this bypasses hooks.

• this bypasses hooks.

use getProfileFieldMetadata

in CiviCRM 6.6

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

Deprecated Feb 2025 in favor of Civi::rebuild(). Reassess after Jun 2026. For an extension bridging before+after, suggest guard like: if (version_compare(CRM_Utils_System::version(), 'X.Y.Z', '>=')) Civi::rebuild(...)->execute() else CRM_Core_Config::singleton()->cleanupCaches(); Choose an 'X.Y.Z' after determining that your preferred rebuild-target(s) are specifically available in X.Y.Z.

in 5.73 will be removed in 5.90

in 5.72 will be removed in 5.90.

since 6.6 will be removed around 6.20.

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()

Comma separated, spaces trimmed, key=value optional

This was added to handle a wonky/legacy field, civicrm_product.options. If you're adding new fields, then use SERIALIZE_JSON instead. JSON is more standardized and has fewer quirks.

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).

See formatter()

See formatter()

See formatter()

since 6.1 will be removed around 6.13

This function is no longer used by v3 api.

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

since 5.80 will be removed around 6.12

• 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 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'].

Deprecated Feb 2025 in favor of Civi::rebuild(). Reassess after Jun 2026. For an extension bridging before+after, suggest guard like: if (version_compare(CRM_Utils_System::version(), 'X.Y.Z', '>=')) Civi::rebuild(...)->execute() else CRM_Core_Invoke::rebuildMenuAndCaches(); Choose an 'X.Y.Z' after determining that your preferred rebuild-target(s) are specifically available in X.Y.Z.

• going forward the optionValue table will not support domain-specific options

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

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.

Get all Activity types.

The static array activityType is returned

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.

Directly apply self::setRequiredTemplateTabKeys to the tabHeader variable

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.

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.

since 6.1.0 will be removed around 6.7.0

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.

avoid calling this function directly as it is likely to change.

since 6.0 will be removed around 6.24 (long deprecation as there are many non-core callers)

• 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.

use `getLocationBlockValue()

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

since 6.6 will be removed around 6.12

since 6.6 will be removed around 6.12

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 6.8 will be removed around 6.24

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).

since 6.9 will be removed around 6.15

• 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.82 will be removed around 5.92

since 5.82 will be removed around 5.92

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();

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

since 6.5 by dev/core#4349 and PR#33076 but still used by Contact Layout Summary Editor

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.80 will be removed around 5.98

Implement a serialization format where:

• Items are comma-separated
• Items maybe barewords or "key=value" pairs

This format is not well-defined for all possible inputs. It should not be used. It's included for working with legacy data.

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

in favor of hook_civicrm_fieldOptions

since 5.72

• use CRM_Utils_System::sendJSONResponse

use ini_parse_quantity

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.

TRUE, if the CMS is Drupal.

TRUE, if the CMS is Joomla!.

TRUE, if the CMS is WordPress.

Deprecated Feb 2025 in favor of Civi::rebuild(). Reassess after Jun 2026. For an extension bridging before+after, suggest guard like: if (version_compare(CRM_Utils_System::version(), 'X.Y.Z', '>=')) Civi::rebuild(...)->execute() else CRM_Utils_System::flushCache();) Choose an 'X.Y.Z' after determining that your preferred rebuild-target(s) are specifically available in X.Y.Z.

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.

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

since 6.3 will be removed around 6.15

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

• use where clause

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.

Note: fields_callback is now deprecated in favor of the civi.entity.fields event.

Not needed if you use $this->createTestRecord() to make your custom groups, as that will cleanup automatically.

• 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