llms_insert_access_plan( array $props = array() )

Create or update an access plan.


Description Description

If $props has an "ID" parameter, that plan will be updated, otherwise a new plan will be created.

See also See also


Top ↑

Parameters Parameters

$props

(array) (Optional) An array of of properties that make up the plan to create or update.

  • 'product_id'
    (int) Required) WP Post ID of the related LifterLMS Product (course or membership).
  • 'id'
    (int) WP Post ID of the Access Plan, if omitted a new plan is created, if supplied, that plan is updated.
  • 'access_expiration'
    (string) Expiration type [lifetime|limited-period|limited-date].
  • 'access_expires'
    (string) Date access expires in m/d/Y format. Only applicable when $access_expiration is "limited-date".
  • 'access_length'
    (int) Length of access from time of purchase, combine with $access_period. Only applicable when $access_expiration is "limited-period".
  • 'access_period'
    (string) Time period of access from time of purchase, combine with $access_length. Only applicable when $access_expiration is "limited-period" [year|month|week|day].
  • 'availability'
    (string) Determine if this access plan is available to anyone or to members only. Use with $availability_restrictions to determine if the member can use the access plan. [open|members].
  • 'availability_restrictions'
    (array) Indexed array of LifterLMS Membership IDs a user must belong to to use the access plan. Only applicable if $availability is "members".
  • 'checkout_redirect_forced'
    (string) On a members' only access plan, whether to force redirect users back to the redirect settings specified in this access plan.
  • 'checkout_redirect_type'
    (string) Type of checkout redirection [self|page|url].
  • 'content'
    (string) Plan description (post_content).
  • 'enroll_text'
    (string) Text to display on buy buttons.
  • 'frequency'
    (int) Frequency of billing. 0 = a one-time payment [0-6].
  • 'is_free'
    (string) Whether or not the plan requires payment [yes|no].
  • 'length'
    (int) Number of intervals to run payment for, combine with $period & $frequency. 0 = forever / until cancelled. Only applicable if $frequency is not 0.
  • 'menu_order'
    (int) Order to display access plans in when listing them. Displayed in ascending order.
  • 'on_sale'
    (string) Enable or disable plan sale pricing [yes|no].
  • 'period'
    (string) Interval period, combine with $length. Only applicable if $frequency is not 0. [year|month|week|day].
  • 'price'
    (float) Price per charge/
  • 'sale_end'
    (string) Date when the sale pricing ends.
  • 'sale_start'
    (string) Date when the sale pricing begins.
  • 'sale_price'
    (float) Sale price.
  • 'sku'
    (string) Short user-created plan identifier.
  • 'title'
    (string) Plan title.
  • 'trial_length'
    (int) length of the trial period. Only applicable if $trial_offer is "yes".
  • 'trial_offer'
    (string) Enable or disable a plan trial period. [yes|no].
  • 'trial_period'
    (string) Period for the trial period. Only applicable if $trial_offer is "yes". [year|month|week|day].
  • 'trial_price'
    (float) Price for the trial period. Can be 0 for a free trial period.

Default value: array()


Top ↑

Return Return

(LLMS_Access_Plan|WP_Error) LLMS_Access_Plan on success, WP_Error on failure.


Top ↑

Source Source

File: includes/functions/llms-functions-access-plans.php

