PHPackages                             setono/client - 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. [Utility & Helpers](/categories/utility)
4. /
5. setono/client

ActiveLibrary[Utility & Helpers](/categories/utility)

setono/client
=============

PHP abstraction for identifying a browser client

v1.1.2(2w ago)018.7k↑13.5%1MITPHPPHP >=8.1CI passing

Since Mar 19Pushed 2w ago1 watchersCompare

[ Source](https://github.com/Setono/client)[ Packagist](https://packagist.org/packages/setono/client)[ GitHub Sponsors](https://github.com/Setono)[ RSS](/packages/setono-client/feed)WikiDiscussions master Synced today

READMEChangelog (4)Dependencies (21)Versions (5)Used By (1)

PHP abstraction for identifying a browser client
================================================

[](#php-abstraction-for-identifying-a-browser-client)

[![Latest Version](https://camo.githubusercontent.com/970c06f647d0e5b01c861b2f184de2d444b609fad06991f002dedbc947245a72/68747470733a2f2f706f7365722e707567782e6f72672f7365746f6e6f2f636c69656e742f762f737461626c65)](https://packagist.org/packages/setono/client)[![Software License](https://camo.githubusercontent.com/c602e8d7c33a4a11283466c43dbfb5a7d781d9067188677f215372922aa6024c/68747470733a2f2f706f7365722e707567782e6f72672f7365746f6e6f2f636c69656e742f6c6963656e7365)](LICENSE)[![Build Status](https://github.com/setono/client/workflows/build/badge.svg)](https://github.com/setono/client/actions)[![Code Coverage](https://camo.githubusercontent.com/28c47f37b9629aa9c49260553bec40534376b71df8a3f7ec736c70a8e2e6dfa6/68747470733a2f2f636f6465636f762e696f2f67682f7365746f6e6f2f636c69656e742f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/setono/client)[![Mutation testing](https://camo.githubusercontent.com/64f3e60bb9530f8aeb0386880bc9c7f7b45ec82518f0fc19d2801c445f262b63/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742675726c3d687474707325334125324625324662616467652d6170692e737472796b65722d6d757461746f722e696f2532466769746875622e636f6d2532465365746f6e6f253246636c69656e742532466d6173746572)](https://dashboard.stryker-mutator.io/reports/github.com/Setono/client/master)

This library provides a small, framework-agnostic value object for identifying a browser client: a stable id together with arbitrary, optionally expiring metadata. A companion `Cookie` class serializes that id — along with a format version and "first/last seen" timestamps — to and from a cookie value, so the same visitor can be recognized across requests.

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

[](#installation)

```
composer require setono/client
```

When you don't supply an id yourself, the library generates a UUIDv7. To use that, install one of the supported UUID libraries (if both are installed, `symfony/uid` is preferred):

```
# If you want to use symfony/uid
composer require symfony/uid

# If you want to use ramsey/uuid
composer require ramsey/uuid
```

Usage
-----

[](#usage)

### The client

[](#the-client)

```
use Setono\Client\Client;

// A new client with a generated UUIDv7 id and empty metadata
$client = new Client();

// ...or built from an existing id and metadata
$client = new Client('a3f1c0de-...', ['plan' => 'pro']);

$client->id;       // the identifier (string, readonly)
(string) $client;  // the same id — Client is Stringable
$client->metadata; // the Metadata object (readonly)
```

### Metadata

[](#metadata)

`Metadata` is a `string => mixed` bag. It implements `ArrayAccess`, `Countable` and `IteratorAggregate`, so you can use it like an array:

```
$metadata = $client->metadata;

$metadata->set('plan', 'pro');
$metadata->has('plan');     // true
$metadata->get('plan');     // 'pro' — throws InvalidArgumentException if the key is missing or expired
$metadata->remove('plan');

// array access, counting and iteration all work
$metadata['plan'] = 'pro';
isset($metadata['plan']);   // true
unset($metadata['plan']);
count($metadata);

foreach ($metadata as $key => $value) {
    // ...
}
```

#### Expiring entries

[](#expiring-entries)

Pass a TTL (in seconds) as the third argument to `set()`. Expired entries are pruned lazily: they are no longer returned by `get()`/`has()` and are excluded from iteration and `count()`.

```
// "promo" expires one hour from now
$metadata->set('promo', 'BLACKFRIDAY', ttl: 3600);
```

### Persisting and restoring

[](#persisting-and-restoring)

`Metadata::toArray()` returns everything needed to rebuild the object — including the expiry bookkeeping — so you can store it (in a database, cache, session, ...) and reconstruct the client later with the timestamps intact:

```
$id   = $client->id;
$data = $client->metadata->toArray();

// ...later
$client = new Client($id, $data);
```

`Client` and `Metadata` are also `JsonSerializable`:

```
json_encode($client); // {"id":"a3f1c0de-...","metadata":{"plan":"pro"}}
```

### Storing the id in a cookie

[](#storing-the-id-in-a-cookie)

The `Cookie` class converts a client id to and from a cookie value. The value also carries a format version and the timestamps for when the client was first and last seen. The library only produces and parses the string — reading the request cookie and writing it to the response is left to your HTTP layer.

```
use Setono\Client\Cookie;

// firstSeenAt and lastSeenAt default to the current time
$cookie = new Cookie($client->id);

(string) $cookie; // "2.1700000000.1700000000.a3f1c0de-..." (version.firstSeenAt.lastSeenAt.clientId)

// Parse an incoming value. A bare id (no dots) is treated as a legacy v1 cookie and upgraded.
$cookie = Cookie::fromString($_COOKIE['_client'] ?? '');

$cookie->clientId;
$cookie->version;
$cookie->firstSeenAt;
$cookie->lastSeenAt;

// Cookie is immutable; "touch" the last-seen timestamp by deriving a new instance
$cookie = $cookie->withLastSeenAt(time());
```

###  Health Score

50

↑

FairBetter than 95% of packages

Maintenance96

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

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

Total

4

Last Release

18d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2412177?v=4)[Joachim Løvgaard](/maintainers/loevgaard)[@loevgaard](https://github.com/loevgaard)

---

Top Contributors

[![loevgaard](https://avatars.githubusercontent.com/u/2412177?v=4)](https://github.com/loevgaard "loevgaard (33 commits)")

---

Tags

php

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Type Coverage Yes

### Embed Badge

![Health badge](/badges/setono-client/health.svg)

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

PHPackages © 2026

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