Gemini PHP for Laravel

https://github.com/google-gemini-php/laravel
Admin
A community-maintained PHP API client that allows interaction with the Gemini AI API, providing...
Tokens:39,407
Snippets:315
Trust Score:6
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Standard install command

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/install-command.md

Run the standard installation for Gemini for Laravel. It creates config/gemini.php, adds GEMINI_API_KEY to .env and .env.example, and displays repository and documentation links.

```bash
php artisan gemini:install
```

--------------------------------

### List Uploaded Files

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Lists uploaded files in the project with pagination. The example iterates over the files and prints their details, then retrieves the next page if a nextPageToken is available.

```php
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::files()->list(pageSize: 10);

foreach ($response->files as $file) {
    echo "Name: {$file->name}\n";
    echo "Display Name: {$file->displayName}\n";
    echo "Size: {$file->sizeBytes} bytes\n";
    echo "MIME Type: {$file->mimeType}\n";
    echo "State: {$file->state->value}\n";
    echo "---\n";
}

// Get next page if available
if ($response->nextPageToken) {
    $nextPage = Gemini::files()->list(pageSize: 10, nextPageToken: $response->nextPageToken);
}
```

--------------------------------

### Install dev dependencies with composer install

Source: https://github.com/google-gemini-php/laravel/blob/main/CONTRIBUTING.md

Run after cloning your fork to install development dependencies required for contributing.

```bash
composer install
```

--------------------------------

### Expected side effects output

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/install-command.md

Output shown after running the standard install command, listing created files and added environment variables.

```text
INFO  Installing Gemini for Laravel.
  config/gemini.php ........... File created.
  .env ........................ GEMINI_API_KEY variable added.
  .env.example ................ GEMINI_API_KEY variable added.
  Repository .................. https://github.com/google-gemini-php/laravel
  Gemini PHP Docs ............. https://github.com/google-gemini-php/client#readme
```

--------------------------------

### System instructions with withSystemInstruction

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Set the model's role and personality using Content::parse. The example uses a pirate-style instruction and outputs a response that follows that style. Combine with other features like GenerationConfig for JSON responses.

```php
use Gemini\Data\Content;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withSystemInstruction(
        Content::parse('You are a helpful assistant that always responds in the style of a pirate. Use nautical terms and pirate slang in all your responses.')
    )
    ->generateContent('Tell me about PHP programming');

echo $response->text();
// Ahoy there, matey! Let me tell ye about this fine treasure called PHP programming...
```

--------------------------------

### Non-interactive install command

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/install-command.md

Run the install command without interaction for CI environments. The prompt is skipped and no browser is opened, but config and env keys are still processed.

```bash
php artisan gemini:install --no-interaction
```

--------------------------------

### Text-and-video input example

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Processes video content using an uploaded file. Uses UploadedFile with fileUri from an uploaded file and MimeType::VIDEO_MP4. The model returns a description of the video.

```php
use Gemini\Data\UploadedFile;
use Gemini\Enums\MimeType;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->generateContent([
        'What is this video?',
        new UploadedFile(
            fileUri: $meta->uri, // the URI of the uploaded file, e.g. https://generativelanguage.googleapis.com/v1beta/files/abc-123
            mimeType: MimeType::VIDEO_MP4
        )
    ]);

$result->text(); //  The video shows...
```

--------------------------------

### Get file search store with Gemini::fileSearchStores()->get()

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Retrieves a specific file search store by name, e.g., 'fileSearchStores/my-search-store'. Prints the name and display name.

```php
use Gemini\Laravel\Facades\Gemini;

$fileSearchStore = Gemini::fileSearchStores()->get('fileSearchStores/my-search-store');

echo "Name: {$fileSearchStore->name}\n";
echo "Display Name: {$fileSearchStore->displayName}\n";
```

--------------------------------

### Text-and-image input example

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Generates responses by providing both text prompts and images. Uses Blob with MimeType::IMAGE_JPEG and base64-encoded image data from a URL. The model returns a description of the image.

```php
use Gemini\Data\Blob;
use Gemini\Enums\MimeType;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->generateContent([
        'What is this picture?',
        new Blob(
            mimeType: MimeType::IMAGE_JPEG,
            data: base64_encode(
                file_get_contents('https://storage.googleapis.com/generativeai-downloads/images/scones.jpg')
            )
        )
    ]);

$result->text(); //  The picture shows a table with a white tablecloth. On the table are two cups of coffee, a bowl of blueberries, a silver spoon, and some flowers. There are also some blueberry scones on the table.
```

--------------------------------

### Publish Gemini Laravel config with artisan vendor:publish or gemini:install

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/configuration.md

Use `php artisan vendor:publish --provider="Gemini\Laravel\ServiceProvider"` to publish the package's configuration, or run `php artisan gemini:install` once to perform the same setup. The `gemini:install` command is a one-time alternative.

```bash
php artisan vendor:publish --provider="Gemini\Laravel\ServiceProvider"
# or, once:
php artisan gemini:install
```

--------------------------------

### GEMINI_API_KEY added to .env

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/install-command.md

