Search by

artisanpack-ui / google

JacobMartellaWebDesign

Shared Google OAuth2 authentication, token storage/refresh, and scope management that powers ArtisanPack UI's Google service integrations.

Package info

github.com/ArtisanPack-UI/google

pkg:composer/artisanpack-ui/google

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 697

Dependents: 4

Suggesters: 2

Stars: 0

Open Issues: 0

1.3.0 2026-10-03 15:55 UTC

Requires

Requires (Dev)

Suggests

Provides

None

Conflicts

None

Replaces

None

MIT ec2cb940ad3f694b17f8b0a50306bab3dd49d325

  • Jacob Martella <me.woop@jacobmartella.com>

oauthoauth2googlelaravelartisanpack-ui

Published on Packagist.org on 2026-10-03 15:56 UTC

This package is auto-updated.

Last update: 2026-10-03 15:57:18 UTC

README

Shared Google OAuth2 authentication, token storage/refresh, and scope management that powers ArtisanPack UI's Google service integrations. Provider packages like artisanpack-ui/analytics-google, artisanpack-ui/google-search-console, and artisanpack-ui/google-tag-manager sit on top of this package.

What this package does

artisanpack-ui/google is the shared plumbing that every ArtisanPack UI Google integration sits on top of. It owns:

  • The OAuth2 authorization-code + PKCE flow — building the consent URL, exchanging the callback code, extracting the user's Google identity from the returned id_token.
  • Encrypted token storage on a per-user google_connections model, with transparent refresh via the token manager.
  • A scope registry that lets any installed service package contribute the scopes it needs. Consent covers the union so users only see one screen.
  • Credential storage drivers (config file, database, or CMS Settings) so credentials can live wherever a project already stores its secrets.
  • An optional broker mode that runs the OAuth flow through an OAuth broker, so a site never holds a Google client secret.
  • Stateless OAuth primitives (Google::client()) for exchanging and refreshing tokens without touching the session or database.

Service packages (Analytics, Search Console, Tag Manager, …) declare the scopes they need and, once a user has connected, call Google::tokens()->getValidAccessToken( $connection ) to make authenticated API calls. They never handle OAuth themselves.

Installation

composer require artisanpack-ui/google

The service provider and Google facade are auto-discovered.

Publish and run migrations to create the google_configurations and google_connections tables:

php artisan vendor:publish --tag=google-migrations
php artisan migrate

Optionally publish the config file to customize routes, drivers, or endpoints:

php artisan vendor:publish --tag=google-config

Optional peer packages

Package What it enables
livewire/livewire ^3.6 The <livewire:google-connection-manager /> connect/disconnect/status UI.
artisanpack-ui/cms-framework The cms credential driver — stores credentials via the CMS Settings module.

Neither is required; the base package boots and works without them.

Google Cloud Console setup

  1. Open the Google Cloud Console and create (or select) a project.
  2. Navigate to APIs & Services → OAuth consent screen. Choose External unless every user has a Workspace account on the same domain, then fill in the app name, support email, and developer contact.
  3. Under Scopes, add every scope your installed service packages require. Consent screens for external apps in "Testing" mode are limited to added test users; publish the app when you're ready for production traffic.
  4. Enable the APIs your service packages depend on (Analytics Data API, Search Console API, Tag Manager API, …) under APIs & Services → Library.
  5. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
    • Application type: Web application
    • Authorized redirect URI: https://your-app.test/google/auth/callback (adjust prefix if you change google.routes.prefix).
  6. Copy the generated Client ID and Client secret.
  7. Save them into whichever credential driver you've chosen (see below).

Credential storage

artisanpack-ui/google supports three credential storage drivers. Choose one by setting GOOGLE_CONFIG_DRIVER (or config('google.driver')).

config (default)

Reads credentials from config/google.php / .env. Best for single-tenant apps where credentials belong in the deploy pipeline:

GOOGLE_CONFIG_DRIVER=config
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://your-app.test/google/auth/callback

The config driver is read-only; Google::config()->save() throws.

database

