README

SimpleClients is a small PHP client library for connecting to provider APIs through reusable, testable client classes. It favors Blue Fission conventions and uses DevElation (bluefission/develation) patterns where they keep configuration, service access, and response handling simple.

The package owns provider client boundaries: authentication input, endpoint configuration, request transport, response normalization, error shape, and deterministic test fixtures. Consumers should depend on these general client contracts instead of adding one-off provider code in application layers.

Features

SimpleClients currently offers connectors to the following services:

AWS SigV4 signing
Claude
DuckDuckGo Search
Gemini
Google Search
Grok
IP API Geo Location
Meta and Instagram messaging
Hugging Face
MurfAI
OCR providers
OpenAI
Open Weather
Speech transcription providers
Trello
Video analysis providers
Zapier Workflow API
WikiHow
Wikipedia
Wiki News

Installation

To install SimpleClients, use Composer:

composer require bluefission/simpleclients

Usage

Each service client is implemented as a class under the BlueFission\SimpleClients namespace. Below are some examples of how to use these clients.

Example: WikipediaClient

<?php

require 'vendor/autoload.php';

use BlueFission\SimpleClients\WikipediaClient;

$wikipedia = new WikipediaClient();
$summary = $wikipedia->getSummary('Artificial Intelligence');

echo $summary;

Example: WikiHowClient

<?php

require 'vendor/autoload.php';

use BlueFission\SimpleClients\WikiHowClient;

$wikihow = new WikiHowClient();
$results = $wikihow->search('How to make coffee');

print_r($results);

Example: OpenAIClient

<?php

require 'vendor/autoload.php';

use BlueFission\SimpleClients\OpenAIClient;

$openai = new OpenAIClient();
$response = $openai->complete('What is the capital of France?');

print_r($response);

Example: ZapierClient

<?php

use BlueFission\SimpleClients\Contracts\ClientConfig;
use BlueFission\SimpleClients\ZapierClient;

$zapier = new ZapierClient(new ClientConfig([
    'auth' => ['token' => getenv('ZAPIER_ACCESS_TOKEN')],
]));

$zaps = $zapier->searchZaps('lead capture');
$created = $zapier->createZap('Capture leads', $steps);
$updated = $zapier->configureZap('zap-id', 'store_lead', [
    'inputs' => ['list_id' => 'qualified-leads'],
]);

Zapier uses OAuth bearer tokens and the Workflow API /v2 endpoints. Step updates first retrieve the Zap, merge the selected step by alias, action, or title, and send the complete step list because Zapier replaces all steps on edit. options.search_limit controls how many Zaps are inspected by search and update operations.

Example: MetaMessagingClient

<?php

use BlueFission\SimpleClients\Contracts\ClientConfig;
use BlueFission\SimpleClients\MetaMessagingClient;

$messaging = new MetaMessagingClient(new ClientConfig([
    'auth' => [
        'token' => getenv('META_ACCESS_TOKEN'),
        'app_secret' => getenv('META_APP_SECRET'),
        'verify_token' => getenv('META_VERIFY_TOKEN'),
    ],
    'options' => [
        'api_version' => getenv('META_API_VERSION'),
        'sender_id' => getenv('META_SENDER_ID'),
        'channel' => 'messenger',
    ],
]));

$sent = $messaging->sendMessage('recipient-id', 'Hello');
$challenge = $messaging->verifyChallenge($_GET);
$signature = $messaging->verifySignature($rawBody, $signatureHeader);

Set base_url to https://graph.instagram.com and options.channel to instagram for the Instagram Login messaging endpoint. API versions remain explicit configuration so applications can advance them without a package release. Webhook signatures must be verified against the exact raw request body.

Further Examples

Below is a brief overview of more clients and their methods.

WikipediaClient

getSummary(string $topic): string
- Retrieves the summary of a given topic from Wikipedia.

WikiHowClient

search(string $query): array
- Searches for articles on WikiHow based on the given query.
extractRating($searchResult): float
- Extracts the rating from a search result.
getSteps(string $url): array
- Retrieves the steps from a WikiHow article.
getStepsAsString(string $url): string
- Retrieves the steps from a WikiHow article as a formatted string.

OpenAIClient

generate($input, $config = [], callable $callback = null)
- Generates a response from OpenAI based on the input.
complete(string $input, $config = []): array
- Retrieves GPT-3 completion based on the input.
chat(string $input, $config = []): array
- Retrieves GPT-3.5 chat completion based on the input.
image(string $prompt, string $width = '256', string $height = '256'): array
- Retrieves an image generated by OpenAI based on the prompt.
embeddings(string $input): array
- Retrieves embeddings from the Ada model based on the input.

GoogleSearchClient

search(string $query): array
- Searches Google using the Custom Search JSON API.

DuckDuckGoSearchClient

search(string $query): array
- Searches DuckDuckGo and retrieves results.

Configuration

Client constructors accept credentials and optional transport/test doubles where supported. Environment helpers are used only as fallback configuration. Do not commit secrets; pass API keys through runtime configuration, environment variables, or secret-management layers outside this package.

Develation Usage Pattern

SimpleClients treats DevElation helpers as the preferred package surface for reusable client internals:

Use Arr for response traversal, config merging, key checks, joins, and iterable transformations.
Use Str for provider names, endpoint normalization, prefix checks, pattern matching, and string cleanup.
Use Val for nullable, empty, truthy, and falsy checks around optional credentials and provider responses.
Use BlueFission\Net\HTTP for query strings, JSON encoding/decoding, URL parsing, path segment encoding, and header lines.
Use contract objects such as ClientConfig, ClientRequest, ClientResponse, and ClientCapabilities when a workflow needs stable request, response, or capability shapes.

Provider clients may continue returning their current array or string shapes for compatibility, but new shared paths should prefer these primitives and contract objects before introducing raw arrays or standalone helper functions.

See SPEC.md, ARCHITECTURE.md, CLIENT_CONTRACTS.md, PROVIDER_EXTRACTION.md, and tests.md for package scope, client boundaries, reusable contract shapes, provider extraction gates, and validation commands.

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue to discuss what you would like to change.

License

This project is licensed under the MIT License.

bluefission / simpleclients

Maintainers

Package info

Statistics

Security