Laravel Google Drive Storage Laravel Package

Getting Started

1. Install and publish config:

composer require yaza/laravel-google-drive-storage
php artisan vendor:publish --provider="Yaza\LaravelGoogleDriveStorage\LaravelGoogleDriveStorageServiceProvider"

2. In Google Cloud, enable the Drive API and create OAuth client credentials. Generate a refresh token for the Google account that owns (or can access) the target Drive folder. A service account works only if the folder is shared with it — see the service-account caveat below.

3. Add a disk to config/filesystems.php using the keys from the published config/google-drive.php:

'google' => [
    'driver' => 'google',
    'clientId' => env('GOOGLE_DRIVE_CLIENT_ID'),
    'clientSecret' => env('GOOGLE_DRIVE_CLIENT_SECRET'),
    'refreshToken' => env('GOOGLE_DRIVE_REFRESH_TOKEN'),
    'folder' => env('GOOGLE_DRIVE_FOLDER_ID'),
],

4. Smoke-test:

Storage::disk('google')->put('hello.txt', 'Hello from Laravel');
Storage::disk('google')->get('hello.txt');

Look first at the published config and the package service provider to confirm the registered driver name and config keys, then config/filesystems.php. The first practical use case is offloading generated artifacts — invoices, exports, backups, or user uploads — to a shared Drive folder without writing Google API code. Keep the disk name generic (google) so local/test environments can swap in local or public.

Implementation Patterns

• Use Laravel’s Storage facade, not raw API calls. The driver exposes normal Flysystem operations: put, putFile, putFileAs, get, readStream, exists, delete, files, allFiles, directories. This keeps your code portable and testable.
• Deterministic names. Drive allows duplicate filenames. Prefer putFileAs('invoices', $file, "{$invoice->id}.pdf") and explicitly delete/replace the old object rather than assuming put overwrites.
• Queue uploads. Wrap Drive writes in jobs with retries and backoff. Google API latency and rate limits make synchronous uploads in request cycles fragile.
• Store paths, not URLs. Persist the relative path (invoices/2025/123.pdf) in the database. Resolve links at render time via the driver’s url() or a small proxy controller if the file must be private.
• Prefix by environment/tenant. Use the configured root folder as a bucket equivalent and write under prod/tenant-42/.... This keeps one Drive account usable across apps and stages.
• Stream large files. Use writeStream/readStream and Storage::disk('google')->download() responses rather than loading entire files into memory.
• Facade for one-offs. The package facade is convenient in artisan commands and seeders, but prefer the Storage disk in application code so you can fake it in tests.
• Backup integration. Many Laravel backup packages accept a custom filesystem disk; register this disk and point backups at it, but verify retention/deletion behavior first.

Gotchas and Tips

• Refresh-token expiry. If the OAuth consent screen is in “Testing”, refresh tokens expire after roughly seven days. Publish the app or use a properly delegated service account.
• Service accounts have no Drive quota. They cannot own files in My Drive. Use a shared drive or domain-wide delegation, and share the target folder explicitly.
• Not a real filesystem. Renames and moves are expensive, there are no atomic operations, and listings are paginated and slow. Cache directory listings and avoid allFiles() on large trees.
• Rate limits. Expect 403 rateLimitExceeded / userRateLimitExceeded. Implement exponential backoff and batch work where possible.
• URLs are not automatically public. url() may return a Drive web link that only the owning account can open. Set permissions through the API or serve files through your own authenticated route.
• Folder ID confusion. The folder config is an ID, not a path. Confirm the folder is shared with the authenticated identity; a wrong ID typically surfaces as a 404 during the first write.
• Large uploads and timeouts. Increase job and HTTP timeouts, use resumable/streamed uploads, and watch PHP memory limits.
• Debugging. Catch Google\Service\Exception, log getErrors(), and enable Guzzle/Google client logging temporarily. Run php artisan config:clear after changing env values.
• Maturity risk. This is a small, single-maintainer package with few dependents. Pin the version, wrap Drive access behind a small interface or service class, and keep an integration test against a dedicated Drive folder so you can swap drivers later.
• Extension point. If you need custom behavior, register your own filesystem driver with Storage::extend('google', ...) or bind a customized adapter rather than editing vendor code.