{"id":47662341,"url":"https://github.com/k-kinzal/storybook-php","last_synced_at":"2026-04-27T07:03:03.794Z","repository":{"id":345454518,"uuid":"1184373072","full_name":"k-kinzal/storybook-php","owner":"k-kinzal","description":"Storybook framework addon for rendering PHP components as stories","archived":false,"fork":false,"pushed_at":"2026-04-22T05:32:46.000Z","size":1346,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-22T06:36:45.738Z","etag":null,"topics":["component-driven","php","storybook","storybook-addon","storybook-framework","ui"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/storybook-php","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k-kinzal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-17T14:23:21.000Z","updated_at":"2026-04-22T05:32:14.000Z","dependencies_parsed_at":"2026-04-02T12:16:35.822Z","dependency_job_id":null,"html_url":"https://github.com/k-kinzal/storybook-php","commit_stats":null,"previous_names":["k-kinzal/storybook-php"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/k-kinzal/storybook-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kinzal%2Fstorybook-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kinzal%2Fstorybook-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kinzal%2Fstorybook-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kinzal%2Fstorybook-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k-kinzal","download_url":"https://codeload.github.com/k-kinzal/storybook-php/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kinzal%2Fstorybook-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32326126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component-driven","php","storybook","storybook-addon","storybook-framework","ui"],"created_at":"2026-04-02T11:39:33.469Z","updated_at":"2026-04-27T07:02:58.784Z","avatar_url":"https://github.com/k-kinzal.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# storybook-php\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![npm version](https://img.shields.io/npm/v/storybook-php.svg)](https://www.npmjs.com/package/storybook-php)\n\nA Storybook framework addon for developing and previewing PHP components as stories.\n\n## Supported Versions\n\n- PHP 8.0-8.5\n- Storybook 10.x\n- Vite 5.x-8.x\n- Node.js 20.19+\n\n## Quick Start\n\n`.storybook/main.ts`:\n\n```typescript\nimport type { StorybookConfig } from \"storybook\";\n\nconst config: StorybookConfig = {\n  stories: [\"../src/**/*.stories.ts\"],\n  framework: {\n    name: \"storybook-php\",\n    options: {},\n  },\n};\n\nexport default config;\n```\n\n`src/Greeting.php`:\n\n```php\n\u003c?php\nclass Greeting {\n    public function __construct(private string $name, private string $greeting = 'Hello') {}\n\n    public function render(): string {\n        return \"\u003ch2\u003e{$this-\u003egreeting}, {$this-\u003ename}!\u003c/h2\u003e\";\n    }\n}\n```\n\n`src/Greeting.stories.ts`:\n\n```typescript\nimport type { Meta, StoryObj } from \"storybook-php\";\nimport { Greeting } from \"./Greeting.php@render\";\n\nconst meta: Meta\u003ctypeof Greeting\u003e = {\n  component: Greeting,\n  title: \"Components/Greeting\",\n};\n\nexport default meta;\ntype Story = StoryObj\u003ctypeof Greeting\u003e;\n\nexport const Default: Story = {\n  args: { name: \"World\" },\n};\n```\n\n```bash\nnpx storybook-php start\n```\n\n## npx storybook-php\n\n| Command                                                     | Description                                     |\n| ----------------------------------------------------------- | ----------------------------------------------- |\n| `npx storybook-php start [storybook opts]`                  | Start the Storybook dev server                  |\n| `npx storybook-php build [storybook opts]`                  | Build static Storybook output                   |\n| `npx storybook-php test [vitest opts]`                      | Run Storybook tests through `vitest run`        |\n| `npx storybook-php typegen [dirs...] [--options-file path]` | Generate declaration files for PHP import paths |\n\n`start` and `build` accept the same options as the `storybook` CLI (e.g. `-p 6006`).\n`test` passes arguments through to `vitest run`.\n\n`typegen` defaults to the `src` directory when no directories are specified. It writes declaration files next to the source import path, including exact-import outputs such as `Button.php@render.d.ts`. When `defaultMethod` resolves, the bare `Button.php.d.ts` output mirrors that callable; otherwise a bare import remains template-shaped.\n\nIf your type generation depends on `defaultMethod` or `typeMap`, pass them through `--options-file` because `typegen` does not read `.storybook/main.ts`. The options file can be JSON or a JS module and may also provide `_configDir` for relative path resolution.\n\nFor PHP-first repositories that do not want to add a local `package.json`, see [PHP Project Setup](docs/php-project-setup.md) for the `npx`-based setup.\n\n## Testing\n\n```bash\nnpx --package=storybook-php --package=vitest \\\n    --package=@storybook/addon-vitest \\\n    --package=@vitest/browser-playwright \\\n    storybook-php test\n```\n\nAdd `@storybook/addon-vitest` to `.storybook/main.ts`:\n\n```typescript\nconst config: StorybookConfig = {\n  addons: [\"@storybook/addon-vitest\"],\n  // ...\n};\n```\n\nIf your project does not define `vitest.config.*` and you do not pass `--config`, the bundled Vitest config is used automatically. To customize, create your own `vitest.config.*`.\n\n## Import Syntax\n\nPHP 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.\n\n| Pattern                      | Import Syntax                 | Args Source                            |\n| ---------------------------- | ----------------------------- | -------------------------------------- |\n| Class instance method        | `./File.php@render`           | Constructor params + method params     |\n| Static method                | `./File.php@danger`           | Method params only                     |\n| Standalone function          | `./file.php@funcName`         | Function params                        |\n| Invocable class              | `./File.php@__invoke`         | Constructor params + `__invoke` params |\n| Enum method                  | `./File.php@swatch`           | `_case` + method params                |\n| Template file                | `./file.php` (default import) | Template variables from args           |\n| Mapped non-PHP import source | `./card.blade.php`            | `typeMap.files` decides the public API |\n\nMethods that use `echo` instead of returning a string are captured via output buffering automatically.\n\nNon-PHP sources such as Blade, Twig, or Latte are supported through `framework.options.typeMap.files`. Those mappings can provide public args, redirect execution to a PHP file, select a callable, include extra files for analysis, and attach adapter middleware.\n\n## Configuration\n\nConfigure in `.storybook/main.ts` under `framework.options`:\n\n| Option          | Type     | Default     | Description                                                                |\n| --------------- | -------- | ----------- | -------------------------------------------------------------------------- |\n| `bootstrap`     | `string` | `undefined` | Path to a PHP file executed before each render (autoloader, config, etc.)  |\n| `phpBinary`     | `string` | `'php'`     | Path to the PHP binary                                                     |\n| `timeout`       | `number` | `5000`      | Render timeout in milliseconds                                             |\n| `defaultMethod` | `string` | `undefined` | Method name used when `@method` is omitted from the import specifier       |\n| `adapter`       | `string` | `undefined` | Path to a PHP adapter file for custom output handling (e.g. Laravel Blade) |\n| `typeMap`       | `object` | `undefined` | File mappings, callable overrides, and runtime type bindings               |\n\nThe adapter file must return middleware compatible with `fn(array $context, callable $next): array|string`\n\nRelative option paths are resolved from Storybook's config directory. `defaultMethod` and `typeMap` also affect module resolution, TS plugin output, and `typegen` when you pass them through `--options-file`.\n\n## TypeScript Support\n\nAdd to `tsconfig.json` for type support on `.php` imports and IDE integration:\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"storybook-php/client\"],\n    \"plugins\": [{ \"name\": \"storybook-php/ts-plugin\" }]\n  }\n}\n```\n\nThis gives editor support for `.php` imports without requiring generated files.\n\nTo generate declaration files on disk:\n\n```bash\nnpx storybook-php typegen\n```\n\n`typegen` writes both bare-import and exact-import declarations when they resolve:\n\n- `Button.php.d.ts`\n- `Button.php@render.d.ts`\n\nFor advanced setups, load `defaultMethod` and `typeMap` from a separate file:\n\n```bash\nnpx storybook-php typegen --options-file storybook-php.config.mjs\n```\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [PHP Project Setup](docs/php-project-setup.md)\n- [Rendering Model](docs/rendering-model.md)\n- [Framework Options](docs/framework-options.md)\n- [Type Mapping](docs/type-mapping.md)\n- [Testing and Types](docs/testing-and-types.md)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-kinzal%2Fstorybook-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk-kinzal%2Fstorybook-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-kinzal%2Fstorybook-php/lists"}