Laravel Google Search Console

https://github.com/jeffersongoncalves/laravel-google-search-console
Admin
Laravel Google Search Console is a lightweight API client for Laravel that provides search analytics...
Tokens:17,645
Snippets:126
Trust Score:9.8
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-google-search-console
```

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

### inspectUrl() example with default site URL

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Example call to inspectUrl using the default site URL from config. The result is an associative array; the example extracts the 'verdict' from the inspection result.

```php
$result = GoogleSearchConsoleClient::inspectUrl('https://example.com/page');
$verdict = $result['inspectionResult']['indexStatusResult']['verdict'] ?? null;
```

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

### inspectUrl() example with explicit site URL and null check

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Example call to inspectUrl with an explicit site URL ('sc-domain:example.com'). Shows how to handle a null return, which indicates a non-2xx response or network error, and mentions the log warning 'GoogleSearchConsoleClient outbound fetch failed'.

```php
$result = GoogleSearchConsoleClient::inspectUrl('https://example.com/page', 'sc-domain:example.com');

if ($result === null) {
    // Inspection failed (non-2xx status or network error) — see the
    // 'GoogleSearchConsoleClient outbound fetch failed' log warning.
}
```

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

### Usage Examples

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

Shows how to use the static client for search analytics, URL inspection, and sitemap management. The site URL defaults to the configured value, and dates default to a 28-day window ending 3 days ago. You can pass a different site URL to override the default.

```php
use JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleClient;

// Search analytics — site URL defaults to config('google-search-console.site_url'),
// dates default to a 28-day window ending 3 days ago (Search Console's usual data lag)
$byQuery = GoogleSearchConsoleClient::searchAnalyticsByQuery();
$byPage = GoogleSearchConsoleClient::searchAnalyticsByPage(startDate: '2026-01-01', endDate: '2026-01-31', limit: 50);
$byCountry = GoogleSearchConsoleClient::searchAnalyticsByCountry();

// URL inspection
$result = GoogleSearchConsoleClient::inspectUrl('https://example.com/page');

// Sitemaps
$sitemaps = GoogleSearchConsoleClient::sitemaps();
GoogleSearchConsoleClient::submitSitemap('https://example.com/sitemap.xml');
GoogleSearchConsoleClient::deleteSitemap('https://example.com/sitemap.xml');

// Target a different site than the configured default
$sitemaps = GoogleSearchConsoleClient::sitemaps(siteUrl: 'sc-domain:example.com');
```

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

### Example HTTP request for search analytics query

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Shows the HTTP request the client produces for the search analytics endpoint. Includes the URL, authorization header, content type, and JSON body with startDate, endDate, rowLimit, and dimensions.

```http
POST https://searchconsole.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fexample.com%2F/searchAnalytics/query
Authorization: Bearer ya29.xxx
Content-Type: application/json

{"startDate":"...","endDate":"...","rowLimit":100,"dimensions":["query"]}
```

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

### searchAnalyticsByCountry() example

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Example call to searchAnalyticsByCountry using named arguments for startDate and endDate. The siteUrl defaults to config('google-search-console.site_url'), startDate defaults to 28 days before the default end date, and endDate defaults to 3 days ago.

```php
$rows = GoogleSearchConsoleClient::searchAnalyticsByCountry(
    startDate: '2026-01-01',
    endDate: '2026-01-31',
);
```

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

### Orchestra Testbench provider registration

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Example of registering the provider in a Testbench test case, as used in the package's own tests.

```php
use JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleServiceProvider;
use Orchestra\Testbench\TestCase as Orchestra;

