PHPackages                             citomni/provider-skeleton - 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. [Framework](/categories/framework)
4. /
5. citomni/provider-skeleton

ActiveProject[Framework](/categories/framework)

citomni/provider-skeleton
=========================

Template provider for CitOmni apps: boot constants (MAP/CFG), example route/controller, service, command, and model. Ultra-lean, deterministic, PHP 8.2+.

v0.0.3(1mo ago)03MITPHPPHP ^8.2

Since Oct 9Pushed 1mo agoCompare

[ Source](https://github.com/citomni/provider-skeleton)[ Packagist](https://packagist.org/packages/citomni/provider-skeleton)[ Docs](https://github.com/citomni/provider-skeleton)[ GitHub Sponsors](https://github.com/LarsGMortensen)[ Fund](https://ko-fi.com/)[ RSS](/packages/citomni-provider-skeleton/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (5)Used By (0)

CitOmni Provider Skeleton
=========================

[](#citomni-provider-skeleton)

Minimal, deterministic **provider template** for CitOmni (PHP 8.2+). Contributes **config**, **service maps**, and optional **routes** via provider registry constants - with optional **controllers**, **commands**, **operations**, **repositories**, **services**, **utils**, and **exceptions**. No magic. No surprises.

♻️ **Green by design** - fewer CPU cycles, lower memory, faster deploys. **More requests per watt.**

> **Scope:** Provider/package skeleton (mode-neutral). Use with `citomni/http` if you expose HTTP routes; use `citomni/cli` if you wire commands into a runner. For application skeletons, see `citomni/http-skeleton`, `citomni/cli-skeleton`, or `citomni/app-skeleton`.

**Further reading**

- Runtime / Execution Mode Layer — why CitOmni has exactly two modes and how deterministic merging works:

- Provider Packages: Design, Semantics, and Best Practices — MAP\_*/CFG\_*, routes, precedence, testing:

---

Requirements
------------

[](#requirements)

- PHP **8.2+**
- Composer
- `citomni/kernel` (required)
- Optional: `citomni/http` (if you use routes/controllers), `citomni/cli` (if you expose commands)

---

Install (scaffold a new provider repo)
--------------------------------------

[](#install-scaffold-a-new-provider-repo)

This repository is a **template** (Composer project). Create a new provider from it:

```
composer create-project citomni/provider-skeleton my-provider
cd my-provider
```

From here you'll **rename** things (package name, namespace, classes) and turn it into your own provider **library**.

---

What's included (in this skeleton)
----------------------------------

[](#whats-included-in-this-skeleton)

```
provider-skeleton/
  ├─ src/
  │  ├─ Boot/
  │  │  └─ Registry.php         # MAP_HTTP / MAP_CLI / CFG_HTTP / CFG_CLI / ROUTES_HTTP / ROUTES_CLI
  │  ├─ Controller/
  │  │  └─ DemoController.php   # Demonstrates JSON, TemplateEngine, and raw HTML actions
  │  ├─ Command/
  │  │  └─ DemoCommand.php      # Extends Kernel BaseCommand
  │  ├─ Operation/
  │  │  └─ DemoOperation.php    # Extends Kernel BaseOperation
  │  ├─ Repository/
  │  │  └─ DemoRepository.php   # Extends Kernel BaseRepository
  │  ├─ Service/
  │  │  └─ DemoService.php      # Extends Kernel BaseService
  │  ├─ Util/
  │  │  └─ DemoUtil.php         # Pure helper, no App dependency
  │  └─ Exception/
  │     └─ DemoException.php    # Package-level example exception
  ├─ tests/
  │  └─ SkeletonSmokeTest.php   # Tiny smoke-test stub (optional)
  ├─ stubs/
  │  └─ provider.composer.json.stub   # READY-TO-PUBLISH composer.json (library)
  ├─ composer.json              # TYPE: project (template for create-project)
  ├─ README.md
  ├─ LICENSE
  └─ .gitignore

```

**PSR-4:** `"CitOmni\\ProviderSkeleton\\": "src/"`**SPDX header:** All PHP files should carry the standard CitOmni header.

---

Deterministic configuration (last wins)
---------------------------------------

[](#deterministic-configuration-last-wins)

Per execution mode (HTTP|CLI), config merges in this order:

1. **Vendor baseline** (by mode)
2. **Providers** (classes listed in your app's `/config/providers.php`; order matters)
3. **App base** (`/config/citomni_{http|cli}_cfg.php`)
4. **Env overlay** (`/config/citomni_{http|cli}_cfg.{dev|stage|prod}.php`)

Merged config is exposed as a **deep, read-only** wrapper; large lists (e.g., `routes`) remain raw arrays for performance:

```
$baseUrl = $this->app->cfg->http->base_url;
$routes  = $this->app->cfg->routes; // raw array by design
```

Services use the same precedence (app overrides provider overrides vendor).

See also:

---

Quick start checklist (after scaffold)
--------------------------------------

[](#quick-start-checklist-after-scaffold)

1. **Switch to your identity**

    - Open `/stubs/provider.composer.json.stub`.
    - Replace placeholders:

        - `your-vendor/your-provider`
        - `YourVendor\\YourProvider\\`
        - URLs and author fields
    - Save it **as** `/composer.json` (overwriting the skeleton's), and ensure `"type": "library"`.
2. **Rename the namespace in code**

    - Update PSR-4 in `/composer.json` to `"YourVendor\\YourProvider\\": "src/"`
    - Search/replace namespaces in `src/` (and `tests/` if used):

    **GNU sed (bash):**

    ```
    find src tests -type f -name '*.php' -print0 \
      | xargs -0 sed -i 's/CitOmni\\ProviderSkeleton\\/YourVendor\\YourProvider\\/g'
    ```

    **PowerShell:**

    ```
    gci -rec src,tests -filter *.php | % {
      (Get-Content $_.FullName) -replace 'CitOmni\\ProviderSkeleton\\','YourVendor\\YourProvider\\' |
        Set-Content $_.FullName
    }
    ```
3. **Rename the boot provider class**

    - Keep the file path: `src/Boot/Registry.php`
    - Change the class namespace to `YourVendor\YourProvider\Boot\Registry`
4. **Decide what to keep**

    - The demo examples (`DemoController`, `DemoCommand`, `DemoOperation`, `DemoRepository`, `DemoService`, `DemoUtil`, `DemoException`) are there to demonstrate the current CitOmni package structure and layer boundaries. Keep or prune freely.
5. **Validate & autoload**

    ```
    composer validate
    composer dump-autoload -o
    ```
6. **Publish**

    - Push to your Git hosting (e.g., GitHub)
    - Submit to Packagist (or enable auto-submit via webhook)

---

Provider contract (registry constants)
--------------------------------------

[](#provider-contract-registry-constants)

Your provider contributes services, config, and optional routes through `src/Boot/Registry.php`. Only present constants are read.

```