storybook-php

A Storybook framework addon for developing and previewing PHP components as stories.

Quick Start

.storybook/main.ts:

import type { StorybookConfig } from "storybook";

const config: StorybookConfig = {
  stories: ["../src/**/*.stories.ts"],
  framework: {
    name: "storybook-php",
    options: {},
  },
};

export default config;

src/Greeting.php:

<?php
class Greeting {
    public function __construct(private string $name, private string $greeting = 'Hello') {}

    public function render(): string {
        return "<h2>{$this->greeting}, {$this->name}!</h2>";
    }
}

src/Greeting.stories.ts:

import type { Meta, StoryObj } from "storybook-php";
import { Greeting } from "./Greeting.php@render";

const meta: Meta<typeof Greeting> = {
  component: Greeting,
  title: "Components/Greeting",
};

export default meta;
type Story = StoryObj<typeof Greeting>;

export const Default: Story = {
  args: { name: "World" },
};

npx storybook-php start

npx storybook-php

Command	Description
npx storybook-php start [opts]	Start Storybook dev server
npx storybook-php build [opts]	Build static Storybook
npx storybook-php test [opts]	Run Storybook tests
npx storybook-php typegen [dirs...]	Generate .d.ts files for PHP sources

start and build accept the same options as the storybook CLI (e.g. -p 6006).

typegen defaults to the src directory when no directories are specified.

Testing

npx --package=storybook-php --package=vitest \
    --package=@storybook/addon-vitest \
    --package=@vitest/browser-playwright \
    storybook-php test

Add @storybook/addon-vitest to .storybook/main.ts:

const config: StorybookConfig = {
  addons: ["@storybook/addon-vitest"],
  // ...
};

A default vitest.config is used automatically. To customize, create your own vitest.config.*.

Import Syntax

PHP components are imported with the ./File.php@method specifier. The @method suffix tells storybook-php which callable to invoke. Constructor parameters and method parameters are merged into the story's args.

Pattern	Import Syntax	Args Source
Class instance method	./File.php@render	Constructor params + method params
Static method	./File.php@danger	Method params only
Standalone function	./file.php@funcName	Function params
Invocable class	./File.php@__invoke	Constructor params + __invoke params
Enum method	./File.php@swatch	_case + method params
Template file	./file.php (default import)	Template variables from args

Methods that use echo instead of returning a string are captured via output buffering automatically.

Configuration

Configure in .storybook/main.ts under framework.options:

Option	Type	Default	Description
bootstrap	string	undefined	Path to a PHP file executed before each render (autoloader, config, etc.)
phpBinary	string	'php'	Path to the PHP binary
timeout	number	5000	Render timeout in milliseconds
defaultMethod	string	undefined	Method name used when @method is omitted from the import specifier
adapter	string	undefined	Path to a PHP adapter file for custom output handling (e.g. Laravel Blade)

The adapter file must return a callable: fn(mixed $result, string $buffered, ?object $instance): string

TypeScript Support

Add to tsconfig.json for type support on .php imports and IDE integration:

{
  "compilerOptions": {
    "types": ["storybook-php/client"],
    "plugins": [{ "name": "storybook-php/ts-plugin" }]
  }
}

To generate .d.ts declarations from PHP source files:

npx storybook-php typegen

License

MIT