Kiota Serialization Text Laravel Package

Getting Started

Treat this as an internal part of the Kiota stack, not a standalone utility you reach for like guzzlehttp/guzzle or league/csv. It is a single-purpose implementation of SerializationWriter / ParseNodeFactory for text/plain, and it only earns its place in a Laravel app that already talks to a Kiota-generated PHP client (Microsoft Graph, Azure SDKs, or an in-house Kiota-generated SDK).

1. Check the prerequisites before anything else. The 2.x line requires PHP 8.2+ and is version-locked to microsoft/kiota-abstractions. If your app is on 8.1 or you have a generated SDK pinned to the 1.x abstraction family, stop here — you'll spend the afternoon on Composer conflicts instead of shipping features.
2. Install it alongside the rest of the family, not alone:

   composer require microsoft/kiota-serialization-text microsoft/kiota-abstractions
   

   In practice you normally get it transitively from a generated SDK's composer.json. Only require it explicitly if you are wiring a hand-written Kiota client.
3. Read these three things in order, because the repo's README is deliberately thin:
   • The README (install + "issues go to kiota-php", nothing more).
   • microsoft/kiota-abstractions — the SerializationWriter, ParseNode, SerializationWriterFactory and ParseNodeFactory interfaces. That is the real contract this package implements.
   • The kiota-php monorepo (source of truth for code and issues; this repo is release-only).
4. First realistic use case: a Kiota-generated client calls an endpoint that returns text/plain (a status message, a raw token, a legacy SOAP-ish payload). Generated clients ship a JSON factory by default, so the response parsing throws or returns null until you register a factory that also understands text/plain. That single registration is the entire "hello world" of this package.

Implementation Patterns

Register the factories with the request adapter. The generated client gives you an adapter; you supply the factory. Because a real app usually needs JSON and text, wrap them in a delegating factory rather than replacing the default one:

// app/Http/Kiota/CompositeWriterFactory.php
final class CompositeWriterFactory implements SerializationWriterFactory
{
    private array $byContentType;

    public function __construct(SerializationWriterFactory ...$factories)
    {
        foreach ($factories as $f) {
            $this->byContentType[$f->getValidContentType()] = $f;
        }
    }

    public function getSerializationWriter(string $contentType): SerializationWriter
    {
        return $this->byContentType[$contentType]
            ?? throw new InvalidArgumentException("No writer for {$contentType}");
    }

    public function getValidContentType(): string { return 'application/json'; } // registry key
}

Do the mirror image with ParseNodeFactory for responses. Register both inside a small Laravel service provider so the wiring lives in one place instead of being copy-pasted into every action.

Wrap Kiota calls in a service, not a controller. Kiota's fluent request builders ($client->users()->byId($id)->messages()->get()) are verbose and hard to fake. Keep them behind an interface (GraphMailer, AzureTokenClient) that Laravel's container resolves, and let controllers/Jobs depend on the interface. This is the pattern that buys you testability; the serialization package itself has no test double.

Use it directly when you need to hand-build a text body. For requests, construct the writer, write the scalar, and rewind the stream before reading:

$writer = new TextSerializationWriter();
$writer->writeStringValue(null, $payload);   // null = root value
$stream = $writer->getSerializedContent();
$stream->rewind();
$body = $stream->getContents();

Respect the "scalar only" model. This provider serializes a string. If the API returns CSV, pipe-delimited records, or JSON smuggled inside a text/plain content type, do not expect writeObjectValue / getObjectValue to produce a structured tree — you write the raw string and do the parsing yourself (a dedicated parser class, league/csv, json_decode after stripping a BOM, etc.). Composed-type support exists (added in 0.5.0), but it is about Kiota's object model, not about magically making plain text structured.

Match the version family across the board. Every changelog entry in this repo is essentially "synchronize microsoft-kiota-php versions." Bump kiota-abstractions, kiota-http, kiota-serialization-json and this package together, in one PR, and pin them in composer.json with the same minor constraint.

Gotchas and Tips

• No Laravel integration exists, and none is coming. No service provider, no config/kiota.php, no facade. If you're searching for one, you're looking at the wrong package — do the wiring yourself in AppServiceProvider.
• getSerializedContent() returns a StreamInterface. Reading it without rewind() yields an empty string and a very confusing debugging session. Same when you pass it to an HTTP client.
• Content-Type lookups fail on parameters. Servers frequently send text/plain; charset=utf-8. If your factory map keys on the exact string, lookup misses and Kiota throws or silently returns null. Normalize (strtok($contentType, ';'), trim, lowercase) in your delegating factory.
• Method signature drift is the main breaking-change vector. Changelog 0.7.0 shows writeObjectValue parameters changing to match abstractions. If you implement or subclass anything from the abstractions, or you mix a 1.x abstraction with a 2.x serializer, you get fatal signature errors at autoload time. Keep versions aligned and let Composer resolve.
• A php-http/discovery quirk bit this package before (0.7.1 disabled the discovery plugin). If you hit odd PSR-18 adapter resolution in a Laravel app that already has Guzzle, check that you aren't fighting the generated client's HTTP transport rather than the serializer.
• Debugging order: (1) log the raw response body and the exact Content-Type header; (2) confirm the factory you expect is registered on the adapter; (3) confirm the version family matches. Nine times out of ten the bug is (2), and the code is actually working.
• Extension point: if you need a custom media type, implement SerializationWriter/ParseNode from kiota-abstractions rather than forking this package. The abstraction is small and stable; the concrete text implementation is intentionally minimal.
• Community support is effectively zero. Seven stars, zero dependents, release-only repo, issues redirected elsewhere. Budget for reading kiota-php source and tests directly — Stack Overflow will not help you.