Gsuite Checker Laravel Package

Getting Started

• Treat v1.0 as the baseline release. Pin the dependency (^1.0) until the public API and configuration shape are proven in your app.
• Install with Composer using the package name from the repository/Packagist entry, then confirm Laravel package auto-discovery. If the package does not auto-register, add its service provider and facade/alias manually.
• Publish any package config if the install docs expose a publish tag, then review the generated file before editing. The first place to look is the config file and README examples for:
  • configured Google Workspace domains
  • credential/authentication strategy
  • cache and HTTP client options
  • facade or injectable service name
• Configure the domains you expect to validate. If the package uses Google Admin/Directory APIs, add service-account credentials and the required scopes, and confirm domain-wide delegation per Workspace domain. If it only performs DNS/MX checks, no OAuth setup should be required.
• First practical use case: gate registration, SSO, invite flows, or contact forms so only emails/domains belonging to your approved Google Workspace tenant are accepted.

Conceptual usage once the package’s real class/facade names are confirmed:

$checker = app(/* package checker service */::class);

$isAllowed = $checker
    ->forDomains(config('gsuite.domains'))
    ->isGSuite($email);

Do not copy class names blindly; verify the actual facade/service and method names from the v1.0 README.

Implementation Patterns

• Inject the checker into form requests, actions, or dedicated validation rules instead of calling a facade deep in domain code. This keeps tests simple and lets you swap the implementation.
• Keep the domain allowlist in config/env rather than hard-coding it. Normalize entries by trimming whitespace, lowercasing, and stripping leading @ characters.
• For single-request validation, check only the submitted email/domain. For imports or admin screens, chunk large lists and avoid one remote/API call per row where possible.
• Cache domain/email results with a key that includes the tenant/domain and a sensible TTL. Workspace domains change less often than users, so domain-level caching is usually safer than long-lived email-level caching.
• Queue bulk checks and imports. Add rate limiting, retries with backoff, and logging around external API calls so a slow Google endpoint does not block web requests.
• Integrate as a Laravel validation rule or after-validation check. Return generic “email/domain not allowed” messages rather than revealing whether a specific mailbox exists.
• For multi-tenant apps, scope configuration, credentials, and cache keys per tenant. Never let one tenant’s cached domain result satisfy another tenant’s check.
• Log audit-friendly outcomes (accepted/rejected domain checks) without logging credentials, raw OAuth tokens, or unnecessary personal data.
• If the package exposes events or extension points, hook into them for metrics and alerting rather than wrapping every call site.

Gotchas and Tips

• The v1.0 release note is very terse. Read the README, config file, and any changelog before relying on method names or return types. There is no prior assessment or migration path to lean on.
• “GSuite” is legacy branding for Google Workspace. Confirm the checker handles current Workspace domains, aliases, and any legacy domains you still support.
• After changing domain lists or credentials in .env, run php artisan config:clear (or config:cache in deployment) before debugging. Cached config is a common source of “it ignores my new domain” issues.
• If using a service account, verify the JSON path is readable by the PHP process, the private key is intact, required scopes are granted, and domain-wide delegation is configured for every domain being checked.
• If the package uses DNS/MX checks instead of Google APIs, expect possible false positives/negatives from cached DNS, proxied domains, or non-Google mail routes. Prefer the API path when you need authoritative tenant membership.
• Watch Google API quotas and per-domain rate limits during imports. Use chunking, queuing, and backoff; do not retry aggressively on quota errors.
• Cache negative results carefully. A domain that is not Workspace today may become Workspace later; keep negative TTLs short or provide a manual refresh path.
• Debug with a single known email/domain in php artisan tinker, inspect the package exception messages, and log the high-level response status. Avoid dumping full credential payloads or private keys.
• Extension points to look for: custom HTTP client binding, cache store override, custom checker implementation, and package events. Prefer these over forking the package for small behavioral changes.
• Security: avoid exposing “this email exists in Google Workspace” to unauthenticated users. Use allowlist checks as an authorization gate, not as an account-enumeration endpoint.