class TestCase extends Orchestra
{
    protected function getPackageProviders($app): array
    {
        return [
            GoogleSearchConsoleServiceProvider::class,
        ];
    }
}
```

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

### deleteSitemap() example with default site URL

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Deletes a sitemap using the configured site URL. Returns true on success (e.g., 204 No Content) and false on failure.

```php
$ok = GoogleSearchConsoleClient::deleteSitemap('https://example.com/sitemap.xml');
```

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

### deleteSitemap() example with explicit site URL and error handling

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Deletes a sitemap with an explicit site URL. Catches InvalidArgumentException, which is only thrown when both the argument and the config site URL are missing.

```php
try {
    $ok = GoogleSearchConsoleClient::deleteSitemap($sitemapUrl, 'sc-domain:example.com');
} catch (InvalidArgumentException $e) {
    // Only thrown when both the argument and the config site URL are missing
}
```

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

### Run Code Formatting

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

Run the code formatter.

```bash
composer format
```

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

### Run Tests

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

Run the test suite.

```bash
composer test
```

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

### Run Static Analysis

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

Run PHPStan static analysis.

```bash
composer analyse
```

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

### Full config file (config/google-search-console.php)

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

The complete configuration file with all options. The timeout is cast to int and defaults to 8 seconds.

```php
<?php

return [
    'access_token' => env('GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN'),
    'site_url' => env('GOOGLE_SEARCH_CONSOLE_SITE_URL'),
    'timeout' => (int) env('GOOGLE_SEARCH_CONSOLE_TIMEOUT', 8),
];
```

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

### configurePackage method signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

The public method signature for configurePackage, invoked by the Spatie package-tools parent during package boot.

```php
public function configurePackage(Package $package): void
```

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

### Publish Config File

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

Optionally publish the configuration file using the tag 'google-search-console-config'.

```bash
php artisan vendor:publish --tag="google-search-console-config"
```

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

### Environment Variables Configuration

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

Add these environment variables to your .env file. The access token is the OAuth bearer token, the site URL must match the exact format shown in Search Console (e.g., https://example.com/ or sc-domain:example.com), and the timeout defaults to 8 seconds.

```env
GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN=ya29.xxxxxxxxxxxxxxxxxxxx
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/
GOOGLE_SEARCH_CONSOLE_TIMEOUT=8
```

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

### configurePackage(Package $package)

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Configures the Laravel package by setting its name and registering the config file for publishing. This method is invoked by the Spatie package-tools parent during package boot.

```APIDOC
## configurePackage(Package $package)

### Description
Configures the Laravel package by setting its name and registering the config file for publishing. This method is invoked by the Spatie package-tools parent during package boot.

### Method
configurePackage

### Signature
```php
public function configurePackage(Package $package): void
```

### Parameters
- `$package` (Spatie\LaravelPackageTools\Package) - Required - The package builder instance supplied by `PackageServiceProvider`.

### Behavior
- `->name('google-search-console')` — registers the package name, which is also the config key (`config('google-search-console.*')`).
- `->hasConfigFile()` — tells package-tools to load the config file `config/google-search-console.php` and register it for `vendor:publish` under the tag `google-search-console-config`:

```bash
php artisan vendor:publish --tag="google-search-console-config"
```

### Return type
`void`.

### Throws
None. This method does not throw under documented conditions.

### Examples
No manual registration is needed in normal Laravel apps: `composer.json` declares the provider under `extra.laravel.providers`, which Laravel's package auto-discovery reads on install:

```json
"extra": {
    "laravel": {
        "providers": [
            "JeffersonGoncalves\\GoogleSearchConsole\\GoogleSearchConsoleServiceProvider"
        ]
    }
}
```

In a package host app or bespoke setup, register it like any provider:

```php
// config/app.php
'providers' => [
    JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleServiceProvider::class,
],
```

