README

A modern, fully-featured Laravel package for managing Google Workspace (formerly G Suite) using the latest Google Admin SDK API. Supports user management, group management, directory operations, and more.

Sponsor

Support the development of this package:

Features

✅ Modern PHP 8.2+ - Uses latest language features (readonly types, enums, named arguments)
✅ User Management - Create, read, update, delete, suspend, and manage user accounts
✅ Group Management - Full group CRUD operations and member management
✅ Directory API - Complete access to the Google Directory API
✅ Type-Safe DTOs - Data transfer objects for type safety
✅ Comprehensive Error Handling - Custom exceptions with detailed error information
✅ Logging Support - Built-in PSR-3 logging for all operations
✅ Fluent Interface - Simple, clean API for all operations
✅ Laravel 10-13 Support - Compatible with all modern Laravel versions
✅ Extensible - Easy to extend with custom services

Requirements

PHP 8.2 or higher
Laravel 10.0 or higher
Google Workspace account with admin access
Google Cloud Project with Admin SDK API enabled

Installation

composer require brickservers/gsuite

Publish Configuration

php artisan vendor:publish --provider="BrickServers\GoogleWorkspace\GoogleWorkspaceServiceProvider" --tag=config

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

Configuration

1. Set Up Google Cloud Project

Go to Google Cloud Console
Create a new project
Enable the "Google Admin SDK API"
Create a service account
Download the credentials JSON file
Move the file to storage/credentials.json (or configure the path)

2. Configure Environment Variables

Add these to your .env file:

GOOGLE_WORKSPACE_CREDENTIALS_PATH=/path/to/credentials.json
GOOGLE_WORKSPACE_DOMAIN=example.com
GOOGLE_WORKSPACE_SUBJECT=admin@example.com
GOOGLE_WORKSPACE_LOGGING=true

3. Update Configuration

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

'domain' => env('GOOGLE_WORKSPACE_DOMAIN', 'example.com'),
'credentials_path' => env('GOOGLE_WORKSPACE_CREDENTIALS_PATH', storage_path('credentials.json')),
'subject' => env('GOOGLE_WORKSPACE_SUBJECT'),
'scopes' => [
    'https://www.googleapis.com/auth/admin.directory.user',
    'https://www.googleapis.com/auth/admin.directory.group',
],

Usage

Basic Setup

use BrickServers\GoogleWorkspace\GoogleWorkspace;

// Via facade or service container
$workspace = app('google-workspace');

// Or using dependency injection
public function __construct(GoogleWorkspace $workspace)
{
    $this->workspace = $workspace;
}

User Management

Create a User

use BrickServers\GoogleWorkspace\DTOs\UserDTO;

$user = new UserDTO(
    email: 'john.doe@example.com',
    givenName: 'John',
    familyName: 'Doe',
    password: 'SecurePassword123!',
    changePasswordAtNextLogin: true,
);

$created = $workspace->users()->create($user);

Get a User

$user = $workspace->users()->get('john.doe@example.com');

// With projection and view type
use BrickServers\GoogleWorkspace\Enums\UserProjection;
use BrickServers\GoogleWorkspace\Enums\UserViewType;

$user = $workspace->users()->get(
    'john.doe@example.com',
    projection: UserProjection::FULL,
    viewType: UserViewType::ADMIN_VIEW,
);

List Users

$result = $workspace->users()->list(maxResults: 100);

$users = $result['users']; // Array of UserDTO
$nextPageToken = $result['nextPageToken']; // For pagination

Update a User

$updates = new UserDTO(
    email: 'john.doe@example.com',
    givenName: 'Johnny',
    familyName: 'Doe',
);

$updated = $workspace->users()->update('john.doe@example.com', $updates);

Delete a User

$workspace->users()->delete('john.doe@example.com');

Suspend/Unsuspend a User

// Suspend
$workspace->users()->suspend('john.doe@example.com');

// Unsuspend
$workspace->users()->unsuspend('john.doe@example.com');

Manage User Aliases

// Add alias
$workspace->users()->addAlias('john.doe@example.com', 'j.doe@example.com');

// Remove alias
$workspace->users()->removeAlias('john.doe@example.com', 'j.doe@example.com');

Group Management

Create a Group

use BrickServers\GoogleWorkspace\DTOs\GroupDTO;

$group = new GroupDTO(
    email: 'developers@example.com',
    name: 'Development Team',
    description: 'All developers in the organization',
);

