# code-snippets/trunk/php/Model/Feedback_Connection.php

Code Snippets, version trunk. 207 lines.

- Page: https://pluginprobe.com/plugins/code-snippets/trunk/code/php/Model/Feedback_Connection.php
- Raw: https://pluginprobe.com/plugins/code-snippets/trunk/raw/php/Model/Feedback_Connection.php
- Modified: 2026-09-22T07:42:04+00:00

Line numbers below start at 1. Link to a line or a range by appending a fragment to the
page URL, for example `https://pluginprobe.com/plugins/code-snippets/trunk/code/php/Model/Feedback_Connection.php#L10-L20`.

```php
<?php

namespace Code_Snippets\Model;

use Code_Snippets\Utils\System_Info;

/**
 * Connection to the Code Snippets Cloud reporting API.
 *
 * The reporting endpoint is resolved on its own rather than from the cloud API URL the rest
 * of the plugin uses. Those are separate services: a site pointed at a local cloud build for
 * development would otherwise send its reports there too, where nobody would read them, and
 * the reports would fail outright whenever that build was not running.
 *
 * Trust model: the programme key below is public. It ships in the plugin source and identifies
 * the reporting programme, not the site, in the same way as the public token on the parent
 * class. Per-site authenticity comes from the registration handshake instead: a site enrols
 * once, receives a public identifier and a secret, and signs every later request with an
 * HMAC over `timestamp.METHOD.request_uri.sha256(body)`. Binding the signature to the method,
 * path, query string and body gives the cloud replay protection within its accepted timestamp
 * window. The secret is stored without autoloading, never reaches the browser and is never
 * included in a REST response. Rate limiting beyond the reporter's own throttle is the
 * cloud's responsibility.
 *
 * @package Code_Snippets
 */
class Feedback_Connection extends Basic_Cloud_Connection {

	/**
	 * Public key identifying the reporting programme.
	 */
	private const PROGRAMME_KEY = 'csb_nhv937hQa0mbBNyB0n9FTQvXZR6i3d9UA2OAZU2E04lu9loS';

	/**
	 * Host serving the reporting API.
	 */
	private const REPORTS_HOST = 'https://codesnippets.cloud';

	/**
	 * Path of the reporting endpoint, relative to the reporting host.
	 */
	private const REPORTS_PATH = 'api/v1/beta-reports';

	/**
	 * Name of the option holding this site's credential.
	 */
	public const CREDENTIALS_OPTION = 'code_snippets_feedback_credentials';

	/**
	 * Shape of a public identifier issued by the cloud.
	 */
	private const PUBLIC_ID_PATTERN = '/^[A-Za-z0-9_-]{16,128}$/';

	/**
	 * Shape of a secret issued by the cloud.
	 */
	private const SECRET_PATTERN = '/^[A-Za-z0-9]{32,128}$/';

	/**
	 * Retrieve the key identifying the reporting programme.
	 *
	 * @return string
	 */
	public function get_key(): string {
		return apply_filters( 'code_snippets_feedback_key', self::PROGRAMME_KEY );
	}

	/**
	 * Retrieve the host serving the reporting API.
	 *
	 * `CS_BETA_FEEDBACK_HOST` names a reporting service on its own, so it wins over the
	 * cloud URL a site may be pointing elsewhere for unrelated development.
	 *
	 * @return string
	 *
	 * @noinspection PhpUndefinedConstantInspection
	 */
	public function get_host(): string {
		$host = self::REPORTS_HOST;

		if ( defined( 'CS_BETA_FEEDBACK_HOST' ) && CS_BETA_FEEDBACK_HOST ) {
			$host = CS_BETA_FEEDBACK_HOST;
		}

		return untrailingslashit( apply_filters( 'code_snippets_feedback_host', $host ) );
	}

	/**
	 * Retrieve the URL of a reporting endpoint.
	 *
	 * @param string $path Optional path below the reporting endpoint.
	 *
	 * @return string
	 */
	public function get_endpoint_url( string $path = '' ): string {
		$url = sprintf( '%s/%s', $this->get_host(), self::REPORTS_PATH );

		if ( $path ) {
			$url .= '/' . ltrim( $path, '/' );
		}

		return apply_filters( 'code_snippets_feedback_endpoint_url', $url, $path );
	}

	/**
	 * Retrieve the credential issued to this site.
	 *
	 * @return array<string, mixed> Empty when this site has not enrolled.
	 */
	public function get_credentials(): array {
		$stored = get_option( self::CREDENTIALS_OPTION, [] );

		return is_array( $stored ) ? $stored : [];
	}

	/**
	 * Store the credential issued to this site.
	 *
	 * @param array<string, mixed> $credentials Credential to store.
	 *
	 * @return void
	 */
	public function save_credentials( array $credentials ): void {
		update_option( self::CREDENTIALS_OPTION, $credentials, false );
	}

	/**
	 * Discard the credential issued to this site.
	 *
	 * @return void
	 */
	public function delete_credentials(): void {
		delete_option( self::CREDENTIALS_OPTION );
	}

	/**
	 * Determine whether a credential has the shape the cloud issues.
	 *
	 * @param array<string, mixed> $credentials Credential to check.
	 *
	 * @return bool
	 */
	public function is_valid_credentials( array $credentials ): bool {
		return ! empty( $credentials['public_id'] ) && ! empty( $credentials['secret'] )
			&& preg_match( self::PUBLIC_ID_PATTERN, (string) $credentials['public_id'] )
			&& preg_match( self::SECRET_PATTERN, (string) $credentials['secret'] );
	}

	/**
	 * Create the headers common to every reporting request.
	 *
	 * @return array<string, string>
	 */
	public function get_request_headers(): array {
		$headers = [
			'Content-Type' => 'application/json; charset=utf-8',
			'Accept'       => 'application/json',
			'X-CS-Site'    => site_url(),
			'X-CS-Edition' => System_Info::get_edition(),
		];

		$key = $this->get_key();

		if ( $key ) {
			$headers['Authorization'] = 'Bearer ' . $key;
		}

		return $headers;
	}

	/**
	 * Create the headers proving a request came from this site.
	 *
	 * @param array<string, mixed> $credentials Credential issued to this site.
	 * @param string               $method      HTTP method.
	 * @param string               $uri         Request path, including any query string.
	 * @param string               $body        Raw request body, empty for a GET.
	 *
	 * @return array<string, string>
	 */
	public function get_signature_headers( array $credentials, string $method, string $uri, string $body ): array {
		$offset = isset( $credentials['offset'] ) ? (int) $credentials['offset'] : 0;
		$timestamp = (string) ( time() + $offset );
		$payload = $timestamp . '.' . strtoupper( $method ) . '.' . $uri . '.' . hash( 'sha256', $body );

		return [
			'X-CS-Site-Id'   => (string) $credentials['public_id'],
			'X-CS-Timestamp' => $timestamp,
			'X-CS-Signature' => hash_hmac( 'sha256', $payload, (string) $credentials['secret'] ),
		];
	}

	/**
	 * Reduce a URL to the part a signature covers.
	 *
	 * @param string $url Absolute URL.
	 *
	 * @return string Path, followed by the query string when there is one.
	 */
	public static function get_request_uri( string $url ): string {
		$path = (string) wp_parse_url( $url, PHP_URL_PATH );
		$query = wp_parse_url( $url, PHP_URL_QUERY );

		return $query ? $path . '?' . $query : $path;
	}
}

```