Schemes API

You can register custom scheme/protocols and intercept standard one.

This API allows you to intercept all calls to addresses according to registered schemes and send custom responses generated entirely programmatically, without actual requests to the server (without network).

#Registration

To enable processing of specific protocols, you should specify them in the list of schemes.

$app = new Boson\Application(new Boson\ApplicationCreateInfo(
    schemes: [ 'test' ],
));

$app->webview->url = 'test://hello.world/';

macOS/WebKit

Does NOT support interception of some existing schemes: http, https, ws, wss, ftp, file, data.

You will get an error similar to the following:

*** Terminating app due to uncaught 
    exception 'NSInvalidArgumentException', reason: "'https' is a URL 
    scheme that WKWebView handles natively"
*** First throw call stack:
    ...

Linux/GTK4

Does NOT support interception of some existing schemes: http, https, ws, wss, ftp, file, data.

You will get an error similar to the following:

** (process:3226): WARNING **: 16:12:59.122: 
Registering special URI scheme https is no longer allowed

#Requests Interception

After enabling the interception of all the necessary protocols (in this case, test), you can start catching the corresponding events of sending requests to this protocol (to this scheme).

use Boson\WebView\Api\Schemes\Event\SchemeRequestReceived;

$app = new Boson\Application(new Boson\ApplicationCreateInfo(
    // List of intecpted schemes
    schemes: [ 'test' ],
));

$app->on(function (SchemeRequestReceived $e): void {
    echo sprintf("%s %s\r\n", $e->request->method, $e->request->url);
    
    foreach ($e->request->headers as $header => $value) {
        echo sprintf("%s: %s\r\n", $header, $value);
    }
    
    echo sprintf("\r\n\r\n%s", $e->request->body);
    
    //
    // Result may looks like:
    //
    // GET test://hello.world/
    // accept: text/html,application/xhtml+xml,application/xml;q=0.9,etc...
    // upgrade-insecure-requests: 1
    // user-agent: Mozilla/5.0 etc...
    // sec-ch-ua: "Microsoft Edge WebView2";v="135", etc...
    // sec-ch-ua-mobile: ?0
    // sec-ch-ua-platform: "Windows"
    //
});

$app->webview->url = 'test://hello.world/';

In that case, if you need to block a request to a specified URL, you can cancel it.

$app->on(function (SchemeRequestReceived $e): void {
    $e->cancel();
});

In addition to canceling a request, you can also simulate a response from a resource.

$app->on(function (SchemeRequestReceived $e): void {
    $e->response = new Boson\Http\Response(
        body: 'Hello World!',
    );
});

Or a more complex response example:

$app->on(function (SchemeRequestReceived $e): void {
    $e->response = new Boson\Http\Response(
        body: json_encode(['error' => 'Something went wrong']),
        headers: ['content-type' => 'application/json'],
        status: 404,
    );
});

Or using specific JsonResponse response instance:

$app->on(function (SchemeRequestReceived $e): void {
    $e->response = new Boson\Http\JsonResponse(
        body: ['error' => 'Something went wrong'],
        status: 404,
    );
});

#Events

Any configured schema can send its own events (and intentions), which allow interaction with requests to specified schemas.

More information about events can be found in the events documentation.

#Request Intention

An Boson\WebView\Api\Schemes\Event\SchemeRequestReceived intention processing of user schemes registered in the configuration.

class SchemeRequestReceived<WebView> 
{
    public readonly Boson\Http\RequestInterface $request;
    
    public ?Boson\Http\ResponseInterface $response = null;
}

• $request - Custom protocol request instance.
• $response - An optional response instance containing the body string.

If intention is cancelled, then the response will be rejected (aborted).

An intention is only called for registered (in configuration) schemes.