The .env file gains an empty GEMINI_API_KEY variable after installation.

```text
GEMINI_API_KEY=
```

--------------------------------

### Grounding with Google Maps using GoogleMaps tool

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Uses the GoogleMaps tool with a RetrievalConfig to enable location-based responses. The example sets latitude and longitude coordinates and enables the widget. The model output references nearby points of interest.

```php
use Gemini\Data\GoogleMaps;
use Gemini\Data\RetrievalConfig;
use Gemini\Data\Tool;
use Gemini\Data\ToolConfig;
use Gemini\Laravel\Facades\Gemini;

$tool = new Tool(
    googleMaps: new GoogleMaps(enableWidget: true)
);

$toolConfig = new ToolConfig(
    retrievalConfig: new RetrievalConfig(
        latitude: 40.758896,
        longitude: -73.985130
    )
);

$response = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withTool($tool)
    ->withToolConfig($toolConfig)
    ->generateContent('Find coffee shops near me');

echo $response->text();
// (Model output referencing coffee shops)
```

--------------------------------

### Text-only input example

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Generates a response from the model given a text prompt. Uses the Gemini facade with model 'gemini-2.5-flash' and accesses the result text.

```php
use Gemini\Laravel\Facades\Gemini;

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

$result->text(); // Hello! How can I assist you today?
```

--------------------------------

### Usage from the install command with View::renderUsing and View::render

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/support-view.md

Shows how InstallCommand uses the View helper: sets the output via renderUsing, then renders 'components.badge' and 'components.two-column-detail' with data arrays. The output style implements OutputInterface.

```php
use Gemini\Laravel\Support\View;

View::renderUsing($this->output); // Illuminate\Console\OutputStyle implements OutputInterface

View::render('components.badge', [
    'type' => 'INFO',
    'content' => 'Installing Gemini for Laravel.',
]);

View::render('components.two-column-detail', [
    'left' => 'config/gemini.php',
    'right' => 'File created.',
]);
```

--------------------------------

### Install Gemini Laravel package via Composer

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Use Composer to install the google-gemini-php/laravel package. Requires PHP 8.2+ and Laravel 9, 10, 11, 12, or 13.

```bash
composer require google-gemini-php/laravel
```

--------------------------------

### Standard registration via Composer and artisan

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/service-provider.md

No manual registration is needed; Composer's Laravel plugin discovers the provider. Run these commands to install and set up the package.

```bash
composer require google-gemini-php/laravel
php artisan gemini:install
```

--------------------------------

### InstallCommand class declaration

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/install-command.md

The artisan command `gemini:install` prepares the Gemini client for use. It publishes the config file, appends `GEMINI_API_KEY=` to `.env` / `.env.example`, and prints status output. The command has no constructor arguments and is resolved through Laravel's container.

```php
class InstallCommand extends Command
{
    private const LINKS = [
        'Repository' => 'https://github.com/google-gemini-php/laravel',
        'Gemini PHP Docs' => 'https://github.com/google-gemini-php/client#readme',
    ];

    private const FUNDING_LINKS = [
        'Sponsor Fatih' => 'https://github.com/sponsors/aydinfatih',
    ];

    protected $signature = 'gemini:install';

    protected $description = 'Prepares the Gemini client for use.';

    public function handle(): void
    {
        // ...
    }
}
```

--------------------------------

### System instructions combined with GenerationConfig for JSON output

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Combine system instructions with a GenerationConfig that sets responseMimeType to APPLICATION_JSON to force JSON responses. The example instructs the model to act as a JSON API and then prints the JSON response using $response->json().

```php
use Gemini\Data\Content;
use Gemini\Data\GenerationConfig;
use Gemini\Enums\ResponseMimeType;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withSystemInstruction(
        Content::parse('You are a JSON API. Always respond with valid JSON objects. Be concise.')
    )
    ->withGenerationConfig(
        new GenerationConfig(responseMimeType: ResponseMimeType::APPLICATION_JSON)
    )
    ->generateContent('Give me information about the Eiffel Tower');

print_r($response->json());
```

--------------------------------

### Get File Metadata

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Retrieves metadata for a specific file. The metadataGet method accepts a file ID, file name, or full URI. The example shows all three forms and then prints the file's display name, state, and size.

```php
use Gemini\Laravel\Facades\Gemini;

$meta = Gemini::files()->metadataGet('abc-123');
// or use the name
$meta = Gemini::files()->metadataGet('files/abc-123');
// or use the full URI
$meta = Gemini::files()->metadataGet($file->uri);

echo "File: {$meta->displayName}\n";
echo "State: {$meta->state->value}\n";
echo "Size: {$meta->sizeBytes} bytes\n";
```

--------------------------------

### Fake chat with startChat() and assertFunctionCalled

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Chats started with startChat() work with the fake. Each message is sent as a generateContent (or streamGenerateContent) request with the full history, consuming the next fake response. Use assertFunctionCalled to verify the startChat call.