When using Orchestra Testbench (the pattern used by this package's own tests in `tests/TestCase.php`):

```php
use JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleServiceProvider;
use Orchestra\Testbench\TestCase as Orchestra;

class TestCase extends Orchestra
{
    protected function getPackageProviders($app): array
    {
        return [
            GoogleSearchConsoleServiceProvider::class,
        ];
    }
}
```
```

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

### Basic searchAnalyticsByQuery() call using config defaults

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Calls searchAnalyticsByQuery() with no arguments, relying on config values for site URL and dates. Iterates over returned rows and prints the first key and click count.

```php
use JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleClient;

$rows = GoogleSearchConsoleClient::searchAnalyticsByQuery();

foreach ($rows as $row) {
    echo $row['keys'][0] . ': ' . $row['clicks'] . ' clicks';
}
```

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

### request() private helper signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Builds the full URL, attaches Authorization: Bearer <token> when configured, sets Http::timeout(self::timeout()), and dispatches via match on get/post/put/delete. Catches any Throwable, logs via logFailure(), and returns null on failure.

```php
private static function request(string $method, string $path, string $context, array $body = []): ?Response
```

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

### Config File Options

Source: https://github.com/jeffersongoncalves/laravel-google-search-console/blob/main/README.md

The published config file returns the environment variables. The timeout is cast to an integer with a default of 8.

```php
// config/google-search-console.php
return [
    'access_token' => env('GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN'),
    'site_url' => env('GOOGLE_SEARCH_CONSOLE_SITE_URL'),
    'timeout' => (int) env('GOOGLE_SEARCH_CONSOLE_TIMEOUT', 8),
];
```

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

### defaultSiteUrl(), accessToken(), timeout() private helpers

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Configuration accessors. defaultSiteUrl() returns config('google-search-console.site_url') with '' converted to null. accessToken() returns config('google-search-console.access_token') with '' converted to null. timeout() returns (int) config('google-search-console.timeout', 8).

```php
private static function defaultSiteUrl(): ?string       // config('google-search-console.site_url'), '' → null
private static function accessToken(): ?string           // config('google-search-console.access_token'), '' → null
private static function timeout(): int                   // (int) config('google-search-console.timeout', 8)
```

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

### searchAnalyticsByQuery() signature with docblock

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Declares the static method signature with a docblock indicating the return type. The method accepts optional site URL, start/end dates, and a limit, defaulting to a 28-day window ending 3 days ago.

```php
/**
 * @return list<array<string, mixed>>
 */
public static function searchAnalyticsByQuery(?string $siteUrl = null, ?string $startDate = null, ?string $endDate = null, int $limit = 100): array
```

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

### searchAnalyticsByPage() method signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Defines the static method signature for fetching search analytics rows by page. Parameters are optional with defaults: siteUrl falls back to config, startDate defaults to 28 days before endDate, endDate defaults to 3 days ago, and limit defaults to 100. Returns a list of associative arrays or an empty array on failure.

```php
/**
 * @return list<array<string, mixed>>
 */
public static function searchAnalyticsByPage(?string $siteUrl = null, ?string $startDate = null, ?string $endDate = null, int $limit = 100): array
```

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

### Runtime override with config()->set()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Overrides config values at runtime, useful for tests or per-request changes without editing .env. The package's own tests use this mechanism.

```php
config()->set('google-search-console.site_url', 'sc-domain:example.com');
config()->set('google-search-console.access_token', 'ya29.new-token');
config()->set('google-search-console.timeout', 15);
```

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

### submitSitemap()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Submits a sitemap URL to Google Search Console. Returns a boolean indicating success.

```APIDOC
## submitSitemap()

### Description
Submits a sitemap URL to Google Search Console. Returns a boolean indicating success.

### Signature

```php
public static function submitSitemap(string $sitemapUrl, ?string $siteUrl = null): bool
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$sitemapUrl` | `string` | Yes | — | Absolute URL of the sitemap to submit, e.g. `https://example.com/sitemap.xml`. |
| `$siteUrl` | `?string` | No | `null` | Verified site URL. Falls back to `config('google-search-console.site_url')`. |

### Return type

`bool` — `true` if the PUT request returned a successful (2xx) status; `false` on non-2xx responses or transport failures.

### Throws

| Error | Condition |
|-------|-----------|
| `InvalidArgumentException` | No site URL could be resolved. |

### Examples

```php
$ok = GoogleSearchConsoleClient::submitSitemap('https://example.com/sitemap.xml');

if (! $ok) {
    Log::warning('Sitemap submission failed');
}
```
```

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

### Composer.json auto-discovery configuration

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Declares the service provider under extra.laravel.providers for Laravel's package auto-discovery.

```json
"extra": {
    "laravel": {
        "providers": [
            "JeffersonGoncalves\\GoogleSearchConsole\\GoogleSearchConsoleServiceProvider"
        ]
    }
}
```

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

### Call with limit and exception handling

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Calls the method with a limit of 10 inside a try-catch block. Catches InvalidArgumentException when no site URL is resolved, logs the error message, and includes a comment explaining the condition.

```php
try {
    $rows = GoogleSearchConsoleClient::searchAnalyticsByPage(limit: 10);
} catch (InvalidArgumentException $e) {
    // config('google-search-console.site_url') is empty and no $siteUrl given
    Log::error($e->getMessage());
}
```

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

### GoogleSearchConsoleServiceProvider class definition

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

The service provider class extends PackageServiceProvider and configures the package with name 'google-search-console' and a config file. It is auto-discovered by Laravel.

```php
class GoogleSearchConsoleServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('google-search-console')
            ->hasConfigFile();
    }
}
```

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

### Basic call to searchAnalyticsByPage()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Calls the method with no arguments, using all default parameter values. The result is assigned to $rows.

```php
$rows = GoogleSearchConsoleClient::searchAnalyticsByPage();
```

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

### Class skeleton for GoogleSearchConsoleClient

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Shows the class declaration with the base URL constant and a comment indicating seven public static methods. The class is fully static and never instantiated.

```php
class GoogleSearchConsoleClient
{
    private const BASE_URL = 'https://searchconsole.googleapis.com';
    // ... seven public static methods
}
```

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

### Explicit searchAnalyticsByQuery() call with named arguments

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Passes explicit site URL, dates, and limit using named arguments. Checks for an empty array to handle either no data or a silent request failure.

```php
$rows = GoogleSearchConsoleClient::searchAnalyticsByQuery(
    siteUrl: 'sc-domain:example.com',
    startDate: '2026-01-01',
    endDate: '2026-01-31',
    limit: 50,
);

