GetStream PHP SDK

A PHP SDK for the GetStream API.

Installation

Install via Composer:

composer require getstream/getstream-php

Migrating from stream-chat-php?

If you are currently using stream-chat-php, we have a detailed migration guide with side-by-side code examples for common Chat use cases. See the Migration Guide.

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Required environment variables:

STREAM_API_KEY=your_api_key_here
STREAM_API_SECRET=your_api_secret_here
STREAM_BASE_URL=https://chat.stream-io-api.com

Code Generation

Generate API methods from OpenAPI spec:

./generate.sh

Testing

Run tests:

# Run all tests
make test

# Run unit tests only
make test-unit

# Run integration tests (requires API credentials)
make test-integration

Usage

Basic Setup

<?php
require_once 'vendor/autoload.php';

use GetStream\ClientBuilder;

$client = ClientBuilder::fromEnv()->build();
$feed = $client->feed('user', 'john-doe');

Working with Activities

use GetStream\GeneratedModels\AddActivityRequest;

// Create an activity
$activity = new AddActivityRequest(
    actor: 'user:john',
    verb: 'post',
    object: 'message:123',
    text: 'Hello World!'
);

$response = $client->addActivity($activity);

// Access response data directly
$createdActivity = $response->activity;
echo "Activity ID: " . $createdActivity->id;

// Or access HTTP metadata
echo "Status: " . $response->getStatusCode();
echo "Duration: " . $response->duration;

Models

Note: When constructing models directly, always use named arguments (e.g. new Message(text: 'hello')). Positional argument usage is not supported and may break across SDK updates as parameter order is not guaranteed.

Automatic JSON Parsing

Generated models automatically handle JSON parsing and serialization:

// Models parse JSON based on constructor types
$response = $client->addActivity($request);
$activity = $response->activity;  // Fully typed object

Custom JSON Key Mapping

Override field names using the JsonKey attribute:

use GetStream\GeneratedModels\JsonKey;

class CustomModel extends BaseModel {
    public function __construct(
        #[JsonKey('fids')]
        public ?array $feedIds = null,    // Maps to "fids" instead of "feed_ids"
    ) {}
}

Response Access

$response = $client->addActivity($request);

// Direct access
$activity = $response->activity;

// HTTP metadata
$statusCode = $response->getStatusCode();
$duration = $response->duration;

Code Generation

Generate models and clients from OpenAPI spec:

./generate.sh

This creates clean, typed models with automatic JSON handling - no boilerplate code needed.

Development

Release Workflow

Releases are automated when a pull request is merged into main or master.

• PR titles must follow Conventional Commit format (for example: feat: ..., fix: ...).
• Ticket prefix is required in the subject: type: [FEEDS-1234] description.
• Keep the commit type first so release automation can parse it.
• Version bump is derived from PR title/body:
  • feat: => minor
  • fix: or bug: => patch
  • feat!: / fix!: / BREAKING CHANGE => major
• Non-release types like chore:, docs:, test: do not create a release.
• The release workflow updates composer.json and src/Constant.php, pushes a tag, creates a GitHub release, and triggers Packagist.

Examples:

• feat: [FEEDS-1350] add feed retention endpoint
• fix: [FEEDS-1402] handle missing reaction id
• feat!: [FEEDS-1410] remove deprecated follow API

Linting and Code Quality

# Run all available linting checks
make lint

# Run PHPStan static analysis only
make phpstan

# Fix code style issues (requires php-cs-fixer)
make cs-fix

# Run comprehensive quality checks (lint + tests)
make quality

Testing

# Run all tests
make test

# Run unit tests only
make test-unit

# Run integration tests
make test-integration