78 lines
2.8 KiB
PHP
78 lines
2.8 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
/**
|
|
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
|
* SPDX-License-Identifier: AGPL-3.0-or-later
|
|
*/
|
|
|
|
namespace KTXF\Mail\Provider;
|
|
|
|
use KTXF\Mail\Service\ServiceBaseInterface;
|
|
|
|
/**
|
|
* Mail Provider Service Test Interface
|
|
*
|
|
* Optional interface for mail providers that support testing service connections.
|
|
* Providers implementing this interface can validate connection parameters,
|
|
* test authentication, and verify service availability before creating a
|
|
* persistent service configuration.
|
|
*
|
|
* Supports two testing modes:
|
|
* 1. Testing an existing service (validate current configuration)
|
|
* 2. Testing a fresh configuration (validate before saving)
|
|
*
|
|
* @since 2025.05.01
|
|
*/
|
|
interface ProviderServiceTestInterface extends ProviderBaseInterface {
|
|
|
|
/**
|
|
* Test a service connection
|
|
*
|
|
* Tests connectivity, authentication, and capabilities of a service.
|
|
*
|
|
* For new services: use serviceFresh() to create a service, configure it with
|
|
* setters, then pass it to this method for testing before persisting.
|
|
*
|
|
* For existing services: fetch the service and pass it directly.
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param ServiceBaseInterface $service Service to test (can be fresh/unsaved or existing)
|
|
* @param array $options Provider-specific test options:
|
|
* - 'timeout' => int (seconds, default: 10)
|
|
* - 'verify_ssl' => bool (default: true)
|
|
* - 'test_send' => bool (attempt test send if capable, default: false)
|
|
* - 'test_receive' => bool (attempt mailbox access if capable, default: true)
|
|
*
|
|
* @return array Test results in the format:
|
|
* [
|
|
* 'success' => bool,
|
|
* 'message' => 'Connection successful' | 'Error message',
|
|
* 'details' => [
|
|
* 'connected' => bool, // Socket/HTTP connection succeeded
|
|
* 'authenticated' => bool, // Authentication succeeded
|
|
* 'capabilities' => ['IMAP4rev1', ...], // Server capabilities (if applicable)
|
|
* 'serverInfo' => 'Server version/banner',
|
|
* 'latency' => 123, // Connection time in milliseconds
|
|
* 'protocols' => [
|
|
* 'inbound' => [
|
|
* 'connected' => bool,
|
|
* 'authenticated' => bool,
|
|
* 'error' => 'error message if failed'
|
|
* ],
|
|
* 'outbound' => [ // For split-socket (IMAP+SMTP)
|
|
* 'connected' => bool,
|
|
* 'authenticated' => bool,
|
|
* 'error' => 'error message if failed'
|
|
* ]
|
|
* ],
|
|
* 'errors' => ['Error 1', 'Error 2'], // List of errors encountered
|
|
* ]
|
|
* ]
|
|
*/
|
|
public function serviceTest(ServiceBaseInterface $service, array $options = []): array;
|
|
|
|
}
|