PHP code example of webfunction-protocol / webfunction

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

webfunction-protocol / webfunction example snippets

$client = \WebFunction\Client::fromPackageEndpoint("https://api.example.com/package");

$client->findUser(["id" => "123"]);
// => ["id" => "123", "name" => "Ada"]

use WebFunction\Client;

$client = Client::fromPackageEndpoint("https://api.example.com/package");

// An endpoint named "list-items" becomes the method listItems() (or list_items()).
$items = $client->listItems(["limit" => 10]);
// => [["id" => 1], ["id" => 2]]

// Pass a bearer token for endpoints that need authentication.
$secure = Client::fromPackageEndpoint(
    "https://api.example.com/package",
    bearerAuth: "my-token",
);

$secure->createItem(["name" => "Notebook"]);
// => ["id" => 3, "name" => "Notebook"]

$client = Client::fromPackageEndpoint("https://api.example.com/package");

$client = Client::fromUrl("https://api.example.com/package.json");

use WebFunction\Package;

$package = Package::fromArray([
    "base_url" => "https://api.example.com/",
    "endpoints" => [
        ["name" => "list-items", "returns" => [["object"]]],
        ["name" => "create-item", "returns" => ["object"]],
    ],
]);

$client = Client::fromPackage($package);

$client->listItems(["limit" => 10, "offset" => 20]);

$client->getCount();           // => 42
$client->listItems();          // => [["id" => 1]]
$client->findUser(["id" => "1"]); // => ["id" => "1", "name" => "Ada"]

$client->call("list-items", ["limit" => 10]);

$client->doesNotExist();
// => \BadMethodCallException

$page = $client->listPeople(["filters" => ["first_name" => "Joe"]]);
// => WebFunction\Page

$page->getItems();
// => [["person_id" => "person_1", "first_name" => "Joe"], ...]

$page->hasNext();     // => true
$page->hasPrevious();  // => false

$nextPage = $page->nextPage();
// => WebFunction\Page

$nextPage->hasPrevious(); // => true
$nextPage->previousPage(); // => back to the earlier page

$endpoint = $client->getPackage()->endpoint("list-people");
$endpoint->isPaginated(); // => true

$client = Client::fromPackageEndpoint(
    "https://api.example.com/package",
    bearerAuth: "my-token",
);

$client->listOrders();

$endpoint = $client->getPackage()->endpoint("list-orders");
$endpoint->

$client = Client::fromPackageEndpoint(
    "https://api.example.com/package",
    version: "2024-01-01",
);

$package = $client->getPackage();
$package->isVersioned(); // => true
$package->getVersion();  // => "2024-01-01"
$package->getVersions(); // => ["2023-06-01", "2024-01-01"]

$package = $client->getPackage();

$package->getName();     // => "Example API"
$package->getBaseUrl();  // => "https://api.example.com/"
$package->getDocs();     // => "Markdown documentation for the package."
$package->getEndpoints(); // => [WebFunction\Endpoint, ...]

$endpoint = $package->endpoint("find-user");
// Same as:
$endpoint = $package->endpoint("find_user");

$endpoint->getName();  // => "find-user"
$endpoint->getDocs();  // => "Retrieves user data."
$endpoint->getReturns(); // => a Type, see below
(string) $endpoint->getReturns(); // => "object"
$endpoint->getGroup(); // => "Users"

$endpoint->getArguments();
// => [WebFunction\Argument, ...]

$id = $endpoint->getArgument("id");
$id->getName();      // => "id"
(string) $id->getType(); // => "string"
$id->isRequired();   // => true
$id->isOptional();   // => false
$id->getChoices();   // => []
$id->getDocs();      // => "Identifier of the user."

$name = $endpoint->getAttribute("name");
$name->getName();      // => "name"
(string) $name->getType(); // => "string"
$name->isNullable();  // => false
$name->getValues();   // => []

$endpoint = $client->getPackage()->endpoint("find-user");
$endpoint->call(["id" => "123"]);
// => ["id" => "123", "name" => "Ada"]

$type = $endpoint->getArgument("email")->getType();

(string) $type;             // => "string.email"
$type->format("compact");   // => "email"
$type->format("base");      // => "string"

$type->isValid("[email protected]"); // => true
$type->isValid("not-an-email");    // => false

use WebFunction\Type;

(string) Type::parse(["object", "null"]); // => "object | null"
(string) Type::parse([["string"]]);       // => "array<string>"
(string) Type::parse("array");            // => "array<any>"
(string) Type::parse(null);               // => "any"

Type::parse("object.user")->objects(); // => ["user"]

$package->getObjects();
// => [WebFunction\ObjectSchema, ...]

use WebFunction\ObjectSchema;

$user = $package->object("user", ObjectSchema::CONTEXT_ATTRIBUTES);

$user->getName();       // => "user"
$user->getAttributes(); // => [WebFunction\Attribute, ...]
$user->getAttribute("email")->getType(); // => string.email

try {
    $client->findUser(["id" => "missing"]);
} catch (\WebFunction\Error $e) {
    $e->getErrorCode(); // => "USER_NOT_FOUND"
    $e->getMessage();   // => "No user with that id."
    $e->getDetails();   // => ["id" => "missing"]
}

$endpoint->getErrors();
// => [WebFunction\DocumentedError, ...]

$error = $endpoint->getError("USER_NOT_FOUND");
$error->getCode(); // => "USER_NOT_FOUND"
$error->getDocs(); // => "Returned when no user matches the id."

$client = Client::fromPackageEndpoint(
    "https://api.example.com/package",
    pipelined: true,
);

$user  = $client->findUser(["id" => "123"]);       // => a Promise
$order = $client->createOrder(["user_id" => $user["id"]]); // uses the first result

$order->resolve();
// => ["id" => "order-1", "user_id" => "123"]

$user->resolve();  // runs the pipeline
$order->value();   // already available, no extra request

use WebFunction\Pipeline;

$pipeline = new Pipeline("https://api.example.com/run-pipeline");

$pipeline->addStep(["url" => "https://api.example.com/a", "headers" => [], "body" => []]);
$pipeline->addStep(["url" => "https://api.example.com/b", "headers" => [], "body" => []]);

$pipeline->execute("all"); // => [["a" => 1], ["b" => 2]]

use WebFunction\Request;

Request::setHttpClient(function (string $url, array $headers, ?string $body): array {
    $response = MyHttp::post($url, headers: $headers, body: $body);

    return [$response->status, $response->body];
});

Request::setHttpClient(function ($url, $headers, $body) {
    return [200, json_encode(["id" => "123"])];
});

use WebFunction\Request;

Request::execute(
    "https://api.example.com/find-user",
    bearerAuth: "my-token",
    version: "2024-01-01",
    args: ["id" => "123"],
);
// => ["id" => "123", "name" => "Ada"]

bash
php tests/smoke.php