Protobuf Php Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require centraldesktop/protobuf-php
   

   Ensure protoc (v2.3+) is installed and in your PATH.

2. Generate PHP Classes:

   protoc --plugin=protoc-gen-php --php_out=./generated tutorial.proto
   

   For custom options (e.g., php.namespace), include the php.proto file:

   protoc -I=./vendor/centraldesktop/protobuf-php/library/DrSlump/Protobuf/Compiler/protos \
          --plugin=protoc-gen-php --php_out=./generated tutorial.proto
   

3. First Use Case:

   use Generated\Tutorial\Person;
   
   $person = new Person();
   $person->name = 'John Doe';
   $person->setId(42);
   
   // Serialize to binary
   $binaryData = $person->serialize();
   
   // Deserialize
   $decodedPerson = Person::parseFrom($binaryData);
   

Implementation Patterns

Core Workflows

1. Code Generation:

   • Use the protoc plugin to generate PHP classes from .proto files.
   • Customize templates (e.g., php.tpl) for advanced use cases (e.g., adding validation logic).
   • Example: Override php.tpl to inject custom setters/getters:

     // In your custom template:
     {foreach $fields}
     public function setCustom{$field.name}({$field.type} $value) {
         $this->set{$field.name}($value);
         // Add custom logic here
     }
     {/foreach}
     

2. Serialization/Deserialization:

   • Binary (Default):

     $data = $message->serialize(); // Binary
     $decoded = Message::parseFrom($data);
     

   • Alternative Codecs (e.g., JSON, XML):

     $codec = new \DrSlump\Protobuf\Codec\Json();
     $jsonData = $codec->encode($message);
     $decoded = $codec->decode($jsonData, Message::class);
     

3. Dynamic Messages:

   • Create messages on-the-fly without code generation:

     $dynamicMessage = new \DrSlump\Protobuf\DynamicMessage();
     $dynamicMessage->setField('name', 'Dynamic Value');
     $data = $dynamicMessage->serialize();
     

4. Lazy Decoding:

   • Improve performance by decoding fields only when accessed:

     $message = Message::parseFrom($data);
     $fieldValue = $message->getLazyField('field_name')->getValue(); // Decodes on access
     

Integration Tips

• Validation: Use PHP’s type hints (e.g., int, string) in generated classes for IDE autocompletion and runtime validation.
• APIs: Leverage generated interfaces for gRPC or REST APIs (e.g., Tutorial\ServiceInterface).
• Testing: Mock generated classes with tools like PHPUnit:

  $mock = $this->getMockBuilder(Message::class)
               ->disableOriginalConstructor()
               ->onlyMethods(['getField'])
               ->getMock();
  

Gotchas and Tips

Pitfalls

1. Integer Handling:

   • Negative values in int32, int64, or fixed64 require GMP or BC Math extensions. Fix: Enable extensions or use zigzag encoding (if supported by your .proto).
   • Unsigned integers > PHP_INT_MAX (e.g., uint64) may lose precision. Workaround: Use double or validate inputs.

2. String Encoding:

   • Binary codec assumes UTF-8 strings. Non-UTF-8 strings may corrupt data. Fix: Encode strings explicitly:

     $message->setName(mb_convert_encoding($name, 'UTF-8'));
     

3. Memory Usage:

   • Large messages (e.g., >10MB) may cause out-of-memory errors. Workaround: Stream processing (not natively supported; consider chunking or external tools).

4. Unknown Fields:

   • Unknown fields in binary format won’t serialize to other codecs (e.g., JSON). Tip: Use UnknownFieldSet for inspection:

     $unknownFields = $message->getUnknownFields();
     

5. Breaking Changes:

   • Version 0.6.0+ uses Option return types for getters (e.g., getName() → Option<string>). Fix: Update calls to handle Option objects:

     if ($message->getName()->isPresent()) {
         $name = $message->getName()->get();
     }
     

Debugging Tips

• Validate .proto Files: Use protoc --decode_raw to inspect binary data:

  protoc --decode_raw --decode_raw_input=binary data.bin
  

• Log Serialized Data: Dump binary/JSON for debugging:

  file_put_contents('debug.bin', $message->serialize());
  

• Check Codec Compatibility: Ensure codecs (e.g., JSON vs. binary) handle your message structure identically.

Extension Points

1. Custom Codecs: Implement \DrSlump\Protobuf\Codec\CodecInterface for new formats (e.g., Avro):

   class CustomCodec implements CodecInterface {
       public function encode($message) { ... }
       public function decode($data, $className) { ... }
   }
   

2. Template Overrides: Extend php.tpl to modify generated classes (e.g., add timestamps):

   // In your custom template:
   {foreach $fields}
   public $createdAt;
   {/foreach}
   

3. Dynamic Annotations: Use @protobuf.annotation in .proto files to customize behavior:

   message User {
     optional string name = 1 [protobuf.annotation = "validate:min=3"];
   }
   

   Note: Requires custom template logic to process annotations.

Configuration Quirks

• Namespace Handling: Use php.namespace in .proto to avoid collisions:

  option php.namespace = "App\\Protobuf";
  

• Multifile Generation: Enable with -Dmultifile=true to generate classes across multiple files:

  protoc-gen-php -o ./generated -Dmultifile=true *.proto