{eac}Doojigger supports the WP Consent API plugin with an enhanced set_cookie() method. Developers may safely use the set_cookie() method regardless of the presence of the API plugin.

public function set_cookie(string $name, string $value, $expires=0, array $options=[], $consent=[]): bool

Method Parameters

• $name - the cookie name
• $value - the cookie value
• $expires - when the cookie should expire.
  • as a string (preferred) :
    • '90 days' - expires in 90 days.
    • '3 months' - expires in 3 months.
    • '1 year' - expires in 1 year.
    • 'session' - expires at the end of the browser session.
    • 'delete' or 'expired' - removes the cookie.
  • as a time offset :
    • 90 * (24 * 60 * 60) - expires in 90 days.
  • as a timestamp :
    • time() + (MONTH_IN_SECONDS * 3) - expires in 90 days.
• $options - the PHP cookie options as an array.
  • 'path' => COOKIEPATH,
  • 'domain' => COOKIE_DOMAIN,
  • 'secure' => is_ssl(),
  • 'httponly' => true,
  • 'samesite' => 'lax',
• $consent - defines the consent options and use of the cookie.
  • as an array :
    • 'plugin_or_service' => $this->pluginName,
    • 'category' => '',
    • 'function' => '', // describe cookie functionality
    • 'collectedPersonalData' => '', // describe personal data collected
    • 'memberCookie' => false,
    • 'administratorCookie' => false,
    • 'type' => 'HTTP',
    • 'domain' => ''
  • as a string :
    • the consent category.
  • as a boolean :
    • false, don't use WP Consent API.
    • true, retrieve the consent array when previously registered with set_cookie_consent().

Categories

The WP Consent API defines the following cookie categories:

• Functional: Cookies used solely for transmitting communications over an electronic network. The technical storage or access is essential to enable the use of a specific service explicitly requested by the subscriber or user. If these cookies are disabled, the requested functionality will not be available, making them essential functional cookies.
• Preferences: Cookies or other local storage that do not fall under statistics, anonymous statistics, marketing, or functional categories, but are necessary for storing user preferences.
• Statistics: Cookies or other local storage used exclusively for statistical purposes, such as analytics.
• Statistics-anonymous: Cookies or other local storage used exclusively for anonymous statistical purposes (Anonymous Analytics Cookies), placed on a first-party domain, and not used to identify individuals.
• Marketing: Cookies or other local storage required to create user profiles, send advertising, or track users across websites for marketing purposes.

Your Consent Management Package (CMP) must map its categories to these categories to properly support the WP Consent API.

In addition, eacDoojigger adds:

• necessary : Cookies or other local storage used exclusively to enable the functionality of the website or application. These cookies must not allow or enable transmission of any information to 3rd-parties. Cookies used by the WP Consent API, E-Commerce Plugins, and payment gateways are typically necessary.

necessary cookies are always allowed, regardless of user preferences.

* Instead of using the 'necessary' category, you could simply pass FALSE, an empty array, or omit the $consent argument to set_cookie().

Examples

// set a unique preference cookie for 90 days
$this->set_cookie($cookieName, $value, "90 Days", [/* default options */],
    [
        'category' => 'preferences',
        'function' => __( '%s sets this cookie to assign a unique visitor ID to track preferences and activity.', $this->PLUGIN_TEXTDOMAIN )
    ]
);

// set a necessary session cookie for the current browser session
$this->set_cookie($session_cookie, $session_id, 'session', ['samesite'=>'strict'], 'necessary');

* If the $consent parameter is omitted, empty, or false, the WP Consent API methods are not used.
* If function is omitted, the cookie will be unidentified and not registered with wp_add_cookie_info().
* Use of %s within function will be replaced with the plugin_or_service value.

Consent Management Packages

There are numerous options for CMPs to be installed on your WordPress system. Many have no support at all for the WP Consent API, some have only limited support.

A seemingly common issue is that the CMP does not set or update (in server-side PHP) the required consent_type within the WP Consent API.

