Download the PHP package brickservers/gsuite without Composer

Google Workspace SDK for Laravel

A Laravel package for managing Google Workspace (formerly G Suite). Friendly repositories for users and groups, plus every method of the Admin SDK Directory, Classroom, Calendar, Gmail and Drive APIs, with error handling, audit logging and safety rails built in.

Sponsor

Support the development of this package:

Features

• ✅ Modern PHP 8.2+ - Uses latest language features (readonly types, enums, named arguments)
• ✅ Every Google API Method - All 413 methods of the Directory, Classroom, Calendar, Gmail and Drive APIs
• ✅ Act as Any User - asUser() for Gmail settings, calendars and Drive files via domain-wide delegation
• ✅ User Management - Create, read, update, delete, suspend, and manage user accounts
• ✅ Group Management - Full group CRUD operations and member management
• ✅ Batch Operations - Bulk creates and membership changes sent as Google batch requests
• ✅ Pagination Helpers - Iterate every user or group with all()
• ✅ Type-Safe DTOs - Partial updates: only the fields you set are sent
• ✅ Precise Error Handling - Not found, access denied and rate limits are reported as such
• ✅ Audit Logging - Every change is logged through PSR-3 / Laravel logging
• ✅ Safety Rails - Protected accounts and groups, opt-in admin promotion
• ✅ Retries & Timeouts - Configurable backoff for transient failures
• ✅ Laravel 12 & 13 - Supports the current Laravel releases
• ✅ Mockable - Repository contracts for dependency injection and testing

Requirements

• PHP 8.2 or higher
• Laravel 12 or 13 (Laravel 13 needs PHP 8.3+)
• Google Workspace account with super admin access (to set up domain-wide delegation)
• Google Cloud project with the APIs you use enabled (Admin SDK at minimum)

Installation

Publish Configuration

This will publish the configuration file to config/google-workspace.php.

Configuration

1. Set Up Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project
3. Enable the Admin SDK API, plus the Classroom, Calendar, Gmail or Drive APIs if you use them
4. Create a service account and download its JSON key
5. Move the key to storage/credentials.json (or set GOOGLE_WORKSPACE_CREDENTIALS_PATH)
6. In the Google Admin console, go to Security → Access and data control → API controls → Domain-wide delegation, add the service account's client ID, and authorize the scopes from your config (and any you pass to asUser())

2. Configure Environment Variables

Add these to your .env file:

GOOGLE_WORKSPACE_SUBJECT is required: it is the admin account the service account impersonates through domain-wide delegation.

3. Update Configuration

Edit config/google-workspace.php to customize settings:

The default scopes cover the users and groups repositories. If you use other parts of the API through directory(), classroom(), calendar(), gmail() or drive(), add the scopes they need and authorize them for the service account in the Google Admin console. Google's service classes define a constant for every scope, e.g. Google\Service\Directory::ADMIN_DIRECTORY_ORGUNIT or Google\Service\Calendar::CALENDAR.

Usage

Basic Setup

User Management

Create a User

givenName and familyName are required when creating. New users must change their password at next login unless you pass changePasswordAtNextLogin: false.

Get a User

List Users

Update a User

Only the fields you set are sent; everything else is left unchanged.

Setting email to a different address renames the user. Protected users cannot be renamed.

Delete a User

Users in the undeletable list cannot be deleted, renamed or suspended, whether you refer to them by email (any case), alias or user ID.

Suspend/Unsuspend a User

Make a User a Super Admin

Disabled by default because it grants full control of the domain. Enable it with GOOGLE_WORKSPACE_ALLOW_ADMIN_PROMOTION=true; otherwise an access denied exception (code 403) is thrown.

Manage User Aliases

Group Management

Create a Group

Get a Group

List Groups

Update a Group

Delete a Group

Manage Group Members

Full API Access

Every resource and method of the Directory, Classroom, Calendar, Gmail and Drive APIs is available through directory(), classroom(), calendar(), gmail() and drive(). Resource and method names match Google's PHP client (and its API reference), and arguments and return values are Google's own model classes:

Every call:

• turns Google errors into GoogleWorkspaceException with the codes listed under Error Handling,
• writes a log entry for anything that changes data,
• applies the same protections as the repositories: protected users and groups can't be deleted, renamed or (users) suspended, and super admin can't be granted, through makeAdmin or a Super Admin role assignment, unless allow_admin_promotion is on.