```php
use Gemini\Laravel\Facades\Gemini;
use Gemini\Responses\GenerativeModel\GenerateContentResponse;

Gemini::fake([
    GenerateContentResponse::fake(),
    GenerateContentResponse::fake(),
]);

$chat = Gemini::generativeModel(model: 'gemini-2.5-flash')->startChat();
$chat->sendMessage('Hello');
$chat->sendMessage('How are you?');

Gemini::generativeModel(model: 'gemini-2.5-flash')->assertFunctionCalled(function (string $method) {
    return $method === 'startChat';
});

Gemini::generativeModel(model: 'gemini-2.5-flash')->assertSent(function (string $method, array $parameters) {
    return $method === 'generateContent' &&
        count($parameters) === 3; // Hello, the model's answer, How are you?
});
```

--------------------------------

### Fake a failing request with a Throwable

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

To test a failing request, provide a Throwable as the response. The example uses ErrorException with a message and status; the exception will be thrown when the request is made.

```php
use Gemini\Exceptions\ErrorException;
use Gemini\Laravel\Facades\Gemini;

Gemini::fake([
    new ErrorException([
        'message' => 'The model `gemini-basic` does not exist',
        'status' => 'INVALID_ARGUMENT',
        'code' => 400,
    ]),
]);

// the `ErrorException` will be thrown
Gemini::generativeModel(model: 'gemini-2.5-flash')->generateContent('test');
```

--------------------------------

### Code Execution with Gemini (PHP)

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Enables the Gemini model to generate and run code automatically. The example sends a prompt asking for the sum of the first 50 prime numbers and then iterates over the response parts to print the executed code and its result.

```php
use Gemini\Data\CodeExecution;
use Gemini\Data\Tool;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withTool(new Tool(codeExecution: CodeExecution::from()))
    ->generateContent('What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.');

// Access the executed code and results
foreach ($response->parts() as $part) {
    if ($part->executableCode !== null) {
        echo "Language: " . $part->executableCode->language->value . "\n";
        echo "Code: " . $part->executableCode->code . "\n";
    }
    if ($part->codeExecutionResult !== null) {
        echo "Outcome: " . $part->codeExecutionResult->outcome->value . "\n";
        echo "Output: " . $part->codeExecutionResult->output . "\n";
    }
}
```

--------------------------------

### Upload a File to Gemini Storage

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Uploads a file to Gemini storage and waits for processing to complete. The example uploads a video, polls the file metadata until the state is complete, and prints the metadata. If the upload fails, it outputs an error and exits.

```php
use Gemini\Enums\FileState;
use Gemini\Enums\MimeType;
use Gemini\Laravel\Facades\Gemini;

$files = Gemini::files();
echo "Uploading\n";
$meta = $files->upload(
    filename: 'video.mp4',
    mimeType: MimeType::VIDEO_MP4,
    displayName: 'Video'
);
echo "Processing";
do {
    echo ".";
    sleep(2);
    $meta = $files->metadataGet($meta->uri);
} while (!$meta->state->complete());
echo "\n";

if ($meta->state == FileState::Failed) {
    die("Upload failed:\n" . json_encode($meta->toArray(), JSON_PRETTY_PRINT));
}

echo "Processing complete\n" . json_encode($meta->toArray(), JSON_PRETTY_PRINT);
echo "\n{$meta->uri}";
```

--------------------------------

### Multi-turn chat with history using startChat and sendMessage

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Starts a chat session with initial history using Content::parse and Role::MODEL. Each sendMessage call sends the full history; the response text is echoed and the updated history is available via $chat->history.

```php
use Gemini\Data\Content;
use Gemini\Enums\Role;
use Gemini\Laravel\Facades\Gemini;

$chat = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->startChat(history: [
        Content::parse(part: 'The stories you write about what I have to say should be one line. Is that clear?'),
        Content::parse(part: 'Yes, I understand. The stories I write about your input should be one line long.', role: Role::MODEL)
    ]);

$response = $chat->sendMessage('Create a story set in a quiet village in 1600s France');
echo $response->text(); // Amidst rolling hills and winding cobblestone streets, the tranquil village of Beausoleil whispered tales of love, intrigue, and the magic of everyday life in 17th century France.

$response = $chat->sendMessage('Rewrite the same story in 1600s England');
echo $response->text(); // In the heart of England's lush countryside, amidst emerald fields and thatched-roof cottages, the village of Willowbrook unfolded a tapestry of love, mystery, and the enchantment of ordinary days in the 17th century.

$chat->history; // array<Content>
```

--------------------------------

### Set media resolution for request or part

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Configures tokenization quality for images, videos, and documents. Uses GenerationConfig::$mediaResolution for the whole request or Part::$mediaResolution for a single part. MEDIA_RESOLUTION_ULTRA_HIGH is only available per part. This example sets a per-part resolution to MEDIA_RESOLUTION_HIGH.

