How can I handle different response content types in Guzzle?

When working with web scraping and API integrations using Guzzle, you'll encounter various response content types including JSON, XML, HTML, plain text, and binary data. Properly handling these different content types is crucial for building robust applications that can process diverse data sources effectively.

Understanding Response Content Types

Guzzle automatically detects content types through HTTP response headers, specifically the Content-Type header. However, you often need to implement specific logic to parse and process different content types appropriately.

Basic Content Type Detection

<?php
use GuzzleHttp\Client;

$client = new Client();
$response = $client->get('https://api.example.com/data');

// Get the content type from response headers
$contentType = $response->getHeaderLine('Content-Type');
echo "Content Type: " . $contentType . "\n";

// Check if response contains specific content type
if (str_contains($contentType, 'application/json')) {
    // Handle JSON response
} elseif (str_contains($contentType, 'text/html')) {
    // Handle HTML response
}

Handling JSON Responses

JSON is the most common content type for API responses. Guzzle provides convenient methods to work with JSON data.

Simple JSON Handling

<?php
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client();

try {
    $response = $client->get('https://jsonplaceholder.typicode.com/posts/1');

    // Parse JSON response
    $data = json_decode($response->getBody(), true);

    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new \Exception('Invalid JSON response: ' . json_last_error_msg());
    }

    echo "Post Title: " . $data['title'] . "\n";
    echo "Post Body: " . $data['body'] . "\n";

} catch (RequestException $e) {
    echo "Request failed: " . $e->getMessage() . "\n";
}

Advanced JSON Processing with Error Handling

<?php
function handleJsonResponse($response) {
    $contentType = $response->getHeaderLine('Content-Type');

    if (!str_contains($contentType, 'application/json')) {
        throw new \Exception('Expected JSON response, got: ' . $contentType);
    }

    $body = $response->getBody()->getContents();

    if (empty($body)) {
        throw new \Exception('Empty response body');
    }

    $data = json_decode($body, true);

    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new \Exception('JSON decode error: ' . json_last_error_msg());
    }

    return $data;
}

// Usage
$client = new Client();
$response = $client->get('https://api.github.com/users/octocat');
$userData = handleJsonResponse($response);

Processing XML Responses

XML responses require different parsing strategies depending on the complexity of the data structure.

Basic XML Parsing

<?php
use GuzzleHttp\Client;

$client = new Client();
$response = $client->get('https://httpbin.org/xml');

$contentType = $response->getHeaderLine('Content-Type');

if (str_contains($contentType, 'application/xml') || str_contains($contentType, 'text/xml')) {
    $xmlString = $response->getBody()->getContents();

    // Using SimpleXML
    $xml = simplexml_load_string($xmlString);

    if ($xml === false) {
        throw new \Exception('Failed to parse XML response');
    }

    // Convert to array for easier manipulation
    $array = json_decode(json_encode($xml), true);
    print_r($array);
}

Advanced XML Processing with DOMDocument

<?php
function handleXmlResponse($response) {
    $contentType = $response->getHeaderLine('Content-Type');

    if (!str_contains($contentType, 'xml')) {
        throw new \Exception('Expected XML response, got: ' . $contentType);
    }

    $xmlString = $response->getBody()->getContents();

    // Use DOMDocument for more robust parsing
    $dom = new \DOMDocument();
    $dom->loadXML($xmlString, LIBXML_NOCDATA);

    // Enable user error handling
    libxml_use_internal_errors(true);

    if (!$dom) {
        $errors = libxml_get_errors();
        throw new \Exception('XML parsing failed: ' . implode(', ', $errors));
    }

    return $dom;
}

Working with HTML Content

HTML responses are common when scraping web pages. You'll often need to extract specific data from HTML markup.

HTML Parsing with DOMDocument

<?php
use GuzzleHttp\Client;

function handleHtmlResponse($response) {
    $contentType = $response->getHeaderLine('Content-Type');

    if (!str_contains($contentType, 'text/html')) {
        throw new \Exception('Expected HTML response, got: ' . $contentType);
    }

    $html = $response->getBody()->getContents();

    $dom = new \DOMDocument();

    // Suppress warnings for malformed HTML
    libxml_use_internal_errors(true);
    $dom->loadHTML($html);
    libxml_clear_errors();

    return $dom;
}

// Usage example
$client = new Client();
$response = $client->get('https://example.com');
$dom = handleHtmlResponse($response);

// Extract specific elements
$xpath = new \DOMXPath($dom);
$titles = $xpath->query('//h1');

foreach ($titles as $title) {
    echo "Title: " . $title->textContent . "\n";
}

Handling Binary Content

Binary content such as images, PDFs, or other files requires special handling to preserve data integrity.

Binary File Download

<?php
use GuzzleHttp\Client;

function handleBinaryResponse($response, $outputPath) {
    $contentType = $response->getHeaderLine('Content-Type');

    // Check for binary content types
    $binaryTypes = ['image/', 'application/pdf', 'application/octet-stream'];
    $isBinary = false;

    foreach ($binaryTypes as $type) {
        if (str_contains($contentType, $type)) {
            $isBinary = true;
            break;
        }
    }

    if (!$isBinary) {
        throw new \Exception('Expected binary content, got: ' . $contentType);
    }

    $body = $response->getBody();

    // Save to file
    $file = fopen($outputPath, 'wb');

    if (!$file) {
        throw new \Exception('Cannot create output file: ' . $outputPath);
    }

    while (!$body->eof()) {
        fwrite($file, $body->read(1024));
    }

    fclose($file);

    return filesize($outputPath);
}

