robotstxt-documentation-markdown/robotstxt-documentation-markdown-functions.php

<?php
/**
 * General Helper Functions
 *
 * @package RobotsTxt\DocumentationMarkdown
 * @since   1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Encrypt GitHub token for storage
 *
 * @since 1.0.0
 *
 * @param string $token Plain token.
 * @return string Encrypted token, or empty string on failure.
 */
function robotstxt_docmd_encrypt_token( string $token ): string {
	if ( empty( $token ) ) {
		return '';
	}

	// Use WordPress salts for encryption key.
	$key       = wp_salt( 'auth' );
	$iv_length = openssl_cipher_iv_length( 'aes-256-cbc' );
	$iv        = openssl_random_pseudo_bytes( $iv_length );
	$encrypted = openssl_encrypt( $token, 'aes-256-cbc', $key, 0, $iv );

	if ( false === $encrypted ) {
		return '';
	}

	return base64_encode( $iv . $encrypted ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
}

/**
 * Decrypt GitHub token from storage
 *
 * @since 1.0.0
 *
 * @param string $encrypted_token Encrypted token.
 * @return string Plain token, or empty string on failure.
 */
function robotstxt_docmd_decrypt_token( string $encrypted_token ): string {
	if ( empty( $encrypted_token ) ) {
		return '';
	}

	$key       = wp_salt( 'auth' );
	$iv_length = openssl_cipher_iv_length( 'aes-256-cbc' );

	$decoded = base64_decode( $encrypted_token, true ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode
	if ( false === $decoded || strlen( $decoded ) <= $iv_length ) {
		return '';
	}
	$iv        = substr( $decoded, 0, $iv_length );
	$encrypted = substr( $decoded, $iv_length );

	$decrypted = openssl_decrypt( $encrypted, 'aes-256-cbc', $key, 0, $iv );
	return false !== $decrypted ? $decrypted : '';
}

/**
 * Generate title from file path
 *
 * Converts "api-documentation.md" to "API Documentation"
 *
 * @since 1.0.0
 *
 * @param string $file_path File path.
 * @return string Generated title.
 */
function robotstxt_docmd_generate_title_from_path( string $file_path ): string {
	// Get filename without extension.
	$filename = basename( $file_path );
	$title    = preg_replace( '/\.(md|markdown)$/i', '', $filename );
	$title    = is_string( $title ) ? $title : $filename;

	// Replace separators with spaces.
	$title = str_replace( array( '-', '_' ), ' ', $title );

	// Capitalize words.
	$title = ucwords( $title );

	// Handle common abbreviations.
	$abbreviations = array(
		'Api'  => 'API',
		'Faq'  => 'FAQ',
		'Url'  => 'URL',
		'Html' => 'HTML',
		'Css'  => 'CSS',
		'Php'  => 'PHP',
		'Json' => 'JSON',
		'Xml'  => 'XML',
		'Sql'  => 'SQL',
	);

	foreach ( $abbreviations as $search => $replace ) {
		$result = preg_replace( '/\b' . $search . '\b/', $replace, $title );
		$title  = is_string( $result ) ? $result : $title;
	}

	return $title;
}

/**
 * Get status badge HTML
 *
 * @since 1.0.0
 *
 * @param string $status Status (never, pending, success, error).
 * @return string Badge HTML.
 */
function robotstxt_docmd_get_status_badge( string $status ): string {
	$badges = array(
		'never'   => array(
			'class' => 'status-never',
			'label' => __( 'Never Synced', 'robotstxt-documentation-markdown' ),
		),
		'pending' => array(
			'class' => 'status-pending',
			'label' => __( 'Syncing...', 'robotstxt-documentation-markdown' ),
		),
		'success' => array(
			'class' => 'status-success',
			'label' => __( 'Success', 'robotstxt-documentation-markdown' ),
		),
		'error'   => array(
			'class' => 'status-error',
			'label' => __( 'Error', 'robotstxt-documentation-markdown' ),
		),
	);

	$badge = $badges[ $status ] ?? $badges['never'];

	return sprintf(
		'<span class="status-badge %s">%s</span>',
		esc_attr( $badge['class'] ),
		esc_html( $badge['label'] )
	);
}

/**
 * Safely get a string value from a superglobal array
 *
 * Provides PHPStan level 9 compliant type-narrowing for superglobal access.
 *
 * @since 1.0.1
 *
 * @param array<string, mixed> $input   The superglobal array ($_POST, $_GET, etc.).
 * @param string               $key     The key to look for.
 * @param string               $fallback Default value if key not found or not a string.
 * @return string
 */
function robotstxt_docmd_input_string( array $input, string $key, string $fallback = '' ): string {
	if ( isset( $input[ $key ] ) && is_string( $input[ $key ] ) ) {
		return $input[ $key ];
	}
	return $fallback;
}

/**
 * Safely get an integer value from a superglobal array
 *
 * Provides PHPStan level 9 compliant type-narrowing for superglobal access.
 *
 * @since 1.0.1
 *
 * @param array<string, mixed> $input   The superglobal array ($_POST, $_GET, etc.).
 * @param string               $key     The key to look for.
 * @param int                  $fallback Default value if key not found or not numeric.
 * @return int
 */
function robotstxt_docmd_input_int( array $input, string $key, int $fallback = 0 ): int {
	if ( isset( $input[ $key ] ) && is_numeric( $input[ $key ] ) ) {
		return (int) $input[ $key ];
	}
	return $fallback;
}