deepseek-php/deepseek-php-client: a PHP client for DeepSeek's V4 models

What the DeepSeek PHP client actually replaces

Most PHP code that talks to an AI provider ends up as a curl call with a hand-built JSON body, plus an error path nobody wrote. This package replaces that with a builder object. You call DeepSeekClient::build() with an API key, chain the options you care about, and call run(). The README describes the goal as a PHP-first interface with a fluent builder pattern and PSR-18 compliant HTTP client integration, which in practice means the transport is swappable and the request construction is not your problem.

The audience is narrow and clear. It is for PHP developers on PHP 8.1 or newer who are building a chat, summarisation, code or extraction feature against DeepSeek's hosted API and who would rather add one Composer dependency than maintain an HTTP wrapper. It is not a local inference library. Nothing in the repository runs a model; every call leaves your process and goes to https://api.deepseek.com. If your requirement is to keep prompts on your own hardware, this package is the wrong layer entirely.

The builder, the defaults and the two HTTP backends

The mechanism is a static factory that returns a mutable client. DeepSeekClient::build() accepts apiKey, baseUrl, timeout and clientType, and the README shows clientType as either 'guzzle' (the default) or 'symfony'. That choice is the most interesting design decision in the package: rather than bundling one HTTP implementation and forcing it on you, it lets an application that already has a Symfony HttpClient wired into its container reuse that client. For a Laravel or Symfony codebase that matters, because it keeps the AI calls inside the same middleware, retry and logging stack as the rest of your outbound traffic.

The defaults are worth reading before you ship anything. According to the README, if you never call withModel() the client sends no model field at all and lets the API decide. Temperature defaults to 1.3, which the README labels TemperatureValues::GENERAL_CONVERSATION, max tokens defaults to 4096, and the response format defaults to text. A temperature of 1.3 is high for anything that needs to be reproducible, so treat the default as tuned for conversational output and set it explicitly for extraction or classification work.

Streaming is exposed as a chainable withStream() call. The README lists streaming as a feature and shows it in the advanced example, but it does not document the shape of the streamed response, so budget time to inspect what run() returns when streaming is enabled rather than assuming a particular callback or iterator.

Installing it and making a first call

Installation is a single Composer command. The package requires PHP 8.1 or newer, and the README gives no other system requirement.

composer require deepseek-php/deepseek-php-client

The quickest working call is two statements. The README calls this the two-line start: build the client with your key, pass a prompt to query(), and call run(). The return value is echoed directly, which tells you run() resolves to something string-castable rather than a decoded array.

use DeepSeek\DeepSeekClient;

$response = DeepSeekClient::build('your-api-key')
    ->query('Explain quantum computing in simple terms')
    ->run();

echo $response;

Once that works, pin the model explicitly. The README exposes model identifiers as enum cases, so you reference Models::V4_PRO->value rather than typing a string. The same example shows setTemperature(), setMaxTokens() and setResponseFormat() chained before the query.

use DeepSeek\DeepSeekClient;
use DeepSeek\Enums\Models;

$response = DeepSeekClient::build(apiKey: 'your-api-key', timeout: 30)
    ->withModel(Models::V4_PRO->value)
    ->setTemperature(1.2)
    ->setMaxTokens(8192)
    ->setResponseFormat('text')
    ->query('Explain quantum computing in simple terms')
    ->run();

If you want to confirm which models your key can reach before writing feature code, the client has getModelsList(). The README shows it returning an object with a data array of model entries, each carrying id, object and owned_by. That is a cheap first call to make in a new environment.

JSON mode fails unless your prompt says json

This is the sharpest edge in the package and the README flags it with a warning section of its own. If you set the response format to json_object and your prompt does not contain the word json in some form, the DeepSeek API rejects the request. The error the README quotes is: Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'.

The README shows both sides. Setting setResponseFormat('json_object') on the prompt Explain quantum computing in simple terms is listed as incorrect. Adding an instruction such as Respond in valid JSON format to the same prompt is listed as correct. The README also suggests supplying a JSON example or stating explicitly that the model should respond only in valid JSON.

