README

Part of BarnSuite.

Generates Scenario Runner Port stub classes from a captured Barnspec area of business — one Arrange and Assert per Subject → Fact, one Act per Action, one Authenticate per Role — ready for you to fill in with real application logic. It can also check the generated files for drift and export your vocabulary as a Barncept schema.

It ships as a library plus the port-generator command.

Requirements

PHP 8.5+
rmb32/barnspec, Barncept and Barnscaff
A project with captured Barnspec data (.barnspec/) — see Barnspec CLI

Installation

composer require --dev rmb32/port-generator

Configuration

Create barnspec.json at your project root (next to .barnspec/):

{
    "portStubs": {
        "directory": "tests/Barnspec/Port",
        "namespace": "App\\Tests\\Barnspec\\Port"
    }
}

Usage

vendor/bin/port-generator generate <area-of-business-slug>
vendor/bin/port-generator check <area-of-business-slug>
vendor/bin/port-generator export-vocabulary <area-of-business-slug> > commerce-vocabulary.json

generate writes stubs and never overwrites an existing file, so re-running after capturing new vocabulary is safe. Each area of business gets its own folder and namespace beneath portStubs — e.g. tests/Barnspec/Port/RoomManagement/Fact/Room/IsOnOfferArrange.php — so a Fact named the same in two areas is two Ports.
check reports Missing, Unexpected, Misplaced and TypeMismatch files in the output directory — useful after renaming or deleting a Fact, Action or Role.
Vocabulary that only replaced Scenarios use — every Scenario using it was amended or retired by an elaboration in a released Phase — has nothing left to prove: generate no longer writes its stubs, and check reports any still on disk as Retired, safe to delete. Vocabulary no Scenario uses yet is still generated.
export-vocabulary prints the area's Roles, Subjects, Facts, Actions and Phases as a Barncept template schema (JSON, to stdout).

Generated stubs throw a TODO until you fill them in. Once you have, run your scenarios with Scenario Bridge.

Ports are built with new by default. To give them constructor dependencies — your application's handlers, say — name a Scenario Runner PortFactory that hands them out of your container:

{
    "portStubs": {
        "directory": "tests/Barnspec/Port",
        "namespace": "App\\Tests\\Barnspec\\Port",
        "factory": "App\\Tests\\Barnspec\\ContainerPorts"
    }
}

Related packages

Barnspec CLI — capture the stories and vocabulary.
Scenario Runner — defines the Port interfaces the stubs implement.
Scenario Bridge — runs captured Scenarios against your filled-in Ports.
Barnspec — where the stories and vocabulary are captured.
Barncept — consumes the exported vocabulary schema.

More docs

Internals · History · Known issues

rmb32 / port-generator

Package info

Security

Statistics