Kiota Serialization Text Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require microsoft/kiota-serialization-text
   

   Add to composer.json if preferred:

   "require": {
       "microsoft/kiota-serialization-text": "^2.0.2"
   }
   

2. First Use Case:

   • Integrate with a Kiota-generated client (e.g., from kiota-php).
   • Register the text serializer in your Kiota client configuration:

     use Microsoft\Kiota\Serialization\Text\TextSerializer;
     
     $serializer = new TextSerializer();
     $client = new YourKiotaClient($serializer);
     

3. Where to Look First:

   • README: Focus on the kiota-php repo for client generation and usage.
   • Source Code: Explore src/TextSerializer.php for core logic (e.g., serializeObject(), deserializeObject()).
   • Tests: Check tests/ for examples of text/plain serialization/deserialization (e.g., handling raw strings, line breaks).

Implementation Patterns

Core Workflows

1. Serialization:

   • Use for APIs returning plain-text responses (e.g., CSV, logs, or simple key-value pairs).
   • Example:

     $response = $client->get('/api/data');
     $plainTextData = $response->parseContent(); // Returns string
     

2. Deserialization:

   • Parse text/plain into structured objects (if your model supports it).
   • Example:

     $serializer = new TextSerializer();
     $object = $serializer->deserializeObject(
         'key1:value1\nkey2:value2',
         YourModel::class
     );
     

3. Integration with Kiota Clients:

   • Request Body: Send plain-text payloads:

     $requestInfo = new RequestInformation();
     $requestInfo->setBody('plain text content');
     $requestInfo->setContentType('text/plain');
     

   • Response Handling: Override default JSON parsing for text responses:

     $response = $client->request($requestInfo);
     $textContent = $response->getBody();
     

4. Custom Model Support:

   • Extend TextSerializer to handle custom formats (e.g., CSV-to-array):

     class CustomTextSerializer extends TextSerializer {
         public function deserializeObject(string $serializedObject, string $type): object {
             if ($type === CustomModel::class) {
                 return $this->csvToModel($serializedObject);
             }
             return parent::deserializeObject($serializedObject, $type);
         }
     }
     

Best Practices

• Content-Type Headers: Always set Content-Type: text/plain for requests/responses.
• Error Handling: Validate plain-text responses for malformed data (e.g., missing delimiters).
• Performance: Avoid complex deserialization for large texts; stream or chunk if needed.

Gotchas and Tips

Pitfalls

1. No Automatic Parsing:

   • Unlike JSON/XML, text/plain requires manual parsing logic. Example:

     // ❌ Fails silently:
     $serializer->deserializeObject('raw text', YourModel::class);
     // ✅ Workaround: Pre-process text into a known format (e.g., JSON string).
     

2. Line Endings:

   • Inconsistent line endings (\n vs \r\n) may break deserialization. Normalize with:

     $normalizedText = str_replace(["\r\n", "\r"], "\n", $rawText);
     

3. Kiota Client Generation:

   • Ensure your Kiota OpenAPI spec includes contentType: text/plain for relevant endpoints. Otherwise, the client may default to JSON.

4. Circular References:

   • The serializer lacks built-in support for circular references (unlike JSON). Flatten objects or use @ignore annotations:

     #[IgnoreProperty]
     public ?Self $selfReference;
     

Debugging Tips

• Log Raw Responses:

  $response = $client->request($requestInfo);
  file_put_contents('debug.txt', $response->getBody());
  

• Validate Serialization:
  • Use serializeObject() to debug object-to-text conversion:

    $text = $serializer->serializeObject($yourObject);
    var_dump($text); // Check for expected format
    

• Test Edge Cases:
  • Empty strings, special characters (\n, \t), or Unicode may require custom handling.

Extension Points

1. Custom Serializers:

   • Extend TextSerializer to support domain-specific formats (e.g., Markdown, INI):

     class MarkdownSerializer extends TextSerializer {
         public function deserializeObject(string $serializedObject, string $type): object {
             // Parse Markdown to your model
         }
     }
     

2. Middleware:

   • Add pre/post-processing middleware for text requests/responses:

     $client->addRequestMiddleware(function ($requestInfo) {
         $requestInfo->setBody(gzip_compress($requestInfo->getBody()));
     });
     

3. Kiota Abstractions:

   • Use SerializationContext to dynamically switch serializers:

     $context = new SerializationContext();
     $context->setSerializer(new TextSerializer());
     $client->setRequestAdapter(new RequestAdapter($context));
     

Config Quirks

• No Built-in Config:
  • The library is lightweight; configure via constructor or dependency injection:

    $serializer = new TextSerializer([
        'delimiter' => '|', // Customize for your use case
    ]);
    

• Compatibility:
  • Test with Kiota v2+ (older versions may lack text/plain support). Check kiota-php releases.