```php
use Gemini\Data\Blob;
use Gemini\Data\Content;
use Gemini\Data\Part;
use Gemini\Data\PartMediaResolution;
use Gemini\Enums\MimeType;
use Gemini\Enums\PartMediaResolutionLevel;
use Gemini\Enums\Role;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->generateContent(new Content(
        parts: [
            new Part(
                inlineData: new Blob(mimeType: MimeType::IMAGE_PNG, data: base64_encode(file_get_contents('chart.png'))),
                mediaResolution: new PartMediaResolution(level: PartMediaResolutionLevel::MEDIA_RESOLUTION_HIGH),
            ),
            new Part(text: 'Read the values from this chart.'),
        ],
        role: Role::USER,
    ));

$result->text();
```

--------------------------------

### chat

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/facade-gemini.md

Starts a multi-turn chat session. Returns a ChatSession resource for conversational interactions.

```APIDOC
## chat

### Description
Starts a multi-turn chat session. Returns a ChatSession resource for conversational interactions.

### Method
Facade static method

### Signature
`chat(BackedEnum|string $model)`

### Parameters
- **model** (BackedEnum|string) - Required - The model identifier for the chat session.

### Returns
`Gemini\Resources\ChatSession`
```

--------------------------------

### Assert requests sent with assertSent and assertNotSent

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

After sending requests, use assertion methods to verify expected requests. The example shows various forms: resource-specific, model-specific, count-based, and global assertions. Comments indicate the intent of each assertion.

```php
// assert list models request was sent
use Gemini\Laravel\Facades\Gemini;
use Gemini\Resources\GenerativeModel;
use Gemini\Resources\Models;

Gemini::models()->assertSent(callback: function ($method) {
    return $method === 'list';
});
// or
Gemini::assertSent(resource: Models::class, callback: function ($method) {
    return $method === 'list';
});

Gemini::generativeModel(model: 'gemini-2.5-flash')->assertSent(function (string $method, array $parameters) {
    return $method === 'generateContent' &&
        $parameters[0] === 'Hello';
});
// or
Gemini::assertSent(resource: GenerativeModel::class, model: 'gemini-2.5-flash', callback: function (string $method, array $parameters) {
    return $method === 'generateContent' &&
        $parameters[0] === 'Hello';
});

// assert 2 generative model requests were sent
Gemini::assertSent(resource: GenerativeModel::class, model: 'gemini-2.5-flash', callback: 2);
// or
Gemini::generativeModel(model: 'gemini-2.5-flash')->assertSent(2);

// assert no generative model requests were sent
Gemini::assertNotSent(resource: GenerativeModel::class, model: 'gemini-2.5-flash');
// or
Gemini::generativeModel(model: 'gemini-2.5-flash')->assertNotSent();

// assert no requests were sent
Gemini::assertNothingSent();
```

--------------------------------

### Function Declaration with JSON Schema Array (PHP)

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Alternative way to define function parameters using a JSON Schema array instead of a Schema object. This example declares a 'get_weather' function with city and unit parameters.

```php
use Gemini\Data\FunctionDeclaration;

new FunctionDeclaration(
    name: 'get_weather',
    description: 'Returns the weather for a city.',
    parametersJsonSchema: [
        'type' => 'object',
        'properties' => [
            'city' => ['type' => 'string'],
            'unit' => ['type' => 'string', 'enum' => ['celsius', 'fahrenheit']],
        ],
        'required' => ['city'],
    ],
);
```

--------------------------------

### Configure Generation and Safety Settings

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Shows how to configure generation parameters and safety settings for a Gemini model request. Use SafetySetting with HarmCategory and HarmBlockThreshold to control harmful content, and GenerationConfig to set stop sequences, token limits, and sampling parameters. The example applies two safety settings and a generation config to a generateContent call.

```php
use Gemini\Data\GenerationConfig;
use Gemini\Data\SafetySetting;
use Gemini\Enums\HarmBlockThreshold;
use Gemini\Enums\HarmCategory;
use Gemini\Laravel\Facades\Gemini;

$safetySettingDangerousContent = new SafetySetting(
    category: HarmCategory::HARM_CATEGORY_DANGEROUS_CONTENT,
    threshold: HarmBlockThreshold::BLOCK_ONLY_HIGH
);

$safetySettingHateSpeech = new SafetySetting(
    category: HarmCategory::HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold::BLOCK_ONLY_HIGH
);

$generationConfig = new GenerationConfig(
    stopSequences: [
        'Title',
    ],
    maxOutputTokens: 800,
    temperature: 1,
    topP: 0.8,
    topK: 10
);

$response = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withSafetySetting($safetySettingDangerousContent)
    ->withSafetySetting($safetySettingHateSpeech)
    ->withGenerationConfig($generationConfig)
    ->generateContent('Write a story about a magic backpack.');
```

--------------------------------

### ServiceProvider class declaration with register, boot, and provides methods

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/service-provider.md

The service provider is auto-discovered by Laravel and deferred until services are resolved. It registers the Gemini client as a singleton, aliases it, publishes the config file, and registers the install command. The class is final and cannot be subclassed.

