Gemini PHP for Laravel wraps the Gemini API in a facade

A facade and a config file in front of the Gemini API

The package describes itself as a community maintained PHP API client for the Gemini AI API, with a facade, configuration and testing helpers for Laravel. That trio is the actual scope. It is not a new Gemini implementation and it does not try to abstract the model surface behind a different vocabulary.

The important structural fact is that this is a wrapper. It sits on top of google-gemini-php/client, and the readme points readers to that repository for more information. Anything you read in the client documentation about request handling, retry behaviour or the shape of the underlying responses applies here too, and when a question comes up about behaviour, the client repository is the place to look rather than this one.

The audience is Laravel developers who want model calls to look like the rest of their application. A facade means a static call in a controller, a published config file means the model name and the key live in configuration rather than in code, and a fake client means tests do not need network access. The features listed cover text, image, video, audio and document input, streaming, chats, structured output, function calling, built-in tools such as Google Search, Google Maps, URL context, File Search and code execution, image and speech generation, thinking models, files, context caching, file search stores, embeddings and models.

Composer, one artisan command, and a published config file

Installation is a Composer requirement followed by a single artisan command:

composer require google-gemini-php/laravel

php artisan gemini:install

That second command does the setup work. According to the readme it creates a config/gemini.php configuration file and adds an empty GEMINI_API_KEY variable to your .env and .env.example files, so the file the framework loads at boot already exists once the command finishes.

The key itself comes from Google AI Studio, and two further environment variables are optional:

GEMINI_BASE_URL=
GEMINI_REQUEST_TIMEOUT=

The base URL variable is the interesting one for anyone behind a gateway or proxy, and the timeout variable is the one to set before a long running generation blocks a request. The key is written as an empty assignment:

GEMINI_API_KEY=

The prerequisites are PHP 8.2 or later and Laravel 9, 10, 11, 12 or 13. The readme notes that the features it documents need version 2.8 or later of google-gemini-php/client, and that on PHP 8.1 Composer installs version 2.7 of the client instead, which means the documented features are not all available on the older runtime.

Version 2.0 locks the package to the Gemini v1beta API

The upgrade section is short but it carries the sharpest constraint in the package. Starting with the 2.0 release this package works only with the Gemini v1beta API, with a link to the API versions documentation. If your application is written against a different API version, moving to 2.0 is not a routine upgrade, it is a migration of the request surface.

The command for the upgrade is:

composer require google-gemini-php/laravel:^2.0

The 2.0 release is also where a large block of features arrived, according to the readme: structured output, system instructions, file uploads, function calling, code execution, grounding with Google Search, cached content, thinking model configuration and speech model configuration. The practical reading is that 2.0 is the release where the package stopped being a thin text generation helper and started exposing most of the Gemini API surface through Laravel.

The readme also warns that there may be other breaking changes not listed. That sentence matters more than it looks, since the feature list above is presented as the headline of the release and the same document admits the list is incomplete.

The ModelType enum is deprecated and the named model helpers go with it

One deprecation is spelled out in detail. The \Gemini\Enums\ModelType enum has been deprecated and will be removed in the next major version, and the Gemini::geminiPro() and Gemini::geminiFlash() methods have been deprecated along with it.

The replacement is the Gemini::generativeModel() method with the model string passed in directly. Methods that previously accepted a ModelType enum now accept a BackedEnum, and the readme suggests implementing your own enum for convenience rather than relying on the library's. The trade-off is deliberate: the package keeps a thin generic type so the model name can live in your own code, and it pushes the enumeration of which models exist to the application, where a model catalogue changes faster than a major release.

For an application that already has a model registry, that is a reasonable design. For a codebase that sprinkled Gemini::geminiPro() calls across controllers, the 2.0 upgrade is a mechanical sweep of every call site, and doing it before the enum is removed avoids doing it twice.

The usage surface runs from generateContent to function calling

The usage section is organised around one entry point. The Gemini facade sends a prompt to a model:

use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.5-flash')->generateContent('Hello');