if ($rows === []) {
    // Either no data in the window, or the request failed silently.
}
```

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

### sitemaps()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Lists the submitted sitemaps for a site. Returns an array of sitemap objects, or an empty array on failure.

```APIDOC
## sitemaps()

### Description
Lists the submitted sitemaps for a site. Returns an array of sitemap objects, or an empty array on failure.

### Signature

```php
public static function sitemaps(?string $siteUrl = null): array
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$siteUrl` | `?string` | No | `null` | Verified site URL. Falls back to `config('google-search-console.site_url')`. |

### Return type

`list<array<string, mixed>>` — the entries of the response's `sitemap` key (each element is a raw sitemap object, e.g. `['path' => ..., 'lastSubmitted' => ..., 'isPending' => ...]`). Returns `[]` when the `sitemap` key is absent, on non-2xx responses, non-JSON responses, or transport failures.

### Throws

| Error | Condition |
|-------|-----------|
| `InvalidArgumentException` | No site URL could be resolved. |

### Examples

```php
$sitemaps = GoogleSearchConsoleClient::sitemaps();

foreach ($sitemaps as $sitemap) {
    echo $sitemap['path'];
}
```

```php
// Target a different site than the configured default
$sitemaps = GoogleSearchConsoleClient::sitemaps(siteUrl: 'sc-domain:example.com');
```
```

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

### logFailure() private helper signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Logs a warning with context, target, exception class, and message. Used to record outbound fetch failures.

```php
private static function logFailure(string $context, string $target, Throwable $e): void
```

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

### resolveSiteUrl() private helper signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Uses the explicit $siteUrl if truthy, else defaultSiteUrl(). Throws InvalidArgumentException when the result is null or empty string.

```php
private static function resolveSiteUrl(?string $siteUrl): string
```

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

### defaultDateRange() private helper signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Returns an array with startDate and endDate. endDate is now minus 3 days, startDate is endDate minus 28 days. The 3-day offset accounts for Search Console's data lag.

```php
private static function defaultDateRange(): array
```

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

### searchAnalytics() private helper signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Shared implementation for the three analytics methods. POSTs to /webmasters/v3/sites/{siteUrl}/searchAnalytics/query with the provided body. Returns $data['rows'] ?? [] from the JSON response.

```php
private static function searchAnalytics(string $dimension, ?string $siteUrl, ?string $startDate, ?string $endDate, int $limit): array
```

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

### Catching InvalidArgumentException for missing site URL

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Use this try-catch block to handle the only throw path in the library: when a public method is called without a site URL and the config value is null or empty. The exception is thrown before any HTTP request, and the message is 'No Google Search Console site URL provided. Pass one explicitly or set config('google-search-console.site_url').'.

```php
use JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleClient;
use InvalidArgumentException;