To resolve this, eacDoojigger:

1. Listens for a JavaScript event (wp_consent_type_defined) that is part of the WP Consent API.
2. Sets a cookie (wp_consent_consent_type) when that event is fired.
3. Adds a WordPress filter (wp_get_consent_type) that reads the cookie to get the consent type.

If this still does not resolve the issue with your CMP, you can try adding this code snippet to your theme's functions.php (or elsewere) that will set a default consent_type if no other process sets a value. You may set this default to 'optout' (as shown) or 'optin' depending on your requirements or CMP plugin.

// set wp_consent_type if not set by a Consent Management Platform
add_filter('wp_get_consent_type',function($type)
    {
        return (empty($type)) ? 'optout' : $type;
    }
);

Additionally, you may want to change the default ('allow') consent for the necessary category with this filter:

// treat the 'necessary' category the same as 'functional'
add_filter('wp_has_consent', function($has_consent, $category, $requested_by) {
    return ($category == 'necessary') ? wp_has_consent('functional') : $has_consent;
},10,3);

Companion Methods

set_cookie_expiration()

Returns an array containing the expiration as an integer and as a string.

public function set_cookie_expiration($expires, bool $getString = true): array

$this->set_cookie_expiration('90 days');
// array( 1731896992, '90 days' )

$this->set_cookie_expiration(MONTH_IN_SECONDS * 3);
// array( 1731897402, '2 months 29 days' )

set_cookie_consent()

Parses the above $consent array (with 'expires' included in either the $consent array or the $defaults array) and registers the cookie with wp_add_cookie_info().

public function set_cookie_consent(string $name, $consent, bool $register = true, array $defaults = []): array

This may be used ...

• To pre-define your cookie's consent parameters prior to setting your cookie.
• If your CMP requires cookie information to be registered at a specific time or through a specific process (not when the cookie is set).

You can then use get_cookie_consent() to retrieve previously registered consent array(s).

$this->set_cookie_consent($cookieName,
    [
        'expires'   => '90 days'
        'category'  => 'preferences',
        'function'  => __( '%s sets this cookie to assign a unique visitor ID to track preferences and activity.', $this->PLUGIN_TEXTDOMAIN )
    ]
);
/*
    'plugin_or_service' => 'eacDoojigger',
    'category' => 'preferences',
    'expires' => '90 days',
    'function' => 'eacDoojigger sets this cookie to assign a unique visitor ID to track preferences and activity.',
    'collectedPersonalData' => '',
    'memberCookie' => false,
    'administratorCookie' => false,
    'type' => 'HTTP',
    'domain' => 'eacdoojigger.earthasylum.com'
*/

get_cookie_consent()

Returns the consent array for a specified cookie, or an associative array for all cookies, for cookies previously registered with set_cookie_consent() .

public function get_cookie_consent($name = false): array

get_cookie()

Returns a sanitized cookie value or default value if the cookie is not set.

public function get_cookie(string $name, $default = null)

Filters and Actions

Filters applied prior to calling PHP setcookie().

Compatible with WP Consent API:

apply_filters( 'wp_setcookie_expires', $expires, $name, $value );
apply_filters( 'wp_setcookie_path', $path, $name, $value );
apply_filters( 'wp_setcookie_domain', $domain, $name, $value );
apply_filters( 'wp_setcookie_category', $category, $name, $value );

Superset of (not included in) WP Consent API:

apply_filters( 'wp_setcookie_options', $options, $name );
apply_filters( 'wp_setcookie_consent', $consent, $name );
apply_filters( 'wp_setcookie_secure', $secure, $name, $value );
apply_filters( 'wp_setcookie_httponly', $httponly, $name, $value );
apply_filters( 'wp_setcookie_samesite', $samesite, $name, $value );

Action fired after successfully setting a cookie:

do_action( 'wp_setcookie_success', $name, $value, $options, $consent );

Code Snippet

See the cookie_consent.trait.php in the {eac}Doojigger Doodads github folder.