ivyforms / backend / src / Services / Security / CaptchaServiceInterface.php

CaptchaServiceInterface.php in The Innovative Form Builder – IvyForms 0.8, at backend/src/Services/Security/CaptchaServiceInterface.php

105 lines 2.9 KB

Raw Download Zip

1	<?php
2
3	/**
4	* @copyright © Melograno Venture Studio. All rights reserved.
5	* @licence See COPYING.md for license details.
6	*/
7
8	namespace IvyForms\Services\Security;
9
10	// phpcs:disable PSR1.Files.SideEffects
11	use IvyForms\Common\Exceptions\ForbiddenException;
12
13	if (!defined('ABSPATH')) {
14	exit; // Exit if accessed directly
15	}
16
17	/**
18	* Interface for CAPTCHA service implementations
19	*
20	* This interface defines the contract that all CAPTCHA services must implement,
21	* providing a polymorphic approach for different CAPTCHA providers.
22	*
23	* @package IvyForms\Services\Security
24	*/
25	interface CaptchaServiceInterface
26	{
27	/**
28	* Verify CAPTCHA response with the provider
29	*
30	* @param string $response The CAPTCHA response token
31	* @param string $secretKey The secret key
32	* @param string $type The CAPTCHA type
33	* @param string $userIp Optional user IP address
34	* @return bool
35	*/
36	public function verify(string $response, string $secretKey, string $type = 'v2', string $userIp = ''): bool;
37
38	/**
39	* Get the script URL for frontend integration
40	*
41	* @param string $type The CAPTCHA type
42	* @param string $siteKey The site key
43	* @param string $language Optional language code (default: 'en')
44	* @return string
45	*/
46	public function getScriptUrl(string $type, string $siteKey, string $language = 'en'): string;
47
48	/**
49	* Get frontend configuration for the CAPTCHA
50	*
51	* @param string $type The CAPTCHA type
52	* @param string $siteKey The site key
53	* @return array<string, mixed>
54	*/
55	public function getFrontendConfig(string $type, string $siteKey): array;
56
57	/**
58	* Validate CAPTCHA credentials
59	*
60	* @param string $siteKey The site key
61	* @param string $secretKey The secret key
62	* @return array{success: bool, message: string}
63	*/
64	public function validateCredentials(string $siteKey, string $secretKey): array;
65
66	/**
67	* Check if the CAPTCHA service is configured
68	*
69	* @return bool
70	*/
71	public function isConfigured(): bool;
72
73	/**
74	* Get the site key from settings
75	*
76	* @return string
77	*/
78	public function getSiteKey(): string;
79
80	/**
81	* Get the CAPTCHA type from settings
82	*
83	* @return string
84	*/
85	public function getType(): string;
86
87	/**
88	* Validate form submission with CAPTCHA
89	*
90	* @param array<string, mixed> $submissionData The form submission data
91	* @param array<object> $formFields The form field objects
92	* @return bool
93	* @throws ForbiddenException
94	*/
95	public function validateFormSubmission(array $submissionData, array $formFields): bool;
96
97	/**
98	* Validate settings for this CAPTCHA provider
99	*
100	* @param array<string, mixed> $settings The settings to validate
101	* @return array{success: bool, message: string}
102	*/
103	public function validateSettings(array $settings): array;
104	}
105