PHPackages                             f4php/ollaminator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. f4php/ollaminator

ActiveLibrary

f4php/ollaminator
=================

Ollaminator is ollama client implementation for F4, a (really) lightweight web application framework

v0.0.3(today)01↑2900%MITPHP

Since Aug 9Pushed todayCompare

[ Source](https://github.com/f4php/ollaminator)[ Packagist](https://packagist.org/packages/f4php/ollaminator)[ RSS](/packages/f4php-ollaminator/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (4)Used By (0)

Ollaminator
===========

[](#ollaminator)

Ollaminator is an [Ollama](https://ollama.com) client for [F4](https://github.com/f4php/framework), a lightweight PHP/PostgreSQL-based web development framework.

It provides a small, typed wrapper around the Ollama HTTP API for chat, single-prompt generation, embeddings, and model listing — returning readonly response objects instead of raw arrays.

Requirements
------------

[](#requirements)

- PHP 8.3+ (uses typed class constants and named arguments)
- A running [Ollama](https://ollama.com/download) instance (defaults to `http://localhost:11434`)
- [Guzzle](https://docs.guzzlephp.org/) 7 (installed as a dependency)

Installation
------------

[](#installation)

```
composer require f4php/ollaminator
```

Configuration
-------------

[](#configuration)

Ollaminator reads two F4-wide config constants for its defaults:

```
// somewhere in your F4 config
final class Config
{
    public const string OLLAMINATOR_URL   = 'http://localhost:11434'; // Ollama host
    public const string OLLAMINATOR_MODEL = 'llama3.2';               // default model
    // ...
}
```

Both are used as fall-through defaults, so in most applications you configure them **once** and never pass a host or model again.

**Model** is resolved per call in this order:

1. A `model:` argument passed to the individual call (`chat`/`generate`/`embed`).
2. The `model:` argument passed to the `Client` constructor.
3. `F4\Config::OLLAMINATOR_MODEL`.

**Host** comes from `F4\Config::OLLAMINATOR_URL` and is the default `baseUrl` of `ApiClient`. Construct an `ApiClient` with an explicit `baseUrl:` to override it for a given client.

You can still override the model per-client or per-call, and the host per-client, whenever you need to.

Quick start
-----------

[](#quick-start)

By default the client talks to Ollama on `Config::OLLAMINATOR_URL` (e.g. `http://localhost:11434`). Make sure the model you want is pulled first (e.g. `ollama pull llama3.2`).

### Chat

[](#chat)

```
use F4\Ollaminator\Client;

$client = new Client();

// No model here — it comes from Config::OLLAMINATOR_MODEL
$response = $client->chat(
    messages: [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user',   'content' => 'Say hello in one sentence.'],
    ],
);

// ChatResponse is Stringable — casting yields the message content
echo $response;                     // "Hello! ..."
echo $response->message['content']; // same thing, explicitly
```

### Generate (single prompt)

[](#generate-single-prompt)

```
$response = $client->generate(
    prompt: 'Write a haiku about PHP.',
);

echo $response;           // GenerateResponse is Stringable
echo $response->response; // the generated text
```

### Embeddings

[](#embeddings)

```
$response = $client->embed(
    model: 'nomic-embed-text', // override the default just for this call
    input: ['The quick brown fox', 'jumps over the lazy dog'],
);

// float[][] — one vector per input
$vectors = $response->embeddings;
```

### List local models

[](#list-local-models)

```
foreach ($client->listModels() as $model) {
    echo "{$model->name} ({$model->size} bytes)\n";
}
```

Connecting to a non-default host
--------------------------------

[](#connecting-to-a-non-default-host)

To reach a host other than `Config::OLLAMINATOR_URL`, pass a configured `ApiClient` to the `Client` constructor. Use named arguments, since `$model` is the first constructor parameter:

```
use F4\Ollaminator\ApiClient;
use F4\Ollaminator\Client;

$client = new Client(
    apiClient: new ApiClient(baseUrl: 'http://ollama.internal:11434', timeout: 120),
);

// or pin both a default model and a custom host:
$client = new Client(
    model: 'llama3.2',
    apiClient: new ApiClient(baseUrl: 'http://ollama.internal:11434'),
);
```

JSON / structured output
------------------------

[](#json--structured-output)

Ask the model to return valid JSON, optionally constrained by a JSON schema:

```
$response = $client->chat(
    messages: [['role' => 'user', 'content' => 'Give me a person as JSON.']],
    format: [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'age'  => ['type' => 'integer'],
        ],
        'required' => ['name', 'age'],
    ],
);

$person = json_decode((string) $response, associative: true);
```

Pass `format: 'json'` for unstructured JSON mode.

Error handling
--------------

[](#error-handling)

All errors extend `F4\Ollaminator\Exception\OllamaException`:

```
use F4\Ollaminator\Exception\ConnectionException;
use F4\Ollaminator\Exception\ModelNotFoundException;
use F4\Ollaminator\Exception\OllamaException;

try {
    $response = $client->chat(messages: $messages);
} catch (ConnectionException $e) {
    // Ollama unreachable at the configured host
} catch (ModelNotFoundException $e) {
    // model isn't pulled locally (HTTP 404)
} catch (OllamaException $e) {
    // any other Ollama / transport error
}
```

Documentation
-------------

[](#documentation)

- **[docs/AGENTS.md](docs/AGENTS.md)** — complete API reference (every method, parameter, and response object) intended for AI agents and as a detailed developer reference.

License
-------

[](#license)

MIT © Dennis Kreminsky

###  Health Score

34

—

LowBetter than 74% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity25

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f878fcf741f07dcf8551640258e4365051c979530601d80867449bca6ffd5519?d=identicon)[arteregn](/maintainers/arteregn)

---

Top Contributors

[![etranger](https://avatars.githubusercontent.com/u/4062692?v=4)](https://github.com/etranger "etranger (4 commits)")

---

Tags

clientollamaf4

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/f4php-ollaminator/health.svg)

```
[![Health](https://phpackages.com/badges/f4php-ollaminator/health.svg)](https://phpackages.com/packages/f4php-ollaminator)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k555.0M2.8k](/packages/aws-aws-sdk-php)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k832.6k52](/packages/neuron-core-neuron-ai)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k19](/packages/tempest-framework)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k6.0M770](/packages/sylius-sylius)[google/cloud

Google Cloud Client Library

1.2k16.9M57](/packages/google-cloud)[google/cloud-core

Google Cloud PHP shared dependency, providing functionality useful to all components.

346137.0M126](/packages/google-cloud-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)