$created = $workspace->groups()->create($group);

Get a Group

$group = $workspace->groups()->get('developers@example.com');

List Groups

$result = $workspace->groups()->list(maxResults: 100);

$groups = $result['groups']; // Array of GroupDTO
$nextPageToken = $result['nextPageToken']; // For pagination

Update a Group

$updates = new GroupDTO(
    email: 'developers@example.com',
    name: 'Dev Team',
    description: 'Updated description',
);

$updated = $workspace->groups()->update('developers@example.com', $updates);

Delete a Group

$workspace->groups()->delete('developers@example.com');

Manage Group Members

// Add member
$workspace->groups()->addMember('developers@example.com', 'john.doe@example.com');

// Remove member
$workspace->groups()->removeMember('developers@example.com', 'john.doe@example.com');

Error Handling

The package throws GoogleWorkspaceException for all API errors:

use BrickServers\GoogleWorkspace\Exceptions\GoogleWorkspaceException;

try {
    $workspace->users()->create($user);
} catch (GoogleWorkspaceException $e) {
    // Handle specific errors
    if ($e->getCode() === 5) {
        // Resource not found
    }
    
    logger()->error('Google Workspace API error: ' . $e->getMessage());
}

Exception Types

GoogleWorkspaceException::validationError() - Validation failed
GoogleWorkspaceException::resourceNotFound() - Resource doesn't exist
GoogleWorkspaceException::undeletableResource() - Protected resource
GoogleWorkspaceException::apiError() - General API error
GoogleWorkspaceException::accessDenied() - Insufficient permissions
GoogleWorkspaceException::missingCredentials() - Credentials not configured

Data Transfer Objects (DTOs)

UserDTO

new UserDTO(
    email: string,
    givenName: string,
    familyName: string,
    password: ?string = null,
    changePasswordAtNextLogin: bool = true,
    suspended: bool = false,
    phone: ?string = null,
    title: ?string = null,
    customSchemas: ?array = null,
)

GroupDTO

new GroupDTO(
    email: string,
    name: ?string = null,
    description: ?string = null,
)

Enums

UserProjection

UserProjection::BASIC    // Basic information only
UserProjection::FULL     // Full user information
UserProjection::CUSTOM   // Custom schema information

UserViewType

UserViewType::ADMIN_VIEW      // Admin perspective
UserViewType::DOMAIN_PUBLIC   // Public domain view

ApiScope

Predefined OAuth scopes for different APIs:

ApiScope::DIRECTORY_USER
ApiScope::DIRECTORY_GROUP
ApiScope::CLASSROOM_COURSES
ApiScope::CALENDAR
ApiScope::GMAIL_COMPOSE
ApiScope::DRIVE
// ... and more

Migration from Old Package

If you're upgrading from wyattcast44/gsuite or brickservers/gsuite:

Changes Summary

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

Migration Steps

Before (Old Package)

GSuite::accounts()->create([
    ['first_name' => 'John', 'last_name' => 'Doe'],
    'email' => 'john.doe@example.com',
    'default_password' => 'password'
]);

After (New Package)

use BrickServers\GoogleWorkspace\DTOs\UserDTO;

$user = new UserDTO(
    email: 'john.doe@example.com',
    givenName: 'John',
    familyName: 'Doe',
    password: 'password',
);

app('google-workspace')->users()->create($user);

Testing

composer test

Run with coverage:

composer test-coverage

Debugging

Enable logging in your .env:

GOOGLE_WORKSPACE_LOGGING=true

View logs in storage/logs/laravel.log to see all API operations.

Supported APIs

✅ Google Admin Directory API
✅ Google Classroom API (ready)
✅ Google Calendar API (ready)
✅ Google Gmail API (ready)
✅ Google Drive API (ready)

Security Best Practices

Never commit credentials.json - Add to .gitignore
Use environment variables - Store sensitive data in .env
Limit API scopes - Only request scopes your app needs
Enable logging - Monitor all API operations
Use protected resources - Add critical accounts/groups to undeletable list
Validate input - DTOs provide validation out of the box

Performance Tips

Use pagination - Always set maxResults parameter
Cache results - Store frequently accessed data
Batch operations - Group multiple API calls when possible
Enable logging selectively - Disable in production if not needed

Contributing

Contributions are welcome! Please follow Laravel coding standards and include tests.

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 with the Google Admin SDK

brickservers / gsuite

Maintainers

Package info

Statistics

Security