Pre-selecting a calendar date using URL parameters

/**
 * GravityCalendar - URL Parameter Initial Date Support
 *
 * This snippet allows users to pre-select a calendar date via URL parameter.
 *
 * Usage Examples:
 * - ?calendar_date=2025-03-01
 * - ?calendar_date=2025-03-15
 * - ?calendar_date=2025-12-25
 */

/**
 * The URL parameter name to use for the initial date.
 *
 * Example: If set to 'calendar_date', use ?calendar_date=2025-03-01 in the URL
 * Example: If set to 'start_date', use ?start_date=2025-03-01 in the URL
 */
define( 'GRAVITYCALENDAR_DATE_URL_PARAM', 'calendar_date' );

add_filter( 'gravityview/calendar/options', 'gravitycalendar_add_initial_date_from_url', 10, 3 );
add_filter( 'gravityview/calendar/extra_options', 'gravitycalendar_set_navigate_to_current_from_url', 10, 3 );

/**
 * Get and validate date from URL parameter.
 *
 * This helper function extracts the date from the URL, validates the format,
 * and ensures it's a real date. Returns the validated date string or false.
 *
 * @since TBD
 *
 * @return string|false The validated date string (YYYY-MM-DD) or false if invalid/missing.
 */
function gravitycalendar_get_date_from_url() {

	/**
	 * Check if the URL has our date parameter.
	 */
	$url_param_name = GRAVITYCALENDAR_DATE_URL_PARAM;

	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Reading URL parameter for display only.
	if ( ! isset( $_GET[ $url_param_name ] ) ) {
		return false;
	}

	/**
	 * Get the date from the URL and clean it up for security.
	 */
	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Reading URL parameter for display only.
	$user_provided_date = sanitize_text_field( wp_unslash( $_GET[ $url_param_name ] ) );

	/**
	 * Check if the date format is correct (YYYY-MM-DD).
	 *
	 * Example: '2025-03-01' is valid, '03/01/2025' is not.
	 */
	$is_valid_format = preg_match( '/^\d{4}-\d{2}-\d{2}$/', $user_provided_date );

	if ( ! $is_valid_format ) {
		GV_Extension_Calendar_Feed::logger()->error(
			sprintf(
				'Invalid date format in URL parameter "%s". Expected YYYY-MM-DD, got: %s',
				$url_param_name,
				$user_provided_date
			)
		);

		return false;
	}

	/**
	 * Check if the date is actually real.
	 *
	 * Example: '2025-03-01' is real, '2025-13-45' is not (no 13th month or 45th day).
	 */
	list( $year, $month, $day ) = explode( '-', $user_provided_date );

	$is_real_date = checkdate( (int) $month, (int) $day, (int) $year );

	if ( ! $is_real_date ) {
		GV_Extension_Calendar_Feed::logger()->error(
			sprintf(
				'Invalid date in URL parameter "%s": %s (this date does not exist)',
				$url_param_name,
				$user_provided_date
			)
		);

		return false;
	}

	return $user_provided_date;
}

/**
 * Add initialDate to calendar options based on URL parameter.
 *
 * This function checks if a date is provided in the URL and, if valid,
 * sets it as the initial date for the calendar to display.
 *
 * @since TBD
 *
 * @param array $calendar_options The calendar configuration options passed to FullCalendar.
 * @param int   $form_id          The form ID.
 * @param int   $feed_id          The calendar feed ID.
 *
 * @return array Modified calendar options with initialDate if valid URL parameter exists.
 */
function gravitycalendar_add_initial_date_from_url( $calendar_options, $form_id, $feed_id ) {

	$date = gravitycalendar_get_date_from_url();

	if ( false === $date ) {
		return $calendar_options;
	}

	$calendar_options['initialDate'] = $date;

	return $calendar_options;
}

/**
 * Set navigateToEvents to "current" when URL date parameter is present.
 *
 * When a user provides a specific date in the URL, we want the calendar to stay
 * on that date rather than automatically navigating to past or future events.
 * This overrides the "No Current Events Behavior" setting to "Stay on Today".
 *
 * @since TBD
 *
 * @param array $extra_options Extra calendar options (not standard FullCalendar options).
 * @param int   $form_id       The form ID.
 * @param int   $feed_id       The calendar feed ID.
 *
 * @return array Modified extra options with navigateToEvents set to 'current'.
 */
function gravitycalendar_set_navigate_to_current_from_url( $extra_options, $form_id, $feed_id ) {

	$date = gravitycalendar_get_date_from_url();

	if ( false === $date ) {
		return $extra_options;
	}

	/**
	 * URL parameter exists, so set navigateToEvents to 'current'.
	 *
	 * This means "Stay on Today (Show Current Calendar)" and prevents the calendar
	 * from automatically jumping to past or future events when there are no events
	 * in the current view.
	 */
	$extra_options['navigateToEvents'] = 'current';

	return $extra_options;
}

function gravitycalendar_add_initial_date_from_url( $calendar_options, $form_id, $feed_id ) {
    // Only apply to calendar feeds #5 and #12
    $allowed_feeds = array( 5, 12 );

    if ( ! in_array( $feed_id, $allowed_feeds, true ) ) {
        return $calendar_options;
    }

    // ... rest of the code continues here
}

add_filter( 'gravityview/calendar/extra_options', 'gravitycalendar_set_navigate_to_current_from_url', 10, 3 );