Getting Started

Minimal Steps

Install the Package Add to composer.json:
```
"require": {
    "google/cloud-common-protos": "^1.0"
}
```
Run composer install.
Verify Installation Check autoloaded classes:
```
composer dump-autoload
```
Verify the Google\Protobuf namespace is available.

First Use Case: Audit Logs Use the Google\Protobuf\Internal\Message base class to create a custom audit log entry:

use Google\Protobuf\Internal\Message;
use Google\Cloud\CommonProtos\AuditLog;

$logEntry = new AuditLog\LogEntry();
$logEntry->setTimestamp(new \Google\Type\Timestamp());
$logEntry->getTimestamp()->setSeconds(time());

Where to Look First

Generated Classes: Browse the Google Cloud PHP GitHub for protobuf definitions (e.g., AuditLog, Status, HttpRequest).
Laravel Integration: Use the package indirectly via Google Cloud SDKs (e.g., google/cloud-logging) to avoid manual protobuf handling.
Protobuf Docs: Refer to Google’s Protobuf Guide for schema design best practices.

Implementation Patterns

Usage Patterns

Indirect Usage via Google Cloud SDKs Most Laravel developers will use this package indirectly through SDKs like google/cloud-logging:
```
use Google\Cloud\Logging\LoggingClient;

$logging = new LoggingClient();
$entry = $logging->entry('my-log', [
    'severity' => 'INFO',
    'textPayload' => 'Test log entry'
]);
$logging->write($entry);
```
Under the hood, this uses google/cloud-common-protos for protobuf serialization.

Direct Protobuf Manipulation For custom gRPC services or advanced integrations, instantiate protobuf messages:

use Google\Cloud\CommonProtos\AuditLog\LogEntry;
use Google\Type\Timestamp;

$logEntry = new LogEntry();
$logEntry->setTimestamp(new Timestamp());
$logEntry->getTimestamp()->setSeconds(time());
$logEntry->setProtoPayload(file_get_contents('custom.proto'));

Laravel Service Container Integration Bind protobuf clients to Laravel’s container for dependency injection:
```
$this->app->bind('google.protobuf.audit-log', function ($app) {
    return new AuditLog\LogEntry();
});
```

Custom Protobuf Extensions Extend generated protobuf classes to add Laravel-specific fields:

class ExtendedLogEntry extends AuditLog\LogEntry {
    private $laravelUserId;

    public function setLaravelUserId(string $id): void {
        $this->laravelUserId = $id;
    }

    public function getLaravelUserId(): string {
        return $this->laravelUserId;
    }
}

Workflows

Audit Log Processing
- Use AuditLog\LogEntry to parse and generate audit logs for compliance.
- Example: Validate log entries against Google’s schema before storage:
```
$validator = new \Google\Protobuf\Internal\Validator();
$validator->validate($logEntry);
```

Error Handling with Status

Standardize API errors using Google\Rpc\Status:

$status = new \Google\Rpc\Status();
$status->setCode(\Google\Rpc\Code::INVALID_ARGUMENT);
$status->setMessage('Invalid input');
throw new \RuntimeException($status->serializeToJson());

HTTP Request Metadata

Attach HTTP context to logs using Google\Logging\Type\HttpRequest:

$httpRequest = new \Google\Logging\Type\HttpRequest();
$httpRequest->setRequestUrl('https://example.com/api');
$httpRequest->setRequestMethod('GET');
$logEntry->setHttpRequest($httpRequest);

Integration Tips

Laravel Logging Channel Create a custom logging channel to serialize protobuf messages:

$app['log']->extend('google_protobuf', function () {
    return new GoogleProtobufHandler();
});

gRPC Client Integration Use grpc/grpc with protobuf-generated clients:

$client = new MyServiceClient(
    new \Grpc\Channel('localhost:50051'),
    [
        'protobuf' => new \Google\Protobuf\Internal\Message()
    ]
);

Protobuf Schema Validation Validate incoming protobuf payloads:

use Google\Protobuf\Internal\Validator;

$validator = new Validator();
if (!$validator->validate($protobufPayload)) {
    throw new \InvalidArgumentException('Invalid protobuf payload');
}

Gotchas and Tips

Pitfalls

Extension Dependency
- Requires the google/protobuf PHP extension. Ensure your server has it installed:
```
pecl install google/protobuf
```
- Workaround: Use Docker with a preconfigured PHP image (e.g., google/cloud-sdk).

Immutable DTOs

Protobuf-generated classes are immutable by design. Use setters to modify fields:

// ❌ Won't work
$logEntry->timestamp = new Timestamp();

// ✅ Correct
$logEntry->setTimestamp(new Timestamp());

Schema Evolution
- Google’s protobuf schemas evolve. Always check for breaking changes in release notes.
- Tip: Use ^1.0 in composer.json to auto-update to non-breaking changes.
Binary vs. JSON Serialization
- Protobuf messages serialize to binary by default. Use serializeToJson() for interoperability:
```
$json = $logEntry->serializeToJson();
```
Namespace Conflicts
- Avoid naming collisions with Laravel’s namespaces (e.g., Google\Cloud vs. App\Google).

Debugging

Validate Protobuf Messages Use the Validator class to debug malformed messages:

$validator = new \Google\Protobuf\Internal\Validator();
$errors = $validator->validate($message);
dd($errors); // Debug validation issues

Inspect Generated Classes Dump the structure of a protobuf message:
```
dd(get_class_methods($logEntry));
```

Check for Deprecated Fields Some fields (e.g., ReservationResourceUsage) are deprecated. Use @deprecated annotations:

if (method_exists($message, 'getDeprecatedField')) {
    throw new \RuntimeException('Deprecated field used');
}

Tips

Use SDKs First Prefer Google Cloud SDKs (e.g., google/cloud-logging) over direct protobuf usage unless you need custom logic.

Leverage Laravel’s Macroable Extend protobuf classes with Laravel macros:

\Google\Cloud\CommonProtos\AuditLog\LogEntry::macro('toLaravelArray', function () {
    return [
        'timestamp' => $this->getTimestamp()->getSeconds(),
        'proto_payload' => $this->getProtoPayload()
    ];
});

Protobuf in Migrations Store protobuf payloads in Laravel migrations as JSON:

Schema::create('audit_logs', function (Blueprint $table) {
    $table->id();
    $table->json('protobuf_payload'); // Store serialized protobuf
    $table->timestamps();
});

Performance Optimization Reuse protobuf message instances to avoid serialization overhead:
```
$logEntry = new AuditLog\LogEntry();
// Reuse $logEntry across requests
```

Testing Protobuf Logic Use Laravel’s Mockery to test protobuf interactions:

$mockLogEntry = Mockery::mock(AuditLog\LogEntry::class);
$mockLogEntry->shouldReceive('getTimestamp')->andReturn(new Timestamp());

CI/CD Considerations Ensure your CI pipeline installs the google/protobuf extension:

# Example GitHub Actions
services:
  php:
    image: php:8.2-cli
    options: --entrypoint /bin/sh
before_script:
  - pecl install google/protobuf

Cloud Common Protos Laravel Package