try {
    GoogleSearchConsoleClient::sitemaps(); // no config site_url set
} catch (InvalidArgumentException $e) {
    Log::error($e->getMessage());
    // "No Google Search Console site URL provided. Pass one
    //  explicitly or set config('google-search-console.site_url')."
}
```

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

### Submit sitemap with GoogleSearchConsoleClient::submitSitemap()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Submits a sitemap URL to Google Search Console. Returns true if the PUT request returns a 2xx status, false otherwise. Throws InvalidArgumentException if no site URL can be resolved.

```php
public static function submitSitemap(string $sitemapUrl, ?string $siteUrl = null): bool
```

```php
$ok = GoogleSearchConsoleClient::submitSitemap('https://example.com/sitemap.xml');

if (! $ok) {
    Log::warning('Sitemap submission failed');
}
```

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

### inspectUrl()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Runs Google's URL Inspection API (`/v1/urlInspection/index:inspect`) against a given URL and returns the raw inspection result. Returns the full JSON response body as an associative array, or `null` when the response is non-2xx, not a JSON array, or a transport failure occurred.

```APIDOC
## inspectUrl()

### Description
Runs Google's URL Inspection API (`/v1/urlInspection/index:inspect`) against a given URL and returns the raw inspection result.

### Method
`inspectUrl` (static method)

### Signature
```php
public static function inspectUrl(string $url, ?string $siteUrl = null): ?array
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$url` | `string` | Yes | — | The URL to inspect, e.g. `https://example.com/page`. Sent as `inspectionUrl` in the request body. |
| `$siteUrl` | `?string` | No | `null` | Verified site URL the inspection is scoped to (`siteUrl` in the body). Falls back to `config('google-search-console.site_url')`. |

### Return type
`array<string, mixed>|null` — the full JSON response body as an associative array (e.g. `['inspectionResult' => [...]]`), or `null` when the response is non-2xx, not a JSON array, or a transport failure occurred.

### Throws
| Error | Condition |
|-------|-----------|
| `InvalidArgumentException` | No site URL could be resolved. |

### Request Example
```php
$result = GoogleSearchConsoleClient::inspectUrl('https://example.com/page');
$verdict = $result['inspectionResult']['indexStatusResult']['verdict'] ?? null;
```

```php
$result = GoogleSearchConsoleClient::inspectUrl('https://example.com/page', 'sc-domain:example.com');

if ($result === null) {
    // Inspection failed (non-2xx status or network error) — see the
    // 'GoogleSearchConsoleClient outbound fetch failed' log warning.
}
```
```

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

### Manual provider registration in config/app.php

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Registers the service provider manually in a Laravel app's providers array.

```php
// config/app.php
'providers' => [
    JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleServiceProvider::class,
],
```

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

### List sitemaps with GoogleSearchConsoleClient::sitemaps()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Lists the submitted sitemaps for a site. The method returns an array of raw sitemap objects, each with keys like 'path', 'lastSubmitted', and 'isPending'. Returns an empty array on non-2xx responses, non-JSON responses, or transport failures.

```php
public static function sitemaps(?string $siteUrl = null): array
```

```php
$sitemaps = GoogleSearchConsoleClient::sitemaps();