The table of contents shows how much surface sits behind that call. There are separate sections for text only input, text and image, text and video, media resolution, image generation, multi-turn conversations through a chat, chat with streaming, streaming generate content, structured output, function calling, code execution, grounding with Google Search, grounding with Google Maps, grounding with File Search, URL context, server-side tool invocations, system instructions, speech generation, thinking mode, counting tokens and response metadata.

Beyond content generation there are whole resource groups with their own operations. Files cover upload, list, metadata and delete. Cached content covers create, list, get, update, delete and then the call that uses the cached content. File search stores have create, get, list and delete, file search documents have upload, import, get operation, get, list and delete, and there are dedicated sections for embeddings and for listing or getting models.

That is a lot of surface area, and it explains why the wrapper exists. It also means the readme reads more like a reference manual than a tutorial, so a reader who wants one working example has to find it among the headings.

A shipped fake client keeps tests off the network

The package ships with a fake client for testing, which is listed among the covered features and is one of the three things the description says the package adds for Laravel beyond the underlying client.

The value of that is straightforward. Gemini calls are slow, cost money and depend on a remote service being up, so a test suite that hits the real API is a test suite that is slow, flaky and occasionally billable. A fake client lets you assert on the shape of a request and the handling of a response without either.

The readme's table of contents also gives troubleshooting its own section with three subsections, error handling, empty responses and timeout, which tells you these are the three places teams usually get stuck. The timeout entry pairs with the GEMINI_REQUEST_TIMEOUT environment variable, and the empty response entry is worth reading before you write your own retry logic, since an empty result may mean the request was blocked rather than that the model had nothing to say.

Where the wrapper stops and the client package begins

The clearest limitation is structural. This repository is a Laravel wrapper, and the readme says so in as many words, so any capability that the underlying client does not expose is out of reach here no matter how the facade is used. When you need to know what an option does or whether a response field is populated, you are reading google-gemini-php/client documentation.

There is a second limitation that matters for version planning. The 2.0 line ties the package to the v1beta API, and the readme already warns that the breaking change list for that release may not be complete. Any application that has to move to a different API version later has a migration waiting, and the package will not smooth that over for you.

A third is the runtime floor. The package supports Laravel 9 through 13 and PHP 8.2 or later, and the documented feature set needs client version 2.8 or later. On PHP 8.1 Composer resolves to client version 2.7, so the features in the readme are quietly unavailable. Applications on older PHP are not blocked from installing the package, they are just reading a manual for a version they do not have.

Community maintenance, an MIT licence and a recent release cadence

The package is explicitly community maintained rather than published by Google, and the repository carries a CHANGELOG.md, CONTRIBUTING.md and a LICENSE.md. The licence is MIT, which is permissive and carries no copyleft requirement on code that uses the package, though your own obligations are a question for your legal team rather than for this repository.

Release history shows recent activity. Version 2.0.3 was published on 2025-11-25, version 2.0.4 on 2026-04-12 and version 2.0.5 on 2026-10-12, and the last push was on 2026-10-12. The gap between 2.0.3 and 2.0.4 was months and the gap to 2.0.5 was longer, so the cadence is patch releases rather than frequent ones.

The repository layout supports the usual Laravel package conventions, with src/ for the implementation, config/ for the published configuration, resources/ for translations or assets, tests/ and a phpunit.xml for the suite, and phpstan.neon for static analysis. The presence of static analysis configuration in a package that ships a facade over a generated client is a good sign for the type safety of the wrapper, and the CHANGELOG.md is the file to check before a version bump.

Editorial conclusion

Use google-gemini-php/laravel when your Laravel application needs Gemini calls from controllers, jobs or services and you want configuration, a facade and a fake client for tests without wiring the HTTP client yourself. Skip it if you need the v1 API surface or if you are not on PHP 8.2 with Laravel 9 through 13, because the package supports neither. Before upgrading, move off the deprecated Gemini::geminiPro() and Gemini::geminiFlash() calls to Gemini::generativeModel(), note that 2.0 removed support for API versions other than v1beta, and check the client repository google-gemini-php/client, since the feature set you actually call lives there.

Frequently asked questions

Official sources

1. google-gemini-php/laravel on GitHub
2. Issues
3. License: MIT
4. README
5. Releases