What the README does not do is turn that rule into something the client enforces. There is no validation step described that checks your prompt before the request goes out, so a missing json word surfaces as an API error at runtime rather than a local exception. If you build a wrapper around this client for structured extraction, that check belongs in your wrapper, not in the SDK.

Model deprecations you inherit by adopting this package

The README is unusually direct about lifecycle. Models::CHAT, Models::CODER, Models::R1 and Models::R1Zero are marked deprecated and scheduled for removal in v3.0.0. Separately, the deepseek-chat and deepseek-reasoner aliases are described as retiring from the DeepSeek API on 2026-07-24. Those are two different clocks: the constants disappear when the PHP package ships v3.0.0, and the aliases disappear from the service on a fixed calendar date.

The current models are Models::V4_PRO, described as a 1.6T parameter model with 49B active and a maximum of 384K output tokens, and Models::V4_FLASH, described as 284B with 13B active and the same output ceiling. The README attributes 1M-token context windows and thinking and non-thinking modes to the V4 line. Those figures come from the project's own documentation and are not independently verified here.

If your codebase was written against the older constants, the repository ships a MIGRATION.md for the 1.x to 2.x jump, and the README points to CHANGELOG.md for release notes. Read both before upgrading a production application, because a constant that no longer exists is a fatal error, not a deprecation notice.

Where it is the wrong tool, and what to use instead

The package is a thin client for one vendor's hosted API. If you need to call several providers behind one interface, or swap providers without touching call sites, this is not that abstraction. The README positions the project under a php-openai-alternative topic, but the API surface is DeepSeek-shaped: model enums, a response format flag, a models list call. There is no provider interface to implement.

A genuine alternative is the official OpenAI PHP client, openai-php/client, which targets OpenAI's API. The difference is not quality, it is shape. The OpenAI client has a resource-oriented API where you construct a client once and then reach into $client->chat()->create() with named resources and typed response objects, and it is maintained by a dedicated organisation with a longer release history. This package uses a static factory plus a mutable builder, so the client and the request are the same object and each chain ends in run(). If your team already standardises on the OpenAI client's resource style and you are adding DeepSeek as a second provider, the two styles will sit awkwardly side by side. If DeepSeek is your only provider and you want the shortest path from a key to a response, the builder is less ceremony.

Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-05-24, which is roughly four months before this article, and the most recent release, v2.1.0, is dated 2026-05-24 as well. The two releases before it, v2.0.5 and v2.0.6, both landed on 2025-07-16. That is a gap of about ten months between the 2.0.6 and 2.1.0 releases, so plan for a project that moves in bursts rather than continuously. The README states that test coverage is coming in v2.1, and the repository does contain phpstan.neon, phpunit.xml and a tests directory, with ./vendor/bin/pest given as the test command. Static analysis and a test suite are configured; what the README does not claim is a coverage figure.

The licence is MIT, declared in LICENSE.md and in the README badge. MIT is permissive: it allows commercial and closed-source use with the copyright notice and permission notice retained. That is a statement about the licence text, not legal advice, and if your organisation has a policy on community-maintained dependencies, the review belongs with your legal team.

The upgrade cost is concentrated in two places. Model constants are being removed in v3.0.0, so any call site using Models::CHAT, Models::CODER, Models::R1 or Models::R1Zero will need rewriting. And the README points to MIGRATION.md for v1.x to v2.x breaking changes, which implies the 1.x to 2.x transition was not drop-in. Budget for both if you are adopting an older codebase or planning a version jump.

Editorial conclusion

Adopt deepseek-php/deepseek-php-client if you are on PHP 8.1+ and want DeepSeek calls expressed as a chainable builder rather than hand-rolled curl, and if you can accept a community-maintained client whose last push was on 2026-05-24. Do not adopt it if your application still depends on the deepseek-chat or deepseek-reasoner aliases, or if you need a stable 1.x API surface, because the README states the legacy model constants are deprecated and will be removed in v3.0.0. Before writing production code, verify two things against the live API: that Models::V4_PRO and Models::V4_FLASH are the identifiers your account accepts, and that every json_object call you write contains the word json in the prompt, since the API rejects the request otherwise.

Frequently asked questions

Official sources

1. deepseek-php/deepseek-php-client on GitHub
2. Issues
3. License: MIT
4. README
5. Releases