foreach ($sitemaps as $sitemap) {
    echo $sitemap['path'];
}
```

```php
// Target a different site than the configured default
$sitemaps = GoogleSearchConsoleClient::sitemaps(siteUrl: 'sc-domain:example.com');
```

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

### jsonOrNull() private helper signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Returns null when the response is null or not successful(); otherwise returns the response as an array, or null if the JSON body is not an array.

```php
private static function jsonOrNull(?Response $response): ?array
```

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

### searchAnalyticsByPage()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Fetches search analytics rows broken down by page (URLs on your site). Returns a list of associative arrays, one per page, with 'keys' containing the page URL. Returns an empty array on failure, non-JSON response, or missing rows.

```APIDOC
## searchAnalyticsByPage()

### Description
Fetches search analytics rows broken down by **page** (URLs on your site). Returns a list of associative arrays, one per page, with `keys` containing the page URL. Returns an empty array on failure, non-JSON response, or missing rows.

### Signature
```php
/**
 * @return list<array<string, mixed>>
 */
public static function searchAnalyticsByPage(?string $siteUrl = null, ?string $startDate = null, ?string $endDate = null, int $limit = 100): array
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$siteUrl` | `?string` | No | `null` | Verified site URL. Falls back to `config('google-search-console.site_url')`. |
| `$startDate` | `?string` | No | `null` | `YYYY-MM-DD` start date; defaults to 28 days before the default end date. |
| `$endDate` | `?string` | No | `null` | `YYYY-MM-DD` end date; defaults to 3 days ago. |
| `$limit` | `int` | No | `100` | Maximum number of rows (`rowLimit`). |

### Return type
`list<array<string, mixed>>` — a row per page, with `keys` containing the page URL. `[]` on failure, non-JSON, or missing `rows`.

### Throws
| Error | Condition |
|-------|-----------|
| `InvalidArgumentException` | No site URL could be resolved. |

### Request Example
```php
$rows = GoogleSearchConsoleClient::searchAnalyticsByPage();
```

```php
try {
    $rows = GoogleSearchConsoleClient::searchAnalyticsByPage(limit: 10);
} catch (InvalidArgumentException $e) {
    // config('google-search-console.site_url') is empty and no $siteUrl given
    Log::error($e->getMessage());
}
```
```

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

### searchAnalytics() request body

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Body sent to the Search Console API. Uses provided dates or defaults from defaultDateRange(), sets rowLimit and dimensions.

```php
[
    'startDate' => $startDate ?? $defaultRange['startDate'],
    'endDate' => $endDate ?? $defaultRange['endDate'],
    'rowLimit' => $limit,
    'dimensions' => [$dimension],
]
```

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

### Log::warning failure diagnostics for outbound fetch

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Logs a warning with context when an outbound request to the Google Search Console API fails. The context array includes the operation tag, target URL, exception class, and message. This is triggered from the request() catch block and uses the default Laravel log channel.

```php
Log::warning('GoogleSearchConsoleClient outbound fetch failed', [
    'context' => $context,   // e.g. 'google_search_console_sitemaps'
    'target' => $url,       // e.g. 'https://searchconsole.googleapis.com/webmasters/v3/sites/...'
    'exception' => $e::class,
    'message' => $e->getMessage(),
]);
```

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

### searchAnalyticsByCountry()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Fetches search analytics rows broken down by country (ISO country codes such as 'bra', 'usa'). Returns a list of associative arrays, one per country, with 'keys' containing the country ISO code, or an empty array on failure.

```APIDOC
## searchAnalyticsByCountry()

### Description
Fetches search analytics rows broken down by country (ISO country codes such as `bra`, `usa`).

### Method
`searchAnalyticsByCountry` (static method)

