PHPackages                             tuupola/branca - 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. [Authentication & Authorization](/categories/authentication)
4. /
5. tuupola/branca

ActiveLibrary[Authentication & Authorization](/categories/authentication)

tuupola/branca
==============

Authenticated and encrypted API tokens using modern crypto.

2.3.0(4y ago)52309.2k↓16.5%6[1 PRs](https://github.com/tuupola/branca-php/pulls)1MITPHPPHP ^7.2|^8.0CI failing

Since Jul 20Pushed 4y ago3 watchersCompare

[ Source](https://github.com/tuupola/branca-php)[ Packagist](https://packagist.org/packages/tuupola/branca)[ Docs](https://github.com/tuupola/branca-php)[ GitHub Sponsors](https://github.com/tuupola)[ RSS](/packages/tuupola-branca/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelogDependencies (6)Versions (18)Used By (1)

Branca Tokens for PHP
=====================

[](#branca-tokens-for-php)

Authenticated and encrypted API tokens using modern crypto.

[![Latest Version](https://camo.githubusercontent.com/1bc1ba0221865b866662b42b22d804842f9390e29fb6ee1ba66c12eb9ac7ff0e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f747575706f6c612f6272616e63612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tuupola/branca)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Build Status](https://camo.githubusercontent.com/c04b3e8c2873ab5c349743dd6307f268a8e2dad63139fee1e7b1ba8a9e560f33/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f747575706f6c612f6272616e63612d7068702f54657374732f322e783f7374796c653d666c61742d737175617265)](https://github.com/tuupola/branca-php/actions)[![Coverage](https://camo.githubusercontent.com/622453643231e6690058705f26b137e58331b3ee216994292141970c0252a749/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f747575706f6c612f6272616e63612d7068702e7376673f7374796c653d666c61742d737175617265)](https://codecov.io/github/tuupola/branca-php)

What?
-----

[](#what)

[Branca](https://github.com/tuupola/branca-spec) is a secure easy to use token format which makes it hard to shoot yourself in the foot. It uses IETF XChaCha20-Poly1305 AEAD symmetric encryption to create encrypted and tamperproof tokens. Payload itself is an arbitrary sequence of bytes. You can use for example a JSON object, plain text string or even binary data serialized by [MessagePack](http://msgpack.org/) or [Protocol Buffers](https://developers.google.com/protocol-buffers/).

It is possible to use [Branca as an alternative to JWT](https://appelsiini.net/2017/branca-alternative-to-jwt/). There is also an [authentication middleware](https://github.com/tuupola/branca-middleware) for frameworks which support PSR-7 doublepass or PSR-15 standards.

Install
-------

[](#install)

Install the library using [Composer](https://getcomposer.org/).

```
$ composer require tuupola/branca
```

This branch requires PHP 7.2 or up. The older 1.x branch supports also PHP 5.6, 7.0 and 7.1.

```
$ composer require "tuupola/branca:^1.0"
```

Usage
-----

[](#usage)

Token payload can be any arbitrary data such as string containing an email address. You also must provide a 32 byte secret key. The key is used for encrypting the payload.

```
use Branca\Branca;

$key = random_bytes(32);
$branca = new Branca($key);

$payload = "tuupola@appelsiini.net";
$token = $branca->encode($payload);
/* hGgg0dPSseaUPZqGloWlDGb2i8hb6iamFBIQaatgYDRhEuaXyByaX0nzmyQk1WYAuSBEMWpB20Z1dENLFItwf1 */

$decoded = $branca->decode($token);
/* tuupola@appelsiini.net */
```

Sometimes you might prefer JSON.

```
use Branca\Branca;

$key = random_bytes(32);
$branca = new Branca($key);

$payload = json_encode(["scope" => ["read", "write", "delete"]]);
$token = $branca->encode($payload);

/*
5R7p5pC1gU5kfVuBUzhl43Ndh4HLT9fxAHrhN1zNRivTuehY8zYYzrVZ8C6d6VcNLfCk3EUgBwwW6kIk0wm32O34OFIYz5LnOIezwcV2Xsfc
*/

$decoded = $branca->decode($token);
$array = json_decode($decoded, true);

/*
Array
(
    [scope] => Array
        (
            [0] => read
            [1] => write
            [2] => delete
        )

)
*/
```

You can keep the token size small by using a space efficient serialization method such as [MessagePack](http://msgpack.org/) or [Protocol Buffers](https://developers.google.com/protocol-buffers/).

```
use Branca\Branca;
use MessagePack\MessagePack;
use MessagePack\Packer;
use MessagePack\BufferUnpacker;

$key = random_bytes(32);
$branca = new Branca($key);

$payload = (new Packer)->pack(["scope" => ["read", "write", "delete"]]);
$token = $branca->encode($payload);

/*
3iJt0CjqTRh3FGuAf0DHEmhULFIbPVInjguWIkmyCm7RMps5BMJZKa1KwZMN0z58IpPeCxdjoTdkurn9pl0YNrxAQfg3deP0
*/

$decoded = $branca->decode($token);
$unpacked = (new BufferUnpacker($decoded))->unpack();
print_r($unpacked);

/*
Array
(
    [scope] => Array
        (
            [0] => read
            [1] => write
            [2] => delete
        )

)
*/
```

Timestamp
---------

[](#timestamp)

Branca token includes a timestamp when it was created. When decoding you can optionally pass a `ttl` parameter. Value is passed in seconds. Below example throws en exception if token is older than 60 minutes.

```
use Branca\Branca;

$key = hex2bin("73757065727365637265746b6579796f7573686f756c646e6f74636f6d6d6974");
$branca = new Branca($key);

$token = "1jJDJOEeG2FutA8g7NAOHK4Mh5RIE8jtbXd63uYbrFDSR06dtQl9o2gZYhBa36nZHXVfiGFz";

print $branca->timestamp($token); /* 123206400 */

try {
    $decoded = $branca->decode($token, 3600);
} catch (RuntimeException $exception) {
    print $exception->getMessage(); /* Token is expired */
}
```

Testing
-------

[](#testing)

You can run tests either manually or automatically on every code change. Automatic tests require [entr](http://entrproject.org/) to work.

```
$ make test
```

```
$ brew install entr
$ make watch
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity47

Moderate usage in the ecosystem

Community14

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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 ~125 days

Recently: every ~297 days

Total

15

Last Release

1472d ago

Major Versions

0.3.4 → 1.0.02019-01-08

1.x-dev → 2.0.02019-01-11

PHP version history (4 changes)0.1.0PHP ^5.6 || ^7.0

0.3.4PHP ^5.6|^7.0

2.0.0PHP ^7.2

2.2.0PHP ^7.2|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/3325405a7d8a43bc40dd0e760a4b7f268fba32a7150cf0327f64f13d1661df0b?d=identicon)[tuupola](/maintainers/tuupola)

---

Top Contributors

[![tuupola](https://avatars.githubusercontent.com/u/21913?v=4)](https://github.com/tuupola "tuupola (104 commits)")

---

Tags

apijwttoken-authenticationxchacha20-poly1305jwtAuthenticationtokenfernet

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tuupola-branca/health.svg)

```
[![Health](https://phpackages.com/badges/tuupola-branca/health.svg)](https://phpackages.com/packages/tuupola-branca)
```

###  Alternatives

[tymon/jwt-auth

JSON Web Token Authentication for Laravel and Lumen

11.5k49.1M350](/packages/tymon-jwt-auth)[namshi/jose

JSON Object Signing and Encryption library for PHP.

1.8k99.6M101](/packages/namshi-jose)[auth0/auth0-php

PHP SDK for Auth0 Authentication and Management APIs.

40820.2M68](/packages/auth0-auth0-php)[kreait/firebase-tokens

A library to work with Firebase tokens

24040.8M14](/packages/kreait-firebase-tokens)[bizley/jwt

JWT integration for Yii 2

67425.3k2](/packages/bizley-jwt)[internacionalweb/cognito-token-verifier

This library verifies that the signature of the JWT is valid, comes from a desired application, and that the token has not been tampered with or expired.

102.1k](/packages/internacionalweb-cognito-token-verifier)

PHPackages © 2026

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