For anything else, ->google() returns the underlying Google\Service\* object.

Acting as a User

Gmail, Calendar and Drive mostly work on a particular user's data. asUser() impersonates that user through domain-wide delegation:

The impersonated account needs the right scopes. By default asUser() uses the configured scopes; pass others as the second argument. Every scope must be authorized for the service account under Security → API controls → Domain-wide delegation in the Google Admin console. Google's service classes define constants for each scope:

users(), groups() and batch() always act as the configured admin, even after asUser().

Paginating Any List

Pass the list method's name followed by its normal arguments.

Batch Operations

Bulk user creation and group membership changes are sent as Google batch requests (up to 1000 calls per HTTP request). Each item succeeds or fails on its own:

Error Handling

The package throws GoogleWorkspaceException for all API errors:

Exception Codes

Transient failures (5xx, rate limits, network errors) are retried automatically according to the retry settings before an exception is thrown.

Data Transfer Objects (DTOs)

UserDTO

null means "not set": the field is left out of API requests. An empty email is also left out.

GroupDTO

Enums

UserProjection

UserViewType

ApiScope

Common OAuth scopes:

For the complete list, use the constants on Google's service classes (e.g. Google\Service\Gmail::GMAIL_SETTINGS_SHARING).

Migration from Old Package

See MIGRATION.md for full upgrade guides, including the breaking changes in 3.0. If you're upgrading from wyattcast44/gsuite:

Changes Summary

1. Namespace Changed: Wyattcast44\GSuite → BrickServers\GoogleWorkspace
2. New DTOs: Use UserDTO and GroupDTO instead of raw arrays
3. Type-Safe: All methods now have proper type hints
4. Better Errors: Custom exception types for better error handling
5. Modern PHP: Uses PHP 8.2+ features (enums, readonly types, named arguments)

Migration Steps

Before (Old Package)

After (New Package)

Testing

Run with coverage:

Logging

Every change made through the package is logged: repository actions (creates, updates, deletes, suspensions, aliases, membership changes, admin promotions) and every non-read call through the API wrappers, recorded as Google Workspace API change with the method (e.g. gmail.usersSettings.updateVacation), its ID arguments and, after asUser(), the impersonated account. Request bodies are not logged.

Logs go to your application's default channel. Send them elsewhere with GOOGLE_WORKSPACE_LOG_CHANNEL, or turn logging off with GOOGLE_WORKSPACE_LOGGING=false.

Supported APIs

Every method of these Google APIs is available, with Google's own documentation on each method:

Users and groups also have the friendlier repositories documented above.

Security Best Practices

1. Never commit credentials.json - Add to .gitignore
2. Use environment variables - Store sensitive data in .env
3. Limit API scopes - Only request and authorize the scopes your app needs; domain-wide delegation lets the service account act as any user for those scopes
4. Keep audit logging on - Every change is logged by default
5. Use protected resources - Add critical accounts/groups to the undeletable list (emails, aliases or IDs)
6. Leave admin promotion off - Only enable allow_admin_promotion if your app really needs it
7. Authorize your own users - The package acts with full admin rights, and asUser() can reach any user's mail, calendar and files; check in your app who may trigger each action

Performance Tips

1. Iterate with all() / paginate() - Pages are fetched lazily instead of loading everything at once
2. Cache results - Store frequently accessed data
3. Use batch() - Bulk creates and membership changes need far fewer HTTP requests
4. Tune retries - Raise retry.max_attempts for large jobs that hit rate limits

Contributing

The API wrappers in src/Api/{Directory,Classroom,Calendar,Gmail,Drive} are generated. Don't edit them by hand: run composer generate-api after updating google/apiclient-services to pick up new Google endpoints.

Contributions are welcome! Please include tests, and run composer test, composer lint and composer analyze before opening a pull request (CI runs all three).

Changelog

See CHANGELOG.md for version history and breaking changes.

License

The MIT License (MIT). Please see License File for more information.

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Credits

• Modern rewrite by BrickServers Team
• Original package by Wyatt Cast
• Built on the Google APIs Client Library for PHP