### Signature
```php
public static function searchAnalyticsByCountry(?string $siteUrl = null, ?string $startDate = null, ?string $endDate = null, int $limit = 100): array
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$siteUrl` | `?string` | No | `null` | Verified site URL. Falls back to `config('google-search-console.site_url')`. |
| `$startDate` | `?string` | No | `null` | `YYYY-MM-DD` start date; defaults to 28 days before the default end date. |
| `$endDate` | `?string` | No | `null` | `YYYY-MM-DD` end date; defaults to 3 days ago. |
| `$limit` | `int` | No | `100` | Maximum number of rows (`rowLimit`). |

### Return type
`list<array<string, mixed>>` — a row per country, with `keys` containing the country ISO code. `[]` on failure.

### Throws
| Error | Condition |
|-------|-----------|
| `InvalidArgumentException` | No site URL could be resolved. |

### Request Example
```php
$rows = GoogleSearchConsoleClient::searchAnalyticsByCountry(
    startDate: '2026-01-01',
    endDate: '2026-01-31',
);
```
```

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

### DELETE /webmasters/v3/sites/{siteUrl}/sitemaps/{sitemapUrl}

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Deletes a sitemap from the specified site. Returns a boolean indicating success based on the HTTP response status.

```APIDOC
## DELETE /webmasters/v3/sites/{siteUrl}/sitemaps/{sitemapUrl}

### Description
Deletes a sitemap from the specified site. Returns `true` if the deletion is successful (2xx response), otherwise `false`.

### Method
DELETE

### Endpoint
/webmasters/v3/sites/{siteUrl}/sitemaps/{sitemapUrl}

### Parameters
#### Path Parameters
- **siteUrl** (string) - Required - The URL of the site. Must be URL-encoded.
- **sitemapUrl** (string) - Required - The URL of the sitemap to delete. Must be URL-encoded.

### Response
#### Success Response (2xx)
- **bool** - `true` if the response is non-null and successful (e.g., 204 No Content); `false` otherwise.
```

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

### searchAnalyticsByCountry() signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Signature of the static method that fetches search analytics rows broken down by country. Returns a list of associative arrays, one per country, with 'keys' containing the ISO country code. Throws InvalidArgumentException when no site URL can be resolved.

```php
/**
 * @return list<array<string, mixed>>
 */
public static function searchAnalyticsByCountry(?string $siteUrl = null, ?string $startDate = null, ?string $endDate = null, int $limit = 100): array
```

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

### inspectUrl() signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Signature of the static method that runs Google's URL Inspection API and returns the raw inspection result. Returns an associative array or null on failure. Throws InvalidArgumentException when no site URL can be resolved.

```php
/**
 * @return array<string, mixed>|null
 */
public static function inspectUrl(string $url, ?string $siteUrl = null): ?array
```

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

### deleteSitemap() method signature

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Public static method to delete a previously submitted sitemap. Returns true on successful (2xx) DELETE response, false on non-2xx or transport failures. Throws InvalidArgumentException when no site URL can be resolved. The $siteUrl parameter falls back to config('google-search-console.site_url').

```php
public static function deleteSitemap(string $sitemapUrl, ?string $siteUrl = null): bool
```

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

### searchAnalyticsByQuery()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Fetches search analytics rows broken down by query (the search terms users typed). Returns an array of analytics row arrays, or an empty array on failure.

```APIDOC
## searchAnalyticsByQuery()

### Description
Fetches search analytics rows broken down by query (the search terms users typed). Returns an array of analytics row arrays, or an empty array on failure.

### Method
GET (via HTTP client)

### Endpoint
https://searchconsole.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query

### Parameters
#### Path Parameters
- `siteUrl` (string) - Required - Verified site URL to query, e.g. `https://example.com/` or `sc-domain:example.com`. Falls back to `config('google-search-console.site_url')` when `null`.

