Download the PHP package raulast/macro-llm-php without Composer

macro-llm-php

Provider-agnostic AI client for Laravel, Slim 4, and standalone PHP.

Overview

MacroLLM provides a unified interface to interact with any AI provider from any PHP 8.1+ application. Call $llm->chat(...) with the same request format regardless of which provider is behind the call — swap providers by changing a single string.

Internally, every request and response flows through a normalized format (InternalRequest / InternalResponse). Providers implement bidirectional normalization: your application code stays the same. This decouples business logic from vendor-specific APIs and makes provider migration a configuration change, not a rewrite.

The HTTP layer is a thin Guzzle wrapper (HttpClient) — illuminate/http is only pulled in for Laravel macro registration, not for core HTTP operations. Standalone and Slim users get zero Laravel overhead.

On top of the provider layer, MacroLLM provides a full agentic stack: Skills (reusable system-prompt + tool bundles), Agents (automatic tool-call loops with configurable memory), and Orchestration (sequential or parallel multi-agent workflows). Combined with built-in MCP client/server support, you can build complex AI-powered systems while keeping each piece testable and swappable.

Features

• 14 built-in providers: OpenAI, Anthropic, Gemini, Groq, OpenRouter, Ollama, llama.cpp, OpenCode Zen Go, OpenCode Zen Go (Anthropic), Azure OpenAI, Mistral, DeepSeek, xAI, Cohere
• Unified InternalRequest / InternalResponse format with bidirectional normalization
• Thin Guzzle HTTP layer — no illuminate/http required outside Laravel
• Retry/backoff exponential configurable per provider (retries, retry_delay_ms)
• Vision/multimodal messages — InternalMessage::userWithImage() (base64 by default) and ContentPart[]
• Structured output via ResponseFormat::jsonSchema() (OpenAI-compatible providers)
• Automatic tool-call loop via Agent
• Reusable Skills (system prompt + tools + config — composable, subclassable, DB-hydratable via Skill::fromArray())
• GenericSkill concrete class for inline and DB-hydrated skills (no subclassing needed)
• Parametrizable conversation memory (NullMemory, InMemoryMemory, SqliteMemory, RedisMemory, FileMemory)
• Multi-agent Orchestration (sequential, parallel, and conditional routing)
• MCP Client — discover and use tools from any MCP server
• MCP Server — expose your tools as a PSR-15 middleware endpoint
• Laravel integration (ServiceProvider, Facade, auto-discovery, vendor:publish)
• Slim 4 integration (MacroLLMSlimExtension)
• Standalone PHP — no framework required
• PHP 8.1+ (enums, readonly classes, fibers)

Supported Providers

Capabilities are declared via interfaces. Use instanceof to check at runtime:

Provider Details

Requirements

• PHP ^8.1
• Laravel ^10 | ^11 (optional, for Laravel integration)

Installation

Laravel auto-discovery registers the ServiceProvider automatically. Optionally publish the config:

Configuration

The config file (config/macro-llm.php) defines:

Each provider entry supports: api_key, default_model, base_url, timeout, retries, retry_delay_ms, extra_headers. All numeric fields are ?int — null means "use global value".

API keys and other string settings support environment variable patterns ('${ENV_VAR}'), expanded when the configuration object is built. Load your .env before constructing Config. A variable that is not defined is left verbatim rather than collapsing to an empty string, so a misconfiguration stays visible instead of turning into a confusing 401.

Example .env entries:

Usage

Standalone (no framework)

Laravel (via Facade)

Laravel (via HTTP macro)

Streaming

Listing Available Models

Tool Calling

Skills

Vision/Multimodal

Structured Output

Observe each event in the agent's tool-call loop without modifying or extending Agent (which is final). Pass an onStep closure to AgentConfig — it receives an AgentStep value object at every meaningful point in the loop.

Step types:

The callback is fire-and-forget: exceptions propagate to the run() caller. Passing null (the default) has zero overhead on the hot path.

Conversation Memory

Multi-Agent Orchestration

MCP Client

MCP Server (Laravel)

Slim 4

MacroLLMSlimExtension requires the container to support set(). PHP-DI's Container does. Slim's built-in container does not — use PHP-DI or another writable PSR-11 container.

The config/macro-llm.php file lives in your project (not in the package) and returns a plain array:

Same format as Config::fromArray() — see the Configuration section.

Directory Structure

Architecture

MacroLLM follows a hexagonal architecture. The core domain (Message, Contract, Registry) has no framework dependencies. The provider layer implements bidirectional normalization behind ProviderInterface, so adding a new provider means implementing a single class without touching application code. The agentic layer (Agent, Skill, Orchestration) composes on top of the provider layer, using the same normalized types. Framework integrations (Laravel, Slim) are thin adapters that wire the core into their respective DI containers and lifecycle hooks.

Exception Handling

An agent only executes the tools it was given — the ones resolved from its skills plus AgentConfig::tools. If a model names a tool outside that set, the agent does not throw: it returns a ToolResult in error state so the model can correct itself, and the loop continues. Tools passed through AgentConfig::tools do not need to be registered in the global ToolRegistry as well.

Testing

composer test runs the unit suite only: 225 tests backed by hand-authored fixtures, no network. It passes on a clean checkout with no credentials.

The integration suite exercises a locally running Ollama and self-skips when it is unreachable, so it never fails a machine that does not have it. Capabilities no local provider can serve — image generation, TTS, STT, reranking, and the provider-specific end-to-end paths — are present as explicitly skipped tests, so the coverage gap shows up in the output instead of being silently absent.

Note that the integration suite talks to real models and can take tens of minutes depending on the machine and which models are warm.

License

MIT — see LICENSE file.

Author

Raul Antonio Salazar Torres — [email protected]