```php
final class ServiceProvider extends BaseServiceProvider implements DeferrableProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        $this->app->singleton(ClientContract::class, static function (): Client {
            $apiKey = config('gemini.api_key');

            if (! is_string($apiKey)) {
                throw MissingApiKey::create();
            }

            $baseURL = config('gemini.base_url');
            if (isset($baseURL) && ! is_string($baseURL)) {
                throw new InvalidArgumentException('Invalid Gemini API base URL.');
            }

            /** @var int $timeout */
            $timeout = config('gemini.request_timeout', 30);

            $client = Gemini::factory()
                ->withApiKey(apiKey: $apiKey)
                ->withHttpClient(client: new GuzzleClient(['timeout' => (int) $timeout]));

            if (! empty($baseURL)) {
                $client->withBaseUrl(baseUrl: $baseURL);
            }

            return $client->make();
        });

        $this->app->alias(ClientContract::class, 'gemini');
        $this->app->alias(ClientContract::class, Client::class);
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        if ($this->app->runningInConsole()) {
            $this->publishes([
                __DIR__.'/../config/gemini.php' => config_path('gemini.php'),
            ]);

            $this->commands([
                InstallCommand::class,
            ]);
        }
    }

    /**
     * Get the services provided by the provider.
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [
            Client::class,
            ClientContract::class,
            'gemini',
        ];
    }
}
```

--------------------------------

### Triggered by a missing key example

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/missing-api-key.md

Example of the exception being thrown when config('gemini.api_key') is null. The try-catch catches MissingApiKey and echoes the message.

```php
// config/gemini.php published but api_key left empty (env not set)
// config('gemini.api_key') === null → MissingApiKey is thrown on first use:

use Gemini\Laravel\Facades\Gemini;

try {
    Gemini::generativeModel(model: 'gemini-2.5-flash')->generateContent('Hello');
} catch (\Gemini\Laravel\Exceptions\MissingApiKey $e) {
    echo $e->getMessage();
    // "The Gemini API Key is missing. Please publish the [gemini.php] configuration file and set the [api_key]."
}
```

--------------------------------

### Get File Search Document

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Retrieves a specific file search document by its name.

```APIDOC
## Get File Search Document

### Description
Retrieves a specific file search document by its name.

### Method
Gemini::fileSearchStores()->getDocument()

### Parameters
- **documentName** (string) - Required - The full name of the document.

### Request Example
```php
use Gemini\Laravel\Facades\Gemini;

$fileSearchDocument = Gemini::fileSearchStores()->getDocument('fileSearchStores/my-search-store/documents/my-document');

echo "Name: {$fileSearchDocument->name}\n";
echo "Display Name: {$fileSearchDocument->displayName}\n";
echo "State: {$fileSearchDocument->state?->value}\n";
```

### Response
Returns a file search document object with `name`, `displayName`, and `state` properties.
```

--------------------------------

### Publish configuration manually

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/service-provider.md

Use this artisan command to manually publish the package configuration.

```bash
php artisan vendor:publish --provider="Gemini\Laravel\ServiceProvider"
```

--------------------------------

### Get Operation

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Polls a long-running operation until it is done. Useful for checking the status of upload and import operations.

```APIDOC
## Get Operation

### Description
Polls a long-running operation until it is done. Useful for checking the status of upload and import operations.

### Method
Gemini::fileSearchStores()->getOperation()

### Parameters
- **operationName** (string) - Required - The name of the operation to poll.

### Request Example
```php
use Gemini\Laravel\Facades\Gemini;

while ($operation->done === false) {
    sleep(2);
    $operation = Gemini::fileSearchStores()->getOperation($operation->name);
}

if ($operation->error !== null) {
    die('Failed: ' . json_encode($operation->error));
}

echo "Document added\n";
```

### Response
Returns the updated operation object with `done` and `error` properties.
```

--------------------------------

### Create file search store with Gemini::fileSearchStores()->create()

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Creates a file search store with a display name. The response includes the store name, e.g., 'fileSearchStores/my-search-store-abc123'.

```php
use Gemini\Laravel\Facades\Gemini;

$fileSearchStore = Gemini::fileSearchStores()->create(
    displayName: 'My Search Store',
);

echo "File search store created: {$fileSearchStore->name}\n"; // fileSearchStores/my-search-store-abc123
```

--------------------------------

### Grounding with Google Search using GoogleSearch tool

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Connects the Gemini model to real-time web content using the GoogleSearch tool. Works with all available languages and provides more accurate answers with verifiable sources. The response includes grounding metadata for search queries, web sources, and grounding supports.

```php
use Gemini\Data\GoogleSearch;
use Gemini\Data\Tool;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withTool(new Tool(googleSearch: GoogleSearch::from()))
    ->generateContent('Who won the Euro 2024?');

echo $response->text();
// Spain won Euro 2024, defeating England 2-1 in the final.

// Access grounding metadata to see sources
$groundingMetadata = $response->candidates[0]->groundingMetadata;
if ($groundingMetadata !== null) {
    // Get the search queries that were executed
    foreach ($groundingMetadata->webSearchQueries ?? [] as $query) {
        echo "Search query: {$query}\n";
    }
    
    // Get the web sources
    foreach ($groundingMetadata->groundingChunks ?? [] as $chunk) {
        if ($chunk->web !== null) {
            echo "Source: {$chunk->web->title} - {$chunk->web->uri}\n";
        }
    }
    
    // Get grounding supports (links text segments to sources)
    foreach ($groundingMetadata->groundingSupports ?? [] as $support) {
        if ($support->segment !== null) {
            echo "Text segment: {$support->segment->text}\n";
            echo "Supported by chunks: " . implode(', ', $support->groundingChunkIndices ?? []) . "\n";
        }
    }
}
```