function llms_insert_access_plan( $props = array() ) {

	$action = 'create';

	if ( ! empty( $props['id'] ) ) {

		$action = 'update';
		$plan   = llms_get_post( $props['id'] );
		if ( ! $plan || ! is_a( $plan, 'LLMS_Access_Plan' ) ) {
			// Translators: %s = The invalid access plan ID.
			return new WP_Error( 'invalid-plan', sprintf( __( 'Access Plan ID "%s" is not valid.', 'lifterlms' ), $props['id'] ) );
		}
		unset( $props['id'] );
		$plan_array = $plan->toArray();
		/**
		 * The property 'checkout_redirect_forced' is not sent when the related checkbox is unchecked,
		 * so we have to avoid to override it with the saved value.
		 *
		 * {@see https://github.com/gocodebox/lifterlms/issues/2234}
		 */
		if ( ! isset( $props['checkout_redirect_forced'] ) ) {
			unset( $plan_array['checkout_redirect_forced'] );
		}
		$props = wp_parse_args( $props, $plan );

	}

	// Merge in default properties.
	$props = wp_parse_args(
		$props,
		apply_filters(
			'llms_access_plan_default_properties',
			array(
				'access_expiration'        => 'lifetime',
				'access_length'            => 1,
				'access_period'            => 'year',
				'availability'             => 'open',
				'checkout_redirect_forced' => 'no',
				'checkout_redirect_type'   => 'self',
				'frequency'                => 0,
				'is_free'                  => 'yes',
				'length'                   => 0,
				'on_sale'                  => 'no',
				'period'                   => 'year',
				'price'                    => 0,
				'sale_price'               => 0,
				'title'                    => __( 'Access Plan', 'lifterlms' ),
				'trial_length'             => 1,
				'trial_offer'              => 'no',
				'trial_period'             => 'year',
				'trial_price'              => 0,
				'visibility'               => 'visible',
			)
		)
	);

	/**
	 * Modify the properties passed into `llms_insert_access_plan()`.
	 *
	 * Either `llms_access_plan_before_create` for new plans or `llms_access_plan_before_update` for updates.
	 *
	 * @since 3.29.0
	 *
	 * @param array $props Properties used to create/update the access plan.
	 */
	$props = apply_filters( 'llms_access_plan_before_' . $action, $props );

	// Cannot create an access plan without a product.
	if ( empty( $props['product_id'] ) || ! is_numeric( $props['product_id'] ) ) {
		// Translators: %s = property key ('product_id').
		return new WP_Error( 'missing-product-id', sprintf( __( 'Missing required property: "%s".', 'lifterlms' ), 'product_id' ) );
	}

	// Paid plan.
	if ( $props['price'] > 0 ) {

		$props['is_free'] = 'no';

		// One-time (no trial).
		if ( 0 === $props['frequency'] ) {
			$props['trial_offer'] = 'no';
		}
	} else {

		$props['is_free']     = 'yes';
		$props['price']       = 0;
		$props['frequency']   = 0;
		$props['on_sale']     = 'no';
		$props['trial_offer'] = 'no';

	}

	// Unset recurring props when it's a 1-time payment.
	if ( 0 === $props['frequency'] ) {
		unset( $props['length'], $props['period'] );
	}

	// Unset trial props when no trial enabled.
	if ( ! llms_parse_bool( $props['trial_offer'] ) ) {
		unset( $props['trial_price'], $props['trial_length'], $props['trial_period'] );
	}

	// Unset sale props when no sale enabled.
	if ( ! llms_parse_bool( $props['on_sale'] ) ) {
		unset( $props['sale_price'], $props['sale_end'], $props['sale_start'] );
	}

	// Unset expiration props based on expiration settings.
	if ( 'lifetime' === $props['access_expiration'] ) {
		unset( $props['access_expires'], $props['access_length'], $props['access_period'] );
	} elseif ( 'limited-date' === $props['access_expiration'] ) {
		unset( $props['access_length'], $props['access_period'] );
	} elseif ( 'limited-period' === $props['access_expiration'] ) {
		unset( $props['access_expires'] );
	}

	// Ensure visibility setting is valid.
	if ( ! in_array( $props['visibility'], array_keys( llms_get_access_plan_visibility_options() ), true ) ) {
		// Translators: %s = supplied visibility setting.
		return new WP_Error( 'invalid-visibility', sprintf( __( 'Invalid access plan visibility: "%s"', 'lifterlms' ), $props['visibility'] ) );
	}

	// Ensure all periods are valid.
	$valid_periods = array_keys( llms_get_access_plan_period_options() );
	foreach ( array( 'period', 'access_period', 'trial_period' ) as $key ) {
		if ( ! empty( $props[ $key ] ) && ! in_array( $props[ $key ], $valid_periods, true ) ) {
			// Translators: %1$s = plan period key name; %2$s = the invalid period.
			return new WP_Error( 'invalid-' . $key, sprintf( __( 'Invalid access plan %1$s: "%2$s"', 'lifterlms' ), $key, $props[ $key ] ) );
		}
	}

	$checkout_redirect_type = $props['checkout_redirect_type'];

	// Ensure that the checkout redirection type is valid.
	if ( ! in_array( $checkout_redirect_type, array_keys( llms_get_checkout_redirection_types() ), true ) ) {
		// Translators: %s = supplied checkout redirect type.
		return new WP_Error( 'invalid-checkout-redirect-type', sprintf( __( 'Invalid checkout redirect type: "%s"', 'lifterlms' ), $checkout_redirect_type ) );
		// Ensure that the correct checkout redirection value is set if the type is page.
	} elseif ( 'page' === $checkout_redirect_type && empty( get_post( $props['checkout_redirect_page'] ) ) ) {
		// Translators: %d = supplied checkout redirect page ID.
		return new WP_Error( 'invalid-checkout-redirect-page', sprintf( __( 'Invalid checkout redirect page ID: "%d"', 'lifterlms' ), $props['checkout_redirect_page'] ) );
		// Ensure that the correct checkout redirection value is set if the type is url.
	} elseif ( 'url' === $checkout_redirect_type && ! filter_var( $props['checkout_redirect_url'], FILTER_VALIDATE_URL ) ) {
		// Translators: %s = supplied checkout redirect page URL.
		return new WP_Error( 'invalid-checkout-redirect-url', sprintf( __( 'Invalid checkout redirect URL: "%s"', 'lifterlms' ), $props['checkout_redirect_url'] ) );

	}

	if ( 'create' === $action ) {
		$plan = new LLMS_Access_Plan( 'new' );
		if ( ! $plan ) {
			return new WP_Error( 'plan-creation', __( 'An error was encountered while creating the access plan', 'lifterlms' ) );
		}
	}

	// Set visibility.
	$plan->set_visibility( $props['visibility'] );

	// Set all valid properties.
	$valid_props = array_keys( $plan->get_properties() );
	foreach ( $props as $prop_key => $prop_val ) {
		if ( in_array( $prop_key, $valid_props, true ) ) {
			$plan->set( $prop_key, $prop_val );
		}
	}

	/**
	 * Do something with an access plan immediately after the access plan is created/updated.
	 *
	 * Either `llms_access_plan_after_create` during creation or  `llms_access_plan_after_update` during an update.
	 *
	 * @since 3.29.0
	 *
	 * @param LLMS_Access_Plan $plan  Access plan instance.
	 * @param array            $props Properties used to create/update the access plan.
	 */
	do_action( 'llms_access_plan_after_' . $action, $plan, $props );

	return $plan;

}


Top ↑

Changelog Changelog

Changelog
Version Description
7.0.0 Correctly handle $checkout_redirect_forced property when updating.
3.30.3 Fixed spelling errors.
3.30.0 Added checkout redirect options.
3.29.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

You must log in before being able to contribute a note or feedback.