README

A barn is a PHP project with its story map and its architecture under one roof: your code, plus Barnspec (stories and scenarios, proven by running them) and Barnark (architecture templates, checked against your code), ready to use. One CLI builds and adopts barns; one browser UI shows the barn's business and its architecture side by side.

Requirements

PHP 8.5+ with ext-ds 2
Composer, and git (for a new barn's repository)

Installation

To build barns from anywhere, install it globally:

composer global require rmb32/barn

A barn you build requires it itself (require-dev), so vendor/bin/barn is there inside every barn.

Build a barn

barn build shop

It asks for the barn's name, Composer package, root namespace and architecture template, offering a suggestion for each (Domain Driven Design is the default template), or takes them as options:

barn build shop --name="Shop" --package=acme/shop --namespace="Acme\Shop" --template=Library

The folder must be new or empty. You get:

shop/
  .barn/
    barn.json                # marks the barn and names it
    barnspec.json            # where generated Port stubs go: tests/Barnspec/Port
    barnspec/                # the story map, empty to start with
    barnark-workspace.json   # src/ is tracked under its template
  composer.json              # PSR-4 for src/ and tests/, require-dev rmb32/barn
  src/                       # scaffolded from the template
  tests/
  .gitignore

then git init (nothing is committed) and composer install; --no-install skips the install. Everything in .barn/ is meant to be committed.

Adopt a project

An existing Composer project, whether it already uses Barnspec or Barnark or neither, becomes a barn with:

cd my-project
barn adopt

It moves barnspec.json, .barnspec/, barnark-workspace.json and .barnark/ into .barn/, renames any custom template the workspace names (.barnark/X.json becomes .barn/barnark/X.json) and writes .barn/barn.json. Whatever else a barn needs and the project lacks is set up too:

rmb32/barn in composer.json's require-dev (an existing requirement is left alone), then installed;
.barn/barnspec.json naming where Port stubs go (tests/Barnspec/Port, under the namespace composer.json's autoload-dev maps to tests/), when there is no barnspec.json;
a folder tracked under an architecture template, when there is no Barnark workspace.

There is no default template for an existing project, so adopt asks, listing the bundled ones. The folder is /src when it is a PSR-4 root; otherwise it asks for that too.

barn adopt --template="Package App"                        # track /src under Package App
barn adopt --template=.barn/barnark/Mine.json --folder=/app # a custom template, another folder
barn adopt --no-template --no-install                       # track nothing; run composer yourself

Every change is listed first; if any of them cannot be made, nothing is touched. barn gui run in a project that is not a barn offers the same adoption, with the template chosen on the page.

Work in a barn

barn gui        # http://localhost:8090, opens your browser
barn status     # the same overview, in the terminal

The GUI has three tabs:

Home: each area of business with its Scenarios counted by colour (green, yellow, red, not started), and each tracked folder with its template and whether it conforms to it.
Business: the Barnspec GUI, for the story map, scenarios and work.
Architecture: the Barnark GUI, for tracked folders, templates and switches.

barn gui takes --host, --port, --no-open and --dry-run. Started outside a barn, it offers to build one, or to adopt the project you are in, and then serves it without a restart.

Every tool in the barn finds it from any folder inside it, so these work from src/Context/Ordering as well as from the root:

vendor/bin/barnspec show
vendor/bin/barnark template:check
vendor/bin/port-generator generate ordering
vendor/bin/scenario-bridge run-all ordering

Each tool still works on its own in a project that is not a barn.

Related packages

rmb32/barn-layout: finds a barn and says where each tool's files are inside it
rmb32/barnspec-cli and rmb32/barnark-cli: the tools' own CLIs
rmb32/port-generator and rmb32/scenario-bridge: turn scenarios into runnable tests

More at the Barn website.

Internals · History · Known issues

rmb32 / barn

Package info

Security

Statistics