--------------------------------

### Get File Search Document by name

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Retrieves a specific file search document using its full name. Outputs the document's name, display name, and state.

```php
use Gemini\Laravel\Facades\Gemini;

$fileSearchDocument = Gemini::fileSearchStores()->getDocument('fileSearchStores/my-search-store/documents/my-document');

echo "Name: {$fileSearchDocument->name}\n";
echo "Display Name: {$fileSearchDocument->displayName}\n";
echo "State: {$fileSearchDocument->state?->value}\n";
```

--------------------------------

### Send prompt using Gemini facade and helper method

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Uses the Gemini facade to generate content with a model name or via GeminiHelper::generateGeminiModel with ModelVariation::FLASH and generation 2.5. The helper returns a model string like 'models/gemini-2.5-flash'. The result text is accessed via $result->text().

```php
use Gemini\Enums\ModelVariation;
use Gemini\GeminiHelper;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.5-flash')->generateContent('Hello');
$result->text(); // Hello! How can I assist you today?

// Helper method usage
$result = Gemini::generativeModel(
    model: GeminiHelper::generateGeminiModel(
        variation: ModelVariation::FLASH,
        generation: 2.5,
    ), // models/gemini-2.5-flash
)->generateContent('Hello');
$result->text(); // Hello! How can I assist you today?
```

--------------------------------

### List file search stores with Gemini::fileSearchStores()->list()

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Lists all file search stores with a page size of 10. Iterates over the response to print each store's name and display name.

```php
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::fileSearchStores()->list(pageSize: 10);

foreach ($response->fileSearchStores as $fileSearchStore) {
    echo "Name: {$fileSearchStore->name}\n";
    echo "Display Name: {$fileSearchStore->displayName}\n";
    echo "--- \n";
}
```

--------------------------------

### Delete a File

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Deletes a file from Gemini storage. The delete method accepts a file ID, file name, or full URI. The example shows deleting by file name and by full URI.

```php
use Gemini\Laravel\Facades\Gemini;

Gemini::files()->delete('files/abc-123');
// or use the full URI
Gemini::files()->delete($file->uri);
```

--------------------------------

### Upgrade Gemini Laravel package to 2.0

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Upgrade command to version ^2.0. Starting 2.0, the package works only with Gemini v1beta API. Introduces new features and deprecates ModelType enum and geminiPro/geminiFlash methods.

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

--------------------------------

### Grounding with File Search using FileSearch tool

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Enables the model to retrieve information from documents in file search stores. The FileSearch tool accepts a store name and an optional metadata filter. Useful for answering questions based on private or extensive document collections.

```php
use Gemini\Data\FileSearch;
use Gemini\Data\Tool;
use Gemini\Laravel\Facades\Gemini;

$tool = new Tool(
    fileSearch: new FileSearch(
        fileSearchStoreNames: ['fileSearchStores/my-search-store'],
        metadataFilter: 'author = "Robert Graves"'
    )
);

$response = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withTool($tool)
    ->generateContent('Summarize the document about Greek myths by Robert Graves');

echo $response->text();
// (Model output summarizing the document)
```

--------------------------------

### List File Search Documents in store

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Lists all file search documents within a store with a specified page size. Iterates over the returned documents and prints their details.

```php
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::fileSearchStores()->listDocuments(storeName: 'fileSearchStores/my-search-store', pageSize: 10);

foreach ($response->documents as $fileSearchDocument) {
    echo "Name: {$fileSearchDocument->name}\n";
    echo "Display Name: {$fileSearchDocument->displayName}\n";
    echo "Create Time: {$fileSearchDocument->createTime}\n";
    echo "Update Time: {$fileSearchDocument->updateTime}\n";
    echo "--- \n";
}
```

--------------------------------

### Update cached content TTL or expiration with Gemini::cachedContents()->update()

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Updates the expiration of cached content either by setting a new TTL (counted from now) or an absolute expiration time. The example shows both options; the second call overrides the first.

```php
use Gemini\Laravel\Facades\Gemini;

// Set a new TTL, counted from now
$updated = Gemini::cachedContents()->update(
    name: 'cachedContents/abc123',
    ttl: '7200s' // Expires in 2 hours
);

// Or set absolute expiration time
$updated = Gemini::cachedContents()->update(
    name: 'cachedContents/abc123',
    expireTime: '2030-12-31T23:59:59Z'
);
```

--------------------------------

