README

Part of BarnSuite.

A concept graph manager. Describe a set of linked concepts as a plain PHP/JSON schema, then resolve it into a concrete, named tree you can print, scaffold on disk, or project onto anything else.

Requirements

PHP 8.5+
The ds extension, ^2.0

Installation

composer require rmb32/barncept

Set up a project

Each project that uses Barncept needs somewhere to keep its own custom schemas. Add the CLI and run init once from the project root:

composer require rmb32/barncept-cli
vendor/bin/barncept init                        # prompts for a schema folder (default: concepts/custom)
vendor/bin/barncept init --schemas=concepts/my  # non-interactive

This writes a barncept.json at the project root — commit it. Read it back from PHP:

use Rmb32\Barncept\Api\Factory\ProjectConfigLoaderFactory;

$config = new ProjectConfigLoaderFactory()->create()->load($projectRoot);
$config?->schemaDirectory(); // absolute path, or null if `init` hasn't been run

The model

A Schema is made of three kinds of entry:

Definition — a concept that can require other Definitions and Abstractions beneath it (Application, Domain).
Abstraction — a named role that Implementations fulfil (Aggregate, Command); it can also require Definitions and Abstractions.
Implementation — a concrete node satisfying one Abstraction (Basket implements Aggregate), optionally providing Implementations for the Abstractions it requires.

A Schema has a kind: template (Definitions and Abstractions only — portable vocabulary, can't be resolved) or custom (adds Implementations, so it can be resolved). Resolving a Schema from a root Implementation produces an Instance tree.

Five ready-made template Schemas ship in concepts/templates/: Domain Driven Design, Feature Based Architecture, Model View Controller, Library and Package App — copies of the catalogue Barnark bundles and uses.

Usage

use Rmb32\Barncept\Api\Factory\PresenterFactory;
use Rmb32\Barncept\Api\Factory\ResolverFactory;
use Rmb32\Barncept\Api\Factory\SchemaFactory;
use Rmb32\Barncept\Api\ValueObject\Key\ImplementationKey;

$data = [
    'kind' => 'custom',
    'definitions' => [
        ['key' => 'Application', 'name' => 'Application', 'meaning' => 'The application layer', 'definitions' => [], 'abstractions' => []],
        ['key' => 'Domain', 'name' => 'Domain', 'meaning' => 'The domain layer', 'definitions' => [], 'abstractions' => []],
    ],
    'abstractions' => [
        [
            'key' => 'Aggregate',
            'name' => 'Aggregate',
            'meaning' => 'A DDD aggregate',
            'definitions' => ['Application', 'Domain'],
            'abstractions' => [],
        ],
    ],
    'implementations' => [
        [
            'key' => 'Root',
            'name' => 'Root',
            'meaning' => 'The project root',
            'abstraction' => 'Aggregate',
            'implementations' => [],
        ],
    ],
];

$schema = new SchemaFactory()->create($data);
$instance = new ResolverFactory()->create()->resolve($schema, ImplementationKey::new('Root'));

echo new PresenterFactory()->create()->present($instance);

Root
|
+--Application
+--Domain

Turn a Schema back into its array shape (e.g. to save edits):

use Rmb32\Barncept\Api\Factory\SchemaSerializerFactory;

$data = new SchemaSerializerFactory()->create()->serialize($schema);

Handling errors

SchemaFactory::create() throws a subclass of Rmb32\Barncept\Api\Exception\ValidationException for a malformed array and of Rmb32\Barncept\Api\Exception\SchemaException for a dangling reference or a cycle. Resolver::resolve() throws Api\Exception\ResolverException (and Api\Exception\Schema\TemplateSchemaUnresolvableException for a template Schema). Catch the abstract root to handle a whole family, or a leaf for one case; each leaf exposes its detail (the key involved, the cycle path) through getters.

Schema shape reference

[
    'kind' => 'template' | 'custom',
    'definitions' => [
        ['key' => string, 'name' => string, 'meaning' => string, 'definitions' => string[], 'abstractions' => string[], 'metadata' => [string => bool|int|float|string]],  // 'metadata' optional
    ],
    'abstractions' => [
        [same shape as a definition],
    ],
    'implementations' => [
        [
            'key' => string,
            'name' => string,
            'meaning' => string,
            'abstraction' => string,        // the Abstraction this implements
            'implementations' => [          // this Implementation's own Implementations,
                string => string[],         //   keyed by the Abstraction they satisfy
            ],
            'metadata' => [string => bool|int|float|string],  // optional
        ],
    ],
]

Related packages

Barnscaff — turn a resolved graph into real folders and files, or check a folder against it (barnscaff scaffold / barnscaff scan).
Barncept CLI — the barncept init command.
Barncept GUI — browse and edit schemas in the browser.
Barnark — architecture templates built on Barncept and Barnscaff.
Barnspec — port-generator export-vocabulary exports captured story vocabulary as a Barncept template Schema.

More docs

Internals · History · Known issues

rmb32 / barncept

Package info

Security

Statistics