// Download an image
$client = new Client();
$response = $client->get('https://httpbin.org/image/png');
$size = handleBinaryResponse($response, '/tmp/downloaded_image.png');
echo "Downloaded {$size} bytes\n";

Creating a Universal Content Handler

For complex applications, you might want to create a universal handler that can process any content type automatically.

<?php
use GuzzleHttp\Client;

class ResponseHandler {

    public static function handle($response) {
        $contentType = $response->getHeaderLine('Content-Type');

        // Remove charset and other parameters
        $mainType = explode(';', $contentType)[0];

        switch (true) {
            case str_contains($mainType, 'application/json'):
                return self::handleJson($response);

            case str_contains($mainType, 'text/xml'):
            case str_contains($mainType, 'application/xml'):
                return self::handleXml($response);

            case str_contains($mainType, 'text/html'):
                return self::handleHtml($response);

            case str_contains($mainType, 'text/plain'):
                return self::handleText($response);

            case str_contains($mainType, 'image/'):
            case str_contains($mainType, 'application/pdf'):
            case str_contains($mainType, 'application/octet-stream'):
                return self::handleBinary($response);

            default:
                throw new \Exception('Unsupported content type: ' . $contentType);
        }
    }

    private static function handleJson($response) {
        $data = json_decode($response->getBody(), true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new \Exception('JSON decode error: ' . json_last_error_msg());
        }
        return ['type' => 'json', 'data' => $data];
    }

    private static function handleXml($response) {
        $xml = simplexml_load_string($response->getBody());
        if ($xml === false) {
            throw new \Exception('XML parsing failed');
        }
        return ['type' => 'xml', 'data' => $xml];
    }

    private static function handleHtml($response) {
        $dom = new \DOMDocument();
        libxml_use_internal_errors(true);
        $dom->loadHTML($response->getBody());
        libxml_clear_errors();
        return ['type' => 'html', 'data' => $dom];
    }

    private static function handleText($response) {
        return ['type' => 'text', 'data' => $response->getBody()->getContents()];
    }

    private static function handleBinary($response) {
        return ['type' => 'binary', 'data' => $response->getBody()];
    }
}

// Usage
$client = new Client();
$response = $client->get('https://api.example.com/data');
$result = ResponseHandler::handle($response);

switch ($result['type']) {
    case 'json':
        echo "JSON data received with " . count($result['data']) . " elements\n";
        break;
    case 'html':
        echo "HTML document with " . $result['data']->getElementsByTagName('*')->length . " elements\n";
        break;
    // Handle other types...
}

Content Type Validation and Error Handling

Implementing robust content type validation prevents unexpected errors in your application.

Expected Content Type Validation

<?php
function validateContentType($response, $expectedTypes) {
    $contentType = $response->getHeaderLine('Content-Type');
    $mainType = explode(';', $contentType)[0];

    $expectedTypes = is_array($expectedTypes) ? $expectedTypes : [$expectedTypes];

    foreach ($expectedTypes as $expected) {
        if (str_contains($mainType, $expected)) {
            return true;
        }
    }

    throw new \Exception(
        "Unexpected content type. Expected: " . implode(', ', $expectedTypes) . 
        ", Got: " . $contentType
    );
}

// Usage
$response = $client->get('https://api.example.com/data');
validateContentType($response, ['application/json', 'text/json']);
$data = json_decode($response->getBody(), true);

Best Practices for Content Type Handling

1. Always Check Content-Type Headers

Never assume the content type. Always verify the Content-Type header before processing responses.

2. Handle Character Encoding

<?php
function getCharsetFromContentType($contentType) {
    if (preg_match('/charset=([^;]+)/i', $contentType, $matches)) {
        return trim($matches[1], '"\'');
    }
    return 'UTF-8'; // Default fallback
}

$contentType = $response->getHeaderLine('Content-Type');
$charset = getCharsetFromContentType($contentType);
$content = mb_convert_encoding($response->getBody(), 'UTF-8', $charset);

3. Implement Graceful Error Handling

<?php
try {
    $response = $client->get($url);
    $result = ResponseHandler::handle($response);
} catch (\Exception $e) {
    error_log("Content processing failed: " . $e->getMessage());
    // Implement fallback logic or user notification
}

Integration with Modern PHP Frameworks

When working with frameworks like Laravel or Symfony, you can extend these concepts into service classes or middleware for consistent content type handling across your application.

Similar to how you might handle different response formats in browser automation tools, Guzzle's content type handling provides the foundation for robust data processing in server-side applications.

Conclusion

Handling different response content types in Guzzle requires understanding HTTP headers, implementing appropriate parsing strategies, and building robust error handling. By following the patterns and examples outlined in this guide, you can create applications that gracefully handle JSON, XML, HTML, and binary content from various APIs and web services.

The key is to always validate content types, implement proper error handling, and choose the right parsing strategy for each content type. This approach ensures your web scraping and API integration projects remain reliable and maintainable as they scale.