### Create cached content with Gemini::cachedContents()->create()

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Creates a cached content entry with a model, system instruction, parts, TTL, and display name. The content must meet a minimum token count to be cached. TTL is specified in seconds, e.g., '3600s' for 1 hour.

```php
use Gemini\Data\Content;
use Gemini\Laravel\Facades\Gemini;

$cachedContent = Gemini::cachedContents()->create(
    model: 'gemini-2.5-flash',
    systemInstruction: Content::parse('You are an expert PHP developer.'),
    parts: [
        'This is a large codebase...',
        'File 1 contents...',
        'File 2 contents...'
    ],
    ttl: '3600s', // Cache for 1 hour
    displayName: 'PHP Codebase Cache'
);

echo "Cached content created: {$cachedContent->name}\n";
```

--------------------------------

### Generate an image with ImageConfig and GenerationConfig

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Uses the Gemini image model 'gemini-2.5-flash-image' with an ImageConfig for aspect ratio and image size. The response may contain text and image parts; inline image data is saved to 'image.png'.

```php
use Gemini\Data\GenerationConfig;
use Gemini\Data\ImageConfig;
use Gemini\Laravel\Facades\Gemini;

$imageConfig = new ImageConfig(aspectRatio: '16:9', imageSize: '2K');
$generationConfig = new GenerationConfig(imageConfig: $imageConfig);

$response = Gemini::generativeModel(model: 'gemini-2.5-flash-image')
    ->withGenerationConfig($generationConfig)
    ->generateContent('Draw a futuristic city');

// The response can contain text and image parts
foreach ($response->parts() as $part) {
    if ($part->inlineData !== null) {
        file_put_contents('image.png', base64_decode($part->inlineData->data));
    }
}
```

--------------------------------

### Optional Gemini environment variables

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Optional environment variables for base URL and request timeout. Define them in your .env file as needed.

```plaintext
GEMINI_BASE_URL=
GEMINI_REQUEST_TIMEOUT=
```

--------------------------------

### Assert function calls like withGenerationConfig()

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Calls that configure a model, such as withGenerationConfig(), withTool(), or startChat(), are recorded as function calls. Use assertFunctionCalled to verify these configuration calls.

```php
use Gemini\Data\GenerationConfig;
use Gemini\Laravel\Facades\Gemini;

Gemini::generativeModel(model: 'gemini-2.5-flash')->assertFunctionCalled(function (string $method, array $parameters) {
    return $method === 'withGenerationConfig' &&
        $parameters[0] instanceof GenerationConfig;
});
```

--------------------------------

### Faking Gemini responses in tests with error handling

Source: https://github.com/google-gemini-php/laravel/blob/main/_autodocs/api-reference/facade-gemini.md

Shows how to fake successful and failing Gemini API responses in tests using the Gemini::fake method. The example demonstrates handling an ErrorException with status and code.

```php
use Gemini\Exceptions\ErrorException;
use Gemini\Laravel\Facades\Gemini;
use Gemini\Responses\GenerativeModel\GenerateContentResponse;

// Fake a successful response
Gemini::fake([
    GenerateContentResponse::fake([
        'candidates' => [
            [
                'content' => [
                    'parts' => [
                        ['text' => 'success'],
                    ],
                ],
            ],
        ],
    ]),
]);

$result = Gemini::generativeModel(model: 'gemini-2.5-flash')->generateContent('test');
echo $result->text(); // "success"

// Fake a failing request with a Throwable
Gemini::fake([
    new ErrorException([
        'message' => 'The model `gemini-basic` does not exist',
        'status' => 'INVALID_ARGUMENT',
        'code' => 400,
    ]),
]);

try {
    Gemini::generativeModel(model: 'gemini-2.5-flash')->generateContent('test');
} catch (ErrorException $e) {
    echo $e->getErrorStatus(); // INVALID_ARGUMENT
    echo $e->getErrorCode(); // 400
}
```

--------------------------------

### List cached content with Gemini::cachedContents()->list()

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Lists all cached content in the project with a page size of 10. Iterates over the response to print name, display name, model, and expiration time.

```php
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::cachedContents()->list(pageSize: 10);

foreach ($response->cachedContents as $cached) {
    echo "Name: {$cached->name}\n";
    echo "Display Name: {$cached->displayName}\n";
    echo "Model: {$cached->model}\n";
    echo "Expires: {$cached->expireTime}\n";
    echo "---\n";
}
```

--------------------------------

### Server-side tool invocations with includeServerSideToolInvocations

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Configure a chat session to receive server-side tool calls (e.g., URL context) and their results as toolCall and toolResponse parts. Requires a model that supports it, such as Gemini 3 models; other models reject the request with an ErrorException. Read the response with parts() instead of text() because it contains several parts.