#### Query Parameters
- `startDate` (string) - Optional - `YYYY-MM-DD` start date of the window. Defaults to a 28-day window ending 3 days ago.
- `endDate` (string) - Optional - `YYYY-MM-DD` end date of the window. Defaults to 3 days ago.
- `limit` (integer) - Optional - Maximum number of rows (`rowLimit`); sent as-is in the request body. Defaults to 100.

### Response
#### Success Response (200)
- `rows` (array) - Array of analytics row objects, each containing `keys`, `clicks`, `impressions`, `ctr`, `position`.

### Request Example
```php
use JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleClient;

$rows = GoogleSearchConsoleClient::searchAnalyticsByQuery();

foreach ($rows as $row) {
    echo $row['keys'][0] . ': ' . $row['clicks'] . ' clicks';
}
```

### Response Example
```json
{
  "rows": [
    {
      "keys": ["example query"],
      "clicks": 10,
      "impressions": 100,
      "ctr": 0.1,
      "position": 5.2
    }
  ]
}
```
```

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

### InvalidArgumentException - Missing Site URL

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

This error is thrown when a public method is called without a $siteUrl argument and the configuration value 'google-search-console.site_url' is null or empty. It is thrown before any HTTP request is made.

```APIDOC
## InvalidArgumentException

### Description
Thrown when a public method is called with no `$siteUrl` argument and `config('google-search-console.site_url')` resolves to `null` or `''`. This occurs before any HTTP request is made.

### Error Class
`InvalidArgumentException` (PHP built-in `SplException` family)

### Trigger Condition
- A public method is called with no `$siteUrl` argument **and** `config('google-search-console.site_url')` resolves to `null` or `''`.

### Source Location
`resolveSiteUrl()` — `src/GoogleSearchConsoleClient.php:183` (throw at lines 189–191)

### Exact Message
`No Google Search Console site URL provided. Pass one explicitly or set config('google-search-console.site_url').`

### Affected Public Methods
- `searchAnalyticsByQuery`
- `searchAnalyticsByPage`
- `searchAnalyticsByCountry`
- `inspectUrl`
- `sitemaps`
- `submitSitemap`
- `deleteSitemap`

### Catching It
```php
use JeffersonGoncalves\GoogleSearchConsole\GoogleSearchConsoleClient;
use InvalidArgumentException;

try {
    GoogleSearchConsoleClient::sitemaps(); // no config site_url set
} catch (InvalidArgumentException $e) {
    Log::error($e->getMessage());
    // "No Google Search Console site URL provided. Pass one
    //  explicitly or set config('google-search-console.site_url')."
}
```
```

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

### deleteSitemap()

Source: https://github.com/jeffersongoncalves/laravel-google-search-console

Deletes a previously submitted sitemap from Google Search Console. Returns true if the DELETE request was successful (2xx status), false otherwise.

```APIDOC
## deleteSitemap()

### Description
Deletes a previously submitted sitemap from Google Search Console. Returns true if the DELETE request was successful (2xx status), false otherwise.

### Signature

```php
public static function deleteSitemap(string $sitemapUrl, ?string $siteUrl = null): bool
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$sitemapUrl` | `string` | Yes | — | Absolute URL of the sitemap to delete, e.g. `https://example.com/sitemap.xml`. |
| `$siteUrl` | `?string` | No | `null` | Verified site URL. Falls back to `config('google-search-console.site_url')`. |

### Return type

`bool` — `true` if the DELETE request returned a successful (2xx) status (e.g. `204 No Content`); `false` on non-2xx responses or transport failures.

### Throws

| Error | Condition |
|-------|-----------|
| `InvalidArgumentException` | No site URL could be resolved. |

### Examples

```php
$ok = GoogleSearchConsoleClient::deleteSitemap('https://example.com/sitemap.xml');
```

```php
try {
    $ok = GoogleSearchConsoleClient::deleteSitemap($sitemapUrl, 'sc-domain:example.com');
} catch (InvalidArgumentException $e) {
    // Only thrown when both the argument and the config site URL are missing
}
```
```
Tokens:
Raw