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 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). Then it asks what to call the project's template: your own copy of the one picked, which src/ is made from and checked against. That name has no suggestion, and can't be a shipped template's name. Each can be given as an option instead:

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

The folder must be new or empty: Barn is for new projects. You get:

shop/
  .barn/
    barn.json                # marks the barn and names it
    barnspec.json            # where generated Port stubs go: tests/Barnspec/Port
    barnspec/                # story-map data and its Barncept storage selection
      area-of-business-storage.json
    barnark/
      tracked-folders.json   # src/ is bound to the template Shop
      templates/Shop/        # that template, kept as revisions, beside any others of your own
  composer.json              # PSR-4 for src/ and tests/, require-dev rmb32/barn
  src/                       # made from the project's 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.

The project's template is a copy, tied to nothing: a later change to the shipped one never reaches it, and nothing in .barn/ names the template it came from. Adding a member to src/ (a new Context, say) adds it to the project's template as a new revision, and so does deleting one. The Architecture tab's History shows its revisions, read-only.

A barn has one bound template. The Architecture tab also lists the unbound ones: the shipped ones, read-only, and your own, which you make by copying any template.

New barns select Barncept for Area of Business data and store its documents under .barn/concepts/.

A barn built with Barn 2

Barn 3's Barnark reads no record that Barnark 5 wrote, and converts none. While .barn/barnark-workspace.json is there, or a tracked-folders.json that binds several folders, as Barnark 6 did, the Architecture tab and barn status say so in place of the bound folder; move that file out of the barn and Barnark starts afresh. To keep src/ bound, run vendor/bin/barnark template:clone "<template>" <name> ./src in a new, empty scratch barn, copy that barn's .barn/barnark/ into yours, then move the old file out.

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 the bound 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 the bound folder, its template and your other templates.

barn gui takes --host, --port, --no-open and --dry-run. Started outside a barn, it offers to build one, 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