```php
use Gemini\Data\Tool;
use Gemini\Data\ToolConfig;
use Gemini\Data\UrlContext;
use Gemini\Laravel\Facades\Gemini;

$chat = Gemini::generativeModel(model: 'gemini-3.5-flash')
    ->withTool(new Tool(urlContext: new UrlContext))
    ->withToolConfig(new ToolConfig(includeServerSideToolInvocations: true))
    ->startChat();

$response = $chat->sendMessage('Summarize https://www.php.net/releases/8.4/en.php in one sentence.');

foreach ($response->parts() as $part) {
    if ($part->toolCall !== null) {
        echo "Tool call: {$part->toolCall->toolType?->value} " . json_encode($part->toolCall->args) . "\n";
    }
    if ($part->toolResponse !== null) {
        echo "Tool response: " . json_encode($part->toolResponse->response) . "\n";
    }
    if ($part->text !== null) {
        echo $part->text . "\n";
    }
}
```

--------------------------------

### Stream chat responses with streamSendMessage

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Starts a chat session and streams the response using streamSendMessage. The history is automatically updated with the full response after streaming completes, joining text chunks and keeping function calls, tool calls, and thoughts as separate parts.

```php
use Gemini\Laravel\Facades\Gemini;

$chat = Gemini::generativeModel(model: 'gemini-2.5-flash')->startChat();

$stream = $chat->streamSendMessage('Hello');

foreach ($stream as $response) {
    echo $response->text();
}
```

--------------------------------

### Inspect empty response reasons with promptFeedback and candidates

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

When text() or parts() throws a ValueError due to empty content, check promptFeedback->blockReason, candidates[0]->finishReason, and finishMessage to diagnose the cause. Common reason: MAX_TOKENS with thinking models.

```php
$response->promptFeedback?->blockReason; // the prompt was blocked, e.g. BlockReason::SAFETY
$response->candidates[0]->finishReason; // e.g. FinishReason::MAX_TOKENS or FinishReason::SAFETY
$response->candidates[0]->finishMessage; // more details, when available
```

--------------------------------

### Function Calling with Gemini in PHP (Laravel)

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Defines a custom function 'addition' that the Gemini model can call during a chat. The handler processes the function call and sends the response back to the model. The example shows how to set up the tool, send a message, handle the function call, and print the final text response.

```php
<?php

use Gemini\Data\Content;
use Gemini\Data\FunctionCall;
use Gemini\Data\FunctionDeclaration;
use Gemini\Data\FunctionResponse;
use Gemini\Data\Part;
use Gemini\Data\Schema;
use Gemini\Data\Tool;
use Gemini\Enums\DataType;
use Gemini\Enums\Role;
use Gemini\Laravel\Facades\Gemini;

function handleFunctionCall(FunctionCall $functionCall): Content
{
    if ($functionCall->name === 'addition') {
        return new Content(
            parts: [
                new Part(
                    functionResponse: new FunctionResponse(
                        name: 'addition',
                        response: ['answer' => $functionCall->args['number1'] + $functionCall->args['number2']],
                        id: $functionCall->id,
                    )
                )
            ],
            role: Role::USER
        );
    }

    //Handle other function calls
}

$chat = Gemini::generativeModel(model: 'gemini-2.5-flash')
    ->withTool(new Tool(
        functionDeclarations: [
            new FunctionDeclaration(
                name: 'addition',
                description: 'Performs addition',
                parameters: new Schema(
                    type: DataType::OBJECT,
                    properties: [
                        'number1' => new Schema(
                            type: DataType::NUMBER,
                            description: 'First number'
                        ),
                        'number2' => new Schema(
                            type: DataType::NUMBER,
                            description: 'Second number'
                        ),
                    ],
                    required: ['number1', 'number2']
                )
            )
        ]
    ))
    ->startChat();

$response = $chat->sendMessage('What is 4 + 3?');

if ($response->parts()[0]->functionCall !== null) {
    $functionResponse = handleFunctionCall($response->parts()[0]->functionCall);

    $response = $chat->sendMessage($functionResponse);
}

echo $response->text(); // 4 + 3 = 7
```

--------------------------------

### List Gemini models with pageSize and nextPageToken

Source: https://github.com/google-gemini-php/laravel/blob/main/README.md

Lists available Gemini models using the Gemini facade. The optional pageSize parameter defaults to 50 models per page (max 1000), and nextPageToken retrieves subsequent pages. The response contains a models array of Gemini\Data\Model objects.

```php
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::models()->list(pageSize: 3, nextPageToken: 'ChFtb2RlbHMvZ2VtaW5pLXBybw==');

$response->models;
//[
//    [0] => Gemini\Data\Model Object
//        (
//            [name] => models/gemini-2.5-flash
//            [version] => 001
//            [displayName] => Gemini 2.5 Flash
//            [description] => Stable version of Gemini 2.5 Flash
//            ...
//        )
//    [1] => Gemini\Data\Model Object
//        (
//            [name] => models/gemini-2.5-pro
//            [version] => 2.5
//            [displayName] => Gemini 2.5 Pro
//            [description] => Stable release of Gemini 2.5 Pro
//            ...
//        )
//    [2] => Gemini\Data\Model Object
//        (
//            [name] => models/gemini-embedding-001
//            [version] => 001
//            [displayName] => Gemini Embedding 001
//            [description] => Obtain a distributed representation of a text.
//            ...
//        )
//]
```
Tokens:
Raw