PHPackages                             pikulsky/whatsapp-streams - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. pikulsky/whatsapp-streams

ActiveLibrary[HTTP & Networking](/categories/http)

pikulsky/whatsapp-streams
=========================

Encrypting and decrypting decorator streams for WhatsApp.

2.0.1(8mo ago)11[5 issues](https://github.com/pikulsky/whatsapp-streams/issues)Apache-2.0PHPPHP ^8.2

Since Sep 3Pushed 8mo agoCompare

[ Source](https://github.com/pikulsky/whatsapp-streams)[ Packagist](https://packagist.org/packages/pikulsky/whatsapp-streams)[ RSS](/packages/pikulsky-whatsapp-streams/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (6)Versions (6)Used By (0)

PSR-7 Encrypting/Decrypting Decorator Streams for WhatsApp
==========================================================

[](#psr-7-encryptingdecrypting-decorator-streams-for-whatsapp)

This package provides PSR-7 compatible stream decorators that allow incremental encryption and decryption of streams of arbitrary size.
It also supports creating sidecar streams.

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require pikulsky/whatsapp-streams
```

Usage
-----

[](#usage)

### Encrypting a stream

[](#encrypting-a-stream)

Wrap any `StreamInterface` with `WhatsAppEncryptingStream` to encrypt data as it's being read:

```
use GuzzleHttp\Psr7\Utils;

$key = 'some-secret-key-here-32-bytes-long';
$plainStream = Utils::streamFor(fopen('input.file', 'r'));

$cipher = new WhatsAppAudioCipher($key);
$encryptingStream = new WhatsAppEncryptingStream($plainStream, $cipher);

$outputStream = Utils::streamFor(fopen('encrypted.file', 'w'));
Utils::copyToStream($encryptingStream, $outputStream);
```

No encryption is performed until you read from the encrypting stream.

---

### Decrypting a stream

[](#decrypting-a-stream)

To decrypt, wrap the encrypted stream with `WhatsAppDecryptingStream`:

```
use GuzzleHttp\Psr7\Utils;

$key = 'some-secret-key-here-32-bytes-long';
$encryptedStream = Utils::streamFor(fopen('encrypted.file', 'r'));

$cipher = new WhatsAppAudioCipher($key);
$decryptingStream = new WhatsAppDecryptingStream($encryptedStream, $cipher);

$outputStream = Utils::streamFor(fopen('decrypted.file', 'w'));
Utils::copyToStream($decryptingStream, $outputStream);
```

---

### Sidecar

[](#sidecar)

A sidecar stream is used to generate additional authentication data alongside encrypted media. To produce a sidecar, wrap the encrypting stream with `WhatsAppSidecarStream` and pass a writable stream for the sidecar output:

```
use GuzzleHttp\Psr7\Utils;

$key = 'some-secret-key-here-32-bytes-long';
$plainStream = Utils::streamFor(fopen('input.file', 'r'));

$cipher = new WhatsAppVideoCipher($key);
$encryptingStream = new WhatsAppEncryptingStream($plainStream, $cipher);

$sidecarStream = Utils::streamFor('');
$sidecarDecorator = new WhatsAppSidecarStream($encryptingStream, $cipher, $sidecarStream);

$outputStream = Utils::streamFor(fopen('encrypted.file', 'w'));
Utils::copyToStream($sidecarDecorator, $outputStream);

$sidecarContent = (string) $sidecarStream;
```

---

Cipher & Key Types
----------------------

[](#cipher--key-types)

A cipher is required for encryption and decryption. The library provides specialized key types and ciphers for different media types.

### Available Key Types

[](#available-key-types)

The library supports three media-specific key types:

- **`AudioKey`** - for audio
- **`ImageKey`** - for image
- **`VideoKey`** - for video

### Available Ciphers

[](#available-ciphers)

Corresponding to the key types, the library provides specialized cipher implementations:

- **`WhatsAppAudioCipher`** - handles encryption/decryption of audio
- **`WhatsAppImageCipher`** - handles encryption/decryption of image
- **`WhatsAppVideoCipher`** - handles encryption/decryption of vidoe

### Usage Examples

[](#usage-examples)

#### Recommended (media-specific cipher):

[](#recommended-media-specific-cipher)

```
$key = 'some-secret-key-here-32-bytes-long';

// For audio
$audioCipher = new WhatsAppAudioCipher($key);
$encrypted = new WhatsAppEncryptingStream($original, $audioCipher);

// For image
$imageCipher = new WhatsAppImageCipher($key);
$encrypted = new WhatsAppEncryptingStream($original, $imageCipher);

// For video
$videoCipher = new WhatsAppVideoCipher($key);
$encrypted = new WhatsAppEncryptingStream($original, $videoCipher);
```

#### Alternative (explicit key + generic cipher):

[](#alternative-explicit-key--generic-cipher)

```
$key = 'some-secret-key-here-32-bytes-long';

// Using specific key types with generic cipher
$audioKey = new AudioKey($key);
$audioCipher = new WhatsAppCipher($audioKey);
$encrypted = new WhatsAppEncryptingStream($original, $audioCipher);

$imageKey = new ImageKey($key);
$imageCipher = new WhatsAppCipher($imageKey);
$encrypted = new WhatsAppEncryptingStream($original, $imageCipher);

$videoKey = new VideoKey($key);
$videoCipher = new WhatsAppCipher($videoKey);
$encrypted = new WhatsAppEncryptingStream($original, $videoCipher);
```

### Dependecies

[](#dependecies)

- PHP 8.2
- [psr/http-message](https://github.com/php-fig/http-message) - PSR-7 stream interface
- [guzzlehttp/psr7](https://github.com/guzzle/psr7) - PSR-7 stream utilities
- [jsq/psr7-stream-encryption](https://github.com/jeskew/php-encrypted-streams) - stream decorators for encryption, decryption and hashing

Note: the library [jsq/psr7-stream-encryption](https://github.com/jeskew/php-encrypted-streams) is forked to [pikulsky/php-encrypted-streams](https://github.com/pikulsky/php-encrypted-streams/tree/pre-init-hash-stream) to add support for PHP 8.2 and improve HashingStream to pre-initialize the hash context with IV.

### How it works

[](#how-it-works)

WhatsAppEncryptingStream uses decorators from [jsq/psr7-stream-encryption](https://github.com/jeskew/php-encrypted-streams) library:

- [AesEncryptingStream](https://github.com/jeskew/php-encrypted-streams/blob/master/src/AesEncryptingStream.php) for encryption
- [HashingStream](https://github.com/pikulsky/php-encrypted-streams/blob/pre-init-hash-stream/src/HashingStream.php) - for generating the integrity hash of the encrypted data

[![Encrypting Process](doc/encrypting.png)](doc/encrypting.png)

WhatsAppDecryptingStream uses WhatsAppFinalizeStream decorator to split the encrypted data into the original data and the integrity hash, and also it uses decorators from [jsq/psr7-stream-encryption](https://github.com/jeskew/php-encrypted-streams) library:

- [AesDecryptingStream](https://github.com/jeskew/php-encrypted-streams/blob/master/src/AesDecryptingStream.php) for decryption
- [HashingStream](https://github.com/pikulsky/php-encrypted-streams/blob/pre-init-hash-stream/src/HashingStream.php) - for validating the integrity of the decrypted data

[![Decrypting Process](doc/decrypting.png)](doc/decrypting.png)

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance41

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

249d ago

Major Versions

0.1.1 → 2.0.02025-09-05

### Community

Maintainers

![](https://www.gravatar.com/avatar/f96864373da02760ad505f693c0a7fe770dc562ef828c5f1257a8ed11633cbde?d=identicon)[pikulsky](/maintainers/pikulsky)

---

Tags

psrpsr-7streamencryptionwhatsapp

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/pikulsky-whatsapp-streams/health.svg)

```
[![Health](https://phpackages.com/badges/pikulsky-whatsapp-streams/health.svg)](https://phpackages.com/packages/pikulsky-whatsapp-streams)
```

###  Alternatives

[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

8.0k1.0B3.2k](/packages/guzzlehttp-psr7)[psr/http-factory

PSR-17: Common interfaces for PSR-7 HTTP message factories

1.9k692.9M1.9k](/packages/psr-http-factory)[laminas/laminas-diactoros

PSR HTTP Message implementations

546105.8M965](/packages/laminas-laminas-diactoros)[jsq/psr7-stream-encryption

For encrypting and decrypting streams of arbitrary size.

36134.2k1](/packages/jsq-psr7-stream-encryption)[psr/http-server-handler

Common interface for HTTP server-side request handler

175101.3M921](/packages/psr-http-server-handler)[psr/http-server-middleware

Common interface for HTTP server-side middleware

18091.2M1.5k](/packages/psr-http-server-middleware)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)