Stores credentials in the google_configurations table. The client secret is encrypted with Laravel's Encrypter (APP_KEY) before it is written. Good for multi-tenant apps or admin-UI-managed credentials:

GOOGLE_CONFIG_DRIVER=database
Google::config()->save( [
    'client_id'     => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'redirect_uri'  => 'https://your-app.test/google/auth/callback',
] );

If you rotate APP_KEY without re-encrypting the stored secret, the driver logs a warning and treats the row as unconfigured.

cms (optional, requires artisanpack-ui/cms-framework)

Delegates get/set to the CMS framework's Settings module, so Google credentials live alongside every other site-level setting:

GOOGLE_CONFIG_DRIVER=cms

The client secret is encrypted before it is passed to apUpdateSetting(). Reading and writing goes through apGetSetting() / apUpdateSetting(), so any Settings API a project already exposes can manage these credentials. If the CMS framework is not installed, the driver's setting keys are simply never registered — you get a clear "not configured" state instead of a hard boot error.

Broker mode

Since 1.2.0 the package can run connect, callback and refresh through an OAuth broker instead of talking to Google directly. The site holds only the broker URL, its site ID and its site secret — never a Google client secret:

GOOGLE_OAUTH_MODE=broker
GOOGLE_BROKER_URL=https://broker.example.com
GOOGLE_BROKER_SITE_ID=site_123
GOOGLE_BROKER_SITE_SECRET=42|plain-secret-from-the-broker

Routes, the connection model, and getValidAccessToken() work unchanged. The broker URL must be HTTPS. Credentials can also be supplied at runtime via the ap.google.broker.credentials filter. If the broker refuses a refresh because the site license has lapsed, the token manager throws LicenseExpiredException (with getRenewUrl()) and leaves the connection connected. See docs/broker-mode.md.

Connecting a user

The base package ships two web routes (mounted under google.routes.prefix, default /google/auth) and two more added for incremental consent and disconnection:

Route Method Name
/connect GET google.auth.connect
/callback GET google.auth.callback
/reauthorize GET google.auth.reauthorize
/disconnect POST google.auth.disconnect

Send an authenticated user to route('google.auth.connect'):

<a href="{{ route('google.auth.connect') }}">Connect Google</a>

The controller redirects them to Google's consent screen, they return to /callback, the code is exchanged, and a GoogleConnection row is written for the authenticated user. Redirects afterwards honor google.routes.redirect_after_connect and google.routes.redirect_after_error.

Registering scopes from a service package

Service packages contribute scopes via the ap.google.scopes filter hook (from artisanpack-ui/hooks):

use ArtisanPackUI\Hooks\Facades\Filter;

// In your service provider's boot() method:
Filter::add( 'ap.google.scopes', function ( array $scopes ): array {
    $scopes[] = 'https://www.googleapis.com/auth/analytics.readonly';
    return $scopes;
} );

At consent time the base package unions every contributed scope with the baseline (openid, userinfo.email, userinfo.profile) and de-duplicates. A single consent screen covers every dependent service — users don't get a per-package prompt.

Applications that need to add a scope without a service provider can call Google::scopes()->register( $scope ) at runtime instead.

Incremental consent

When a new service package is installed after the account is already connected, the scope registry starts returning scopes the connection doesn't hold. The connection-management component surfaces a Reauthorize action; the google.auth.reauthorize route hits OAuthManager::reauthorizationUrl() and asks Google for only the missing scopes with include_granted_scopes=true — Google merges the new grant with the existing one so the user isn't reprompted for scopes they've already approved.

If your app has its own UI, call the manager directly:

$granted = $connection->grantedScopes();
$url     = Google::oauth()->reauthorizationUrl( $userId, $granted );

Connection-management UI

The package ships three interchangeable connection-management components — one Livewire, one React, one Vue — all backed by the same routes and JSON status endpoint. Each shows:

  • A Connect Google button when the user is disconnected.
  • Connected as {email}, plus Disconnect and Reauthorize actions, when connected.
  • A prompt to reauthorize when the scope registry grows (see incremental consent above).
  • The scopes that will be requested (or that have been granted) in a collapsible details block.

