PHPackages                             mvieira/macaroons - 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. mvieira/macaroons

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

mvieira/macaroons
=================

v0.0.1(8y ago)35.3k—0%MITPHPPHP >=7.0

Since Aug 4Pushed 8y ago1 watchersCompare

[ Source](https://github.com/mickaelvieira/macaroons)[ Packagist](https://packagist.org/packages/mvieira/macaroons)[ Docs](https://github.com/mickaelvieira/macaroons)[ RSS](/packages/mvieira-macaroons/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (3)Used By (0)

Macaroons
=========

[](#macaroons)

[![Software License](https://camo.githubusercontent.com/850eae1099d2b05f53383473d7cd51f9bc1ab09b7d0d9e5122f1dd930efdcc6d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d6173686170652f6170697374617475732e737667)](https://github.com/mickaelvieira/macaroons/blob/master/LICENSE.md)[![Latest Stable Version](https://camo.githubusercontent.com/a8c29dcb8ddc3aa53fa8e2e53c45cf2052f54cd1dc445ac8b39db9ca3dc91150/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d7669656972612f6d616361726f6f6e732e737667)](https://packagist.org/packages/mvieira/macaroons)[![Build Status](https://camo.githubusercontent.com/270206f6dae29f1c1bf464f22fc48f1a908d0af2e6eb96a97087f82c9663e70f/68747470733a2f2f7472617669732d63692e6f72672f6d69636b61656c7669656972612f6d616361726f6f6e732e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/mickaelvieira/macaroons)[![Coverage Status](https://camo.githubusercontent.com/6c80aef487f8fcb1335ad82cf4c0ab9870426d07d683eff177f8c6c13184e904/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6d69636b61656c7669656972612f6d616361726f6f6e732f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/mickaelvieira/macaroons?branch=master)

A php implementation of Macaroons: Cookies with Contextual Caveats for Decentralized Authorization

**Specification**

-
-

**Resources**

-
-
-

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

[](#installation)

**Requirements**

- php >= 7.0
- [libsodium-php >= 1.0](https://github.com/jedisct1/libsodium-php)

**About libsodium**

- The `libsodium` library will be distributed with PHP >= 7.2)
- The `libsodium` library is not required in `composer.json` because the versions 1 (`ext-libsodium`) and 2 (`ext-sodium`) have different names. Nevertheless, this package should work with both once installed.

**Installation**

Add the library as a requirement in your `composer.json`

```
{
    "require": {
        "mvieira/macaroons": "dev-master"
    }
}
```

or with command line

```
$ composer require mvieira/macaroons
```

Documentation
-------------

[](#documentation)

Here is a simple example with a third party `macaroon`:

On the `target service` server, produce the `macaroon` authorizing the user to access the service.

```
use Macaroons\Macaroon;

use function Macaroons\Crypto\crypto_gen_nonce;

$macaroon = Macaroon::create('secret random number', crypto_gen_nonce(), 'https://unicorn.co');
$macaroon = $macaroon
    ->withThirdPartyCaveat('third party secret', 'user_auth', 'https://auth.unicorn.co');
```

On the identification provider server, produce the `discharge macaroon` that will verified the `third party caveat`

```
use Macaroons\Macaroon;

// user login happens beforehand...
// once the user manages to log in to the service

// Deserialize the root macaroon
$macaroon  = Macaroon::deserialize('@#!?$');

// prepare the discharge macaroon that will satisfied the third party caveat
$discharge = Macaroon::create('third party secret', 'user_auth', 'https://auth.unicorn.co')
    ->withFirstPartyCaveat('user_id = 12345678'); // add the requested first party caveat

// bind the discharge macaroon to the root macaroon
$discharge = $macaroon->bind($discharge);
```

Back on the target service server

```
use Macaroons\Macaroon;
use Macaroons\Verifier;
use Macaroons\Serialization\V1\Serializer;

// deserialize both macaroons
$macaroon  = Macaroon::deserialize('@#!?$', new Serializer());
$discharge = Macaroon::deserialize('#?@$!', new Serializer());

// prepare the verifier
$verifier = (new Verifier())
    ->satisfyExact('user_id = 12345678')
    ->withDischargeMacaroon($discharge);

try {
    $verified = $macaroon->verify('secret random number', $verifier);
} catch (\DomainException $e) {
    // Catch verification errors
    echo $e->getMessage() . "\n";
}
```

Examples
--------

[](#examples)

Examples are available in the directory `./examples/`

```
$ php ./examples/1-target-service.php
```

```
$ php ./examples/2-identity-provider.php
```

```
$ php ./examples/3-verification.php
```

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

[](#contributing)

Please see [CONTRIBUTING](https://github.com/mickaelvieira/macaroons/tree/master/CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see [LICENSE](https://github.com/mickaelvieira/macaroons/tree/master/LICENSE.md)for more information.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity49

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

Total

2

Last Release

3153d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/54a9031d93c5538389f6f505716a19f552d2b40e2bbfa330ddbca95c6e6fa573?d=identicon)[mickaelvieira](/maintainers/mickaelvieira)

---

Top Contributors

[![mickaelvieira](https://avatars.githubusercontent.com/u/3251585?v=4)](https://github.com/mickaelvieira "mickaelvieira (7 commits)")

---

Tags

Authenticationauthorizationcookiemacarooncaveatsdecentralization

###  Code Quality

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/mvieira-macaroons/health.svg)

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

###  Alternatives

[league/oauth2-server

A lightweight and powerful OAuth 2.0 authorization and resource server library with support for all the core specification grants. This library will allow you to secure your API with OAuth and allow your applications users to approve apps that want to access their data from your API.

6.6k136.0M245](/packages/league-oauth2-server)[league/oauth2-client

OAuth 2.0 Client Library

3.8k118.6M1.1k](/packages/league-oauth2-client)[hybridauth/hybridauth

PHP Social Authentication Library

3.4k8.5M91](/packages/hybridauth-hybridauth)[league/oauth1-client

OAuth 1.0 Client Library

99698.8M106](/packages/league-oauth1-client)[lusitanian/oauth

PHP 7.2 oAuth 1/2 Library

1.1k23.2M118](/packages/lusitanian-oauth)[league/oauth2-google

Google OAuth 2.0 Client Provider for The PHP League OAuth2-Client

41721.2M117](/packages/league-oauth2-google)

PHPackages © 2026

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