Using rates to set salary for LaborEdge

<?php
/**
 * Matador Jobs | LaborEdge Integration: Use Rates for Job Salary Min/Max
 *
 * By default, Matador sets a job's salary minimum and maximum from the
 * `weeklyPayRange` or `hourlyPayRange` fields in LaborEdge, depending on
 * your Matador settings. This snippet overrides that behaviour and pulls
 * the salary min/max from specific entries inside the LaborEdge `rates`
 * array instead.
 *
 * HOW TO USE
 * ----------
 * 1. Copy this file into your theme's functions.php, or into a custom
 *    site-specific plugin (recommended).
 * 2. Find the two rate code IDs that represent your desired low and high
 *    salary values in LaborEdge (see "CUSTOMISATION" below).
 * 3. Replace the placeholder rate code IDs with your own.
 * 4. Save and test by running a fresh job import from the Matador dashboard.
 *
 * REQUIREMENTS
 * ------------
 * - Matador Jobs Pro 4+ with the LaborEdge integration active.
 * - PHP 8.1+.
 *
 * CUSTOMISATION
 * -------------
 * The two functions at the bottom of this file each loop through the
 * `rates` array returned by LaborEdge and look for a specific
 * `billRateCodeId`. Replace the example IDs with the codes that exist in
 * your LaborEdge account:
 *
 *   Salary LOW  → currently set to 'PR_SALARY_LOW'
 *   Salary HIGH → currently set to 'PR_SALARY_HIGH'
 *
 * To find valid rate code IDs, inspect a raw LaborEdge job payload or
 * ask your LaborEdge administrator for the bill rate code list.
 *
 * @see https://matadorjobs.com/docs/ Matador documentation
 */

// ---------------------------------------------------------------------------
// 1. HOOK — Remap the salary min/max field sources
// ---------------------------------------------------------------------------

/**
 * Tells Matador to source salary min/max values from the `rates` field
 * instead of the default pay-range fields, and to transform those values
 * using the callback functions defined below.
 *
 * Priority 20 ensures this runs after Matador has built its default map which is hooked at priority 5.
 */
add_filter(
	'matador_standard_job_object_field_map_laboredge',
	'matador_custom_laboredge_use_rates_for_salary',
	20
);

/**
 * Filter callback: swap the salary min/max mappings.
 *
 * Matador's field map is an array of mapping tuples. Each tuple looks like:
 *
 *   [ [destination_field, sub_key], source_field, transform_callback ]
 *
 * This function finds the tuples whose destination is ['salary', 'min'] or
 * ['salary', 'max'] and updates them to:
 *   - Pull data from the `rates` source field.
 *   - Pass that data through a custom transform callback.
 *
 * @param array $defaults The default field map built by Matador.
 * @return array The modified field map.
 */
function matador_custom_laboredge_use_rates_for_salary( array $defaults ): array {

	foreach ( $defaults as $i => $mapping ) {

		// Only act on mappings whose destination is ['salary', 'min|max'].
		if (
			is_array( $mapping[0] )
			&& 'salary' === $mapping[0][0]
			&& in_array( $mapping[0][1], [ 'min', 'max' ], true )
		) {
			// Switch the source field from the default pay-range to `rates`.
			$defaults[ $i ][1] = 'rates';

			// Point to the appropriate transform callback for min or max.
			$defaults[ $i ][2] = ( 'min' === $mapping[0][1] )
				? 'matador_custom_laboredge_rate_for_salary_low'
				: 'matador_custom_laboredge_rate_for_salary_high';
		}
	}

	return $defaults;
}

// ---------------------------------------------------------------------------
// 2. TRANSFORMS — Extract the desired rate value from the rates array
// ---------------------------------------------------------------------------

/**
 * Transform callback: extract the salary MINIMUM from the rates array.
 *
 * Receives the full `rates` array from the LaborEdge job object and returns
 * the numeric rate value belonging to the bill rate code that should map to
 * the salary minimum.
 *
 * CUSTOMISE: Replace 'PR_SALARY_LOW' with the billRateCodeId that
 * represents your low / minimum salary rate.
 *
 * @param mixed  $value        The raw value from LaborEdge (expected: array of rate objects).
 * @param object $external_job The full raw LaborEdge job object.
 * @param object $standard_job The Matador standard job object being built.
 * @return string|int|float The rate value, or an empty string if not found.
 */
function matador_custom_laboredge_rate_for_salary_low( $value, $external_job, $standard_job ) {

	if ( ! is_array( $value ) ) {
		return '';
	}

	$salary_low = '';

	foreach ( $value as $rate ) {
		// ---------------------------------------------------------------
		// CUSTOMISE: Replace 'PR_SALARY_LOW' with your target rate code.
		// If desired, you can condition which rate is used on data in the $external_job or $standard_job objects.
		// ---------------------------------------------------------------
		if ( $rate?->billRateCodeId && 'PR_SALARY_LOW' === $rate->billRateCodeId ) {
			$salary_low = $rate->rate;
		}
	}

	return $salary_low;
}

/**
 * Transform callback: extract the salary MAXIMUM from the rates array.
 *
 * Receives the full `rates` array from the LaborEdge job object and returns
 * the numeric rate value belonging to the bill rate code that should map to
 * the salary maximum.
 *
 * CUSTOMISE: Replace 'PR_SALARY_HIGH' with the billRateCodeId that
 * represents your high / maximum salary rate.
 *
 * @param mixed  $value        The raw value from LaborEdge (expected: array of rate objects).
 * @param object $external_job The full raw LaborEdge job object.
 * @param object $standard_job The Matador standard job object being built.
 * @return string|int|float The rate value, or an empty string if not found.
 */
function matador_custom_laboredge_rate_for_salary_high( $value, $external_job, $standard_job ) {

	if ( ! is_array( $value ) ) {
		return '';
	}

	$salary_high = '';

	foreach ( $value as $rate ) {
		// ------------------------------------------------------------------
		// CUSTOMISE: Replace 'PR_SALARY_HIGH' with your target code.
		// If desired, you can condition which rate is used on data in the $external_job or $standard_job objects.
		// ------------------------------------------------------------------
		if ( $rate?->billRateCodeId && 'PR_SALARY_HIGH' === $rate->billRateCodeId ) {
			$salary_high = $rate->rate;
		}
	}

	return $salary_high;
}