Scope-limited to connect / disconnect / status by design — no per-service enable/disable toggles.

Livewire

If livewire/livewire is installed, mount:

<livewire:google-connection-manager />

React

The React and Vue components ship as source under resources/js/ — no prebuilt npm package. Either publish the assets into your app's tree:

php artisan vendor:publish --tag=google-js

…or point your bundler at the package directly. Then import:

import { GoogleConnectionManager } from '../vendor/google/react';
// or, if you kept the files inside vendor/ and Vite is configured to see them:
// import { GoogleConnectionManager } from '@artisanpack-ui/google/react';

export function IntegrationsPage() {
    return (
        <GoogleConnectionManager
            onDisconnected={ () => console.log( 'disconnected' ) }
        />
    );
}

Props (all optional):

Prop Type Default Purpose
statusUrl string /google/auth/status Override the status endpoint if you've changed google.routes.prefix.
csrfToken string | null Read from <meta name="csrf-token"> Sent as X-CSRF-TOKEN on the disconnect POST.
onDisconnected () => void Fires after a successful disconnect.
onStatusChanged (status) => void Fires whenever the status payload refreshes.
className string Appended to the root element's class.

Vue 3

<script setup lang="ts">
import { GoogleConnectionManager } from '../vendor/google/vue';
</script>

<template>
    <GoogleConnectionManager @disconnected="onDisconnected" />
</template>

Props and emits mirror the React component; see the source for the exact shape.

Building your own

The React and Vue components are a convenience. Any UI framework can consume:

  • GET /google/auth/status → JSON status payload.
  • GET /google/auth/connect → redirect to Google.
  • GET /google/auth/reauthorize → redirect for incremental consent.
  • POST /google/auth/disconnect → mark disconnected (send the CSRF token).

The same status payload the JS components consume is what the shared resources/js/shared/api.ts module type-encodes — use it as a reference for your own client.

Making API calls

Service packages retrieve a valid access token via the token manager. It refreshes transparently when the current token is within 60 seconds of expiring, and marks the connection disconnected on invalid_grant:

use ArtisanPackUI\Google\Facades\Google;

$connection = $user->googleConnection; // or however you load it
$token      = Google::tokens()->getValidAccessToken( $connection );

Http::withToken( $token )
    ->get( 'https://analyticsdata.googleapis.com/v1beta/...' );

Stateless OAuth primitives

Google::client() returns a GoogleClient that performs the Google OAuth calls without the session or database — useful for building an OAuth broker or storing tokens yourself:

use ArtisanPackUI\Google\OAuth\GoogleCredentials;

$client = Google::client( new GoogleCredentials( $clientId, $clientSecret, $redirectUri ) );

$url    = $client->authorizationUrl( $state, $scopes, [], $verifier );
$tokens = $client->exchangeCode( $code, $verifier );   // TokenResponse
$tokens = $client->refresh( $refreshToken );           // TokenResponse

$tokens->toArray(); // broker wire shape

See docs/stateless-client.md.

Configuration reference

Key options in config/google.php:

Key Default Meaning
client_id / client_secret / redirect_uri env(...) Credentials used by the config driver.
driver config Credential driver: config, database, or cms.
mode direct direct or broker.
broker.url / broker.site_id / broker.site_secret env(...) OAuth broker credentials (broker mode).
broker.return_url env(...) → callback route Where the broker sends the browser back.
endpoints.authorize Google auth URL Overridable for testing.
endpoints.token Google token URL Overridable for testing.
routes.enabled true Set false to skip the built-in web routes.
routes.prefix google/auth Prefix for the five package routes.
routes.middleware ['web'] Middleware applied to the built-in routes.
routes.redirect_after_connect / Path or route name to send users to after connect/disconnect.
routes.redirect_after_error / Path or route name for OAuth errors.
user_model App\Models\User The user model GoogleConnection belongs to.

Contributing

Please read through the contributing guidelines to learn more about how you can contribute to this project.