Getting Started

Install the package as a require-dev dependency:

composer require google/cloud-tools --dev

The most immediate value is the flex_exec utility for running Laravel CLI commands in the exact App Engine Flex production environment. To start:

./vendor/bin/flex_exec run -- php artisan migrate

Before first use, ensure:

Your app is deployed to App Engine Flex
gcloud CLI is authenticated (gcloud auth login / gcloud auth application-default login)
Cloud Build service account has Cloud SQL Client role if accessing Cloud SQL

For testing, begin with Google\Cloud\TestUtils\TestTrait (validates env vars/credentials) and ExecuteCommandTrait (runs commands reliably in tests).

Implementation Patterns

Use `flex_exec` for production-accurate CLI workflows

Run migrations/seeds in the same environment as Flex prod:

vendor/bin/flex_exec run -- php artisan migrate:fresh --seed  
vendor/bin/flex_exec run -- php artisan queue:work --queue=high

Avoid discrepancies from local Docker (e.g., missing gmagick extension, differing timezone configs, or Cloud SQL socket paths).

Build resilient integration tests with test traits

Use TestTrait::checkEnv() to guard tests against missing GOOGLE_PROJECT_ID or GOOGLE_APPLICATION_CREDENTIALS.
Wrap flaky API calls (e.g., Cloud Storage uploads) with ExponentialBackoffTrait’s useResourceExhaustedBackoff().
Execute internal HTTP requests in tests using ExecuteCommandTrait::runCommand('curl ...') to validate endpoints end-to-end.

Integrate into Laravel-specific CI/CD

Leverage shared workflows (e.g., .github/workflows/ci-cs-fixer.yml) to enforce code style consistency across Laravel codebases.
Use FileUtil::copy() and FileUtil::move() in test helpers to manage temporary fixture files for storage/service tests.

Target specific services/versions

Override default deployment behavior via env vars:

GOOGLE_VERSION_ID=my-test-version vendor/bin/flex_exec run -- php artisan db:seed

Useful for testing against canary/staging versions before full rollout.

Gotchas and Tips

Environment variables are non-negotiable

flex_exec fails if GOOGLE_APPLICATION_CREDENTIALS is missing. Always set it in CI (-e GOOGLE_APPLICATION_CREDENTIALS=/creds.json).
In Laravel, .env is not loaded inside flex_exec. Explicitly set APP_ENV=production or pass --env=production to avoid config caching:
```
vendor/bin/flex_exec run -- bash -c "APP_ENV=production php artisan config:clear && php artisan migrate"  
```

Cloud SQL socket ≠ localhost

Your config/database.php must use DB_SOCKET (not DB_HOST) for Flex:

'connections' => [  
    'mysql' => [  
        'driver' => 'mysql',  
        'host' => env('DB_SOCKET', '127.0.0.1'), // Critical!  
        'database' => env('DB_DATABASE'),  
        ...  
    ],  
],

Billing surprises

Free tier covers ~120 build-min/day on Cloud Build. A single migrate call uses ~30s; in CI, runs multiply quickly. Monitor in Cloud Billing > Reports.

Testing gotchas

GOOGLE_SKIP_DEPLOYMENT=true skips all deployment steps (including beforeDeploy hooks) — useful for testing against existing prod deployments.
Set GOOGLE_KEEP_DEPLOYMENT=true during local debugging to inspect the deployed app (otherwise it’s auto-cleared post-test).

Laravel compatibility

Laravel 10+ with Symfony 7 works if flex_exec uses a Flex image with matching PHP/Symfony versions. Verify via php -v and composer show symfony/* in the Flex container.
Avoid hardcoded paths — Cloud Build runs with /workspace as CWD, not base_path(). Use __DIR__ or base_path() explicitly in test code.

Cloud Tools Laravel Package