PHPackages                             maatify/shared-common - 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. [PSR & Standards](/categories/psr-standards)
4. /
5. maatify/shared-common

ActiveLibrary[PSR & Standards](/categories/psr-standards)

maatify/shared-common
=====================

Fundamental contracts and shared abstractions for Maatify modules, including clock and telemetry interfaces.

v1.0.2(1mo ago)12.7k↓72.3%1MITPHPPHP ^8.2CI passing

Since Mar 11Pushed 1mo agoCompare

[ Source](https://github.com/Maatify/SharedCommon)[ Packagist](https://packagist.org/packages/maatify/shared-common)[ RSS](/packages/maatify-shared-common/feed)WikiDiscussions main Synced 3w ago

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

Maatify SharedCommon
====================

[](#maatify-sharedcommon)

[![Latest Version](https://camo.githubusercontent.com/08c579ede89f243ca99e6a05e5e4fc5bffcfaba0dc64f380fe9a05f5ec4188ff/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6161746966792f7368617265642d636f6d6d6f6e2e7376673f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/maatify/shared-common)[![PHP Version](https://camo.githubusercontent.com/4e01b18ecc395518f045b05b9b0097c1d04a2a4640d784c2e5c89bedae395d20/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d6161746966792f7368617265642d636f6d6d6f6e2e7376673f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/maatify/shared-common)[![License](https://camo.githubusercontent.com/85571d0a916e32cd8f63aaee96229519d520b94497d6fd44eb46a7b27952df79/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d6161746966792f7368617265642d636f6d6d6f6e2e7376673f7374796c653d666f722d7468652d6261646765)](LICENSE)

[![PHPStan](https://camo.githubusercontent.com/f85016b73718ab38275b913dafed1c1ce7f287c3c2ec319445bc29011149f408/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c2532304d61782d344538434145)](https://camo.githubusercontent.com/f85016b73718ab38275b913dafed1c1ce7f287c3c2ec319445bc29011149f408/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c2532304d61782d344538434145)

[![Changelog](https://camo.githubusercontent.com/32f7664d004132f7e0fb111b5e01bd7270705d1e7247db502287d51910c04cb9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4368616e67656c6f672d566965772d626c7565)](CHANGELOG.md)[![Security](https://camo.githubusercontent.com/a150750c8b2c6ca6209aa80bdf220d2f0950b984df64c1b859a46ee9152570f3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53656375726974792d506f6c6963792d696d706f7274616e74)](SECURITY.md)

[![Monthly Downloads](https://camo.githubusercontent.com/4ab684f59e40690f3848f24ec84366d6dbd449a6cc66dad0870ae2670e0e061a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6d6161746966792f7368617265642d636f6d6d6f6e3f6c6162656c3d4d6f6e74686c79253230446f776e6c6f61647326636f6c6f723d303041384538)](https://camo.githubusercontent.com/4ab684f59e40690f3848f24ec84366d6dbd449a6cc66dad0870ae2670e0e061a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6d6161746966792f7368617265642d636f6d6d6f6e3f6c6162656c3d4d6f6e74686c79253230446f776e6c6f61647326636f6c6f723d303041384538)[![Total Downloads](https://camo.githubusercontent.com/c3aeeed19808ef8001c680a41e6428b4bae95afb01b559f6f409f20965de6430/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6161746966792f7368617265642d636f6d6d6f6e3f6c6162656c3d546f74616c253230446f776e6c6f61647326636f6c6f723d324141394530)](https://camo.githubusercontent.com/c3aeeed19808ef8001c680a41e6428b4bae95afb01b559f6f409f20965de6430/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6161746966792f7368617265642d636f6d6d6f6e3f6c6162656c3d546f74616c253230446f776e6c6f61647326636f6c6f723d324141394530)

[![Maatify Ecosystem](https://camo.githubusercontent.com/0bfd6db80f9a39f03dac1923cc79f27a507f2fdf59b3a853dc0af26be1343315/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6161746966792d45636f73797374656d2d626c756576696f6c65743f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/0bfd6db80f9a39f03dac1923cc79f27a507f2fdf59b3a853dc0af26be1343315/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6161746966792d45636f73797374656d2d626c756576696f6c65743f7374796c653d666f722d7468652d6261646765)

[![Install](https://camo.githubusercontent.com/2eac40f99482a9257c5ca42abf54d9973edf8095a034d04637efeb4a92f2d13a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f496e7374616c6c2d636f6d706f736572253230726571756972652d626c75653f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/maatify/shared-common)

Overview
--------

[](#overview)

The `Maatify\SharedCommon` module contains foundational contracts and abstractions that are intended to be shared across all Maatify modules (such as `AdminKernel`, `Verification`, etc.). Its primary goal is to provide unified interfaces for common cross-cutting concerns like time management, security contexts, permission mapping definitions, and telemetry, enabling consistent behavior and testing across the entire system.

Purpose
-------

[](#purpose)

By depending on `SharedCommon` rather than framework-specific implementations or raw PHP functions (like `time()` or `date()`), other modules can remain truly framework-agnostic. This module defines the "how we communicate" contracts for basic system realities.

Module Structure
----------------

[](#module-structure)

```
Modules/SharedCommon/
├── Bootstrap/                 # Dependency Injection bindings
│   └── SharedCommonBindings.php
├── Contracts/                 # Core interfaces for time, telemetry, security, and shared module extensions
│   ├── ClockInterface.php
│   ├── Security/              # Framework-neutral security extension contracts
│   │   ├── PermissionMapProviderInterface.php
│   │   ├── PermissionRequirementDefinition.php
│   │   └── ProvidesPermissionMapsInterface.php
│   ├── SecurityEventContextInterface.php
│   └── TelemetryContextInterface.php
├── Infrastructure/            # Default implementations of contracts
│   └── SystemClock.php
├── Path/                      # Common application path resolution utilities
│   └── AppPaths.php
├── docs/                      # Architectural and integration documentation
└── composer.json              # Standalone package metadata
```

Quick Usage
-----------

[](#quick-usage)

To quickly integrate the default implementations of this module into your dependency injection container:

```
use Maatify\SharedCommon\Bootstrap\SharedCommonBindings;
use DI\ContainerBuilder;
use Maatify\SharedCommon\Contracts\ClockInterface;

$builder = new ContainerBuilder();

// Register the bindings for SharedCommon contracts
SharedCommonBindings::register($builder);

$container = $builder->build();

// Resolve the Clock
/** @var ClockInterface $clock */
$clock = $container->get(ClockInterface::class);

// Get the current time as a DateTimeImmutable object
$now = $clock->now();
echo $now->format('Y-m-d H:i:s');
```

---

Permission Mapping Contracts
----------------------------

[](#permission-mapping-contracts)

`SharedCommon` provides framework-neutral permission mapping contracts under:

```
Maatify\SharedCommon\Contracts\Security
```

These contracts allow independent Maatify modules to expose route-to-permission requirements without depending on `AdminKernel` or any application-specific security implementation.

This keeps modules reusable and decoupled while allowing the application or kernel layer to aggregate permission maps and convert them into its own authorization model.

### Defining Permission Requirements

[](#defining-permission-requirements)

Use `PermissionRequirementDefinition` to describe the permission requirement for a route.

```
use Maatify\SharedCommon\Contracts\Security\PermissionRequirementDefinition;

$single = PermissionRequirementDefinition::single('payment_methods.list');

$anyOf = PermissionRequirementDefinition::anyOf([
    'payment_methods.list',
    'payment_methods.dropdown',
]);

$allOf = PermissionRequirementDefinition::allOf([
    'payment_methods.update',
    'payment_methods.translations.upsert',
]);

$compound = PermissionRequirementDefinition::compound(
    anyOf: ['payment_methods.list', 'payment_methods.dropdown'],
    allOf: ['admin.access'],
);
```

### Providing a Permission Map from a Module

[](#providing-a-permission-map-from-a-module)

A module can expose its route permission map by implementing `PermissionMapProviderInterface`.

```