Local development setup

No, but without Pro you won't have built-in Xdebug, the Dumps feature, or database services.

• Xdebug is required for generating unit test coverage reports
• Dumps is a great debugging tool which is referenced in this documentation
• Database services are required if you want to use Herd to develop websites with WordPress or any other database-driven CMS.
  :::

3. Make sure Herd is controlling PHP:

Get-Command php

The output should list the source as C:\Users\<your-username>\.config\herd\bin\php84\php.exe or similar according to the global PHP version you have set in Herd.

HTTPS is the standard in production environments and some tools and applications will not work correctly without it, even locally. Even if everything runs fine on HTTP locally, the difference can cause some headaches when you deploy to production, so enabling HTTPS locally can save time and effort later.

No, you don't have to use PhpStorm, but all IDE-specific information in these docs is written for it.

Install and activate the following plugins and any dependencies they have:

• Test Automation
• PHP Annotations
• PowerShell

In File > Settings > Plugins, ensure the following bundled plugins are enabled:

• PHP
• PHP Architecture
• JavaScript and TypeScript
• Node.js
• Vue.js
• Ini
• JSON
• CSS
• Sass
• Blade
• Pest
• Terminal
  :::

PHP Interpreter and Xdebug

1. In File > Settings > PHP, click the 3 dot button next to the CLI Interpreter dropdown.
2. Add the Path to Herd's PHP .bat file so that it will use the global PHP version set in Herd.
3. Click the refresh button and make sure it has picked up the version, configuration file, and Xdebug correctly. If it does not detect Xdebug, you can manually add the path to it as shown in the below screenshot.

Terminal

1. Go to File > Settings > Tools > Terminal.
2. Tick Use new terminal to use the JetBrains terminal.
3. In the Start directory field, enter the path to your project root (e.g., C:\Users\<your-username>\PhpStormProjects\comet-components).
4. In the Shell path field, select or enter the path to PowerShell.
5. Tick Shell integration.
6. Tick Add default PHP interpreter to PATH (it should already be there but it can't hurt to tick it).
7. Tick Add node_modules/.bin from the project root to PATH.

C:\Users\<your-username>\AppData\Local\Microsoft\WindowsApps\pwsh.exe

No, but you may need to adapt some commands and scripts for your shell of choice.

• CMD? Amateur hour - just use PowerShell, it comes with Windows.
• WSL? Hardcore, I like it. Instructions for almost all steps using WSL are available in the Local setup deep dives section. (But be warned: A lot of them just route commands through PowerShell anyway, as integration of all tooling such as the IDE, PHP, Xdebug, Node, and Playwright is easier if you use the native Windows instances of things installed by Herd.)
  :::

Node

Enable Node.js support in File > Settings > Languages & Frameworks > Node.js:

• In the Node interpreter dropdown, ensure C:\Program Files\nodejs\node.exe is selected.
• Tick Coding assistance for Node.js.

Scopes

Scopes are used to limit the scope of file watchers and other settings to specific directories. Configuration for the core package and the WordPress plugin is included in the .idea directory in the project root, so PhpStorm should pick them up automatically. If not, or you need to create a new scope for your implementation:

1. Go to File > Settings > Appearance & Behaviour > Scopes.
2. Click the Add (+ plus sign) button and select Local.
3. Enter a name for the scope (e.g., Core Package).
4. Select the directories you want to include in the scope (e.g., packages/core) and click Include recursively.
5. In the top right corner, tick Share through VCS to ensure the scope is included in the project's Git repository.

File watchers for asset compilation

PhpStorm will probably prompt you to set up a file watcher when you open a .scss file for the first time, but you can also find or create the configuration in File > Settings > Tools > File Watchers.

To automatically compile individual SCSS files in the core package into CSS files in the same location (for example, ./src/components/global.scss to ./src/components/global.css), follow these steps:

1. Go to File > Settings > Tools > File Watchers.
2. Click the Add (+ plus sign) button and select SCSS.
3. In the File Type dropdown, select SCSS style sheet.
4. Uncheck Track only root files.
5. In the Scope dropdown, select Core package.
6. In the Program field, enter the path to the Sass executable that you installed in step 3:

C:\ProgramData\chocolatey\bin\sass

7. In the Arguments field, enter --color --source-map $FileName$:$FileNameWithoutExtension$.css.
8. In the Output paths field, enter $FileNameWithoutExtension$.css:$FileNameWithoutExtension$.css.map.
9. In the Working directory field, enter $FileDir$.
10. Under Advanced Options, tick Auto-save edited files to trigger the watcher and Trigger the watcher on external changes.
11. For Show console, select On error.
12. Click OK to save the watcher.

Note: The variables surrounded by $ are variables that PhpStorm will replace with the actual file names when it runs the watcher. Do not replace these manually with your actual file names.

Rollup is a JavaScript bundler that is used to bundle the core package's JavaScript into one file, to make it easier for implementations to use. It is installed with the project dependencies.

You can set up PhpStorm to automatically run Rollup when you save a JavaScript file like so:

1. Go to File > Settings > Tools > File Watchers.
2. Click the Add (+ plus sign) button and select Custom.
3. In the File Type dropdown, select JavaScript.
4. For the Scope, select Core Package.
5. In the Program field, enter the path to the Rollup executable:

$ProjectFileDir$\packages\core\node_modules\.bin\rollup

(Note: $ProjectFileDir$ is a real variable that resolves to the project root directory, you don't need to manually replace that with your actual path.)

6. In the Arguments field, enter -c to use the configuration file in the project root.
7. In the Output paths field, enter $ProjectFileDir$\packages\core\dist\dist.js (this is the output file for the bundled JavaScript).
8. In the Working directory field, enter $ProjectFileDir$\packages\core.
9. Under Advanced Options, tick Auto-save edited files to trigger the watcher and Trigger the watcher on external changes.
10. For Show console, select On error.
11. Click OK to save the watcher.

Laravel Pint is a code style fixer for PHP built on top of PHP CS Fixer, which is used to ensure consistent code formatting and standards adherence across the project. It is installed as a project dependency and configuration is defined ./pint.json.

To configure PhpStorm to show Pint warnings and automatic fixes, follow these steps:

1. Go to File > Settings > PHP > Quality Tools > Laravel Pint
2. Toggle the switch to enable Pint
3. Fill in the path to the pint.json file in the root of the project
4. Next to the "Configuration: System PHP" dropdown, click the three dots and fill in the path to your global Pint executable (pint.bat) in the dialog that appears (something like C:\Users\<your-username>\AppData\Roaming\Composer\vendor\bin\pint.bat).
5. Click OK to save the executable path and close that pop-up, and Apply to save the Pint settings without closing the settings window.
6. Go to PHP > Quality Tools and select "Laravel Pint" as the external formatter. This will ensure that the Pint configuration is used for formatting and linting in the IDE, including formatting on save.
7. Go to File > Settings > Editor > Inspections and ensure the "Laravel Pint validation" inspection is enabled.

Blade Formatter is a third-party tool installed as a core package dependency, with configuration defined in the ./packages/core/.bladeformatterrc.json file.

To configure PhpStorm to automatically format Blade templates on save, follow these steps:

1. Go to File > Settings > Tools > File Watchers.
2. Click the Add (+ plus sign) button and select Custom.
3. In the File Type dropdown, select Blade.
4. For the Scope, select Core Package.
5. In the Program field, enter powershell.exe.
6. In the Arguments field, enter:

"$ProjectFileDir$\packages\core\node_modules\.bin\blade-formatter.ps1" --write "$FilePath$"

Note: $ProjectFileDir$ is a variable that PhpStorm will replace with the real path when it runs the watcher. You not replace this manually with your actual path.

7. In the Output paths to refresh field, enter $FileName$.
8. In the Working directory field, enter $FileDir$.
9. Under Advanced Options, tick Auto-save edited files to trigger the watcher and Trigger the watcher on external changes.
10. For Show console, select On error.
11. Click OK to save the watcher.

ESLint is installed as a project dependency and configuration for linting and formatting JavaScript and TypeScript code is defined in ./eslint.config.js.

To configure PhpStorm to run ESLint on save and fix issues automatically where possible, follow these steps:

1. Go to File > Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint.
2. Select Automatic ESLint configuration.
3. Tick Run eslint --fix on save.

HTTPS is the standard in production environments and some tools and applications will not work correctly without it, even locally. For example, Storybook loading the test pages into iframes can have problems over HTTP. And as for why we enable HTTP in Herd for the local development site, because HTTPS is standard for production environments it can save us some headaches later if we develop locally with the same standard.

The project is configured to allow Storybook to request the test pages from the local development site in ./browser/test/wrapper-open.php, which you should have configured php.ini to use as the herd_auto_prepend_file in step 7 above. If you still have CORS problems, you can try the below server configurations, or alternatively browser extensions that disable CORS (for local development).

If using Apache, add this to .htaccess in the project root, updating the server paths and domain as needed:

php_value auto_prepend_file "/home/YOUR_USERNAME/public_html/tests/browser/wrapper-open.php"
php_value auto_append_file "/home/YOUR_USERNAME/public_html/tests/browser/wrapper-close.php"

# Enable CORS for storybook subdomain
<IfModule mod_headers.c>
    SetEnvIf Origin "^https://storybook\.comet-components\.test$" ORIGIN_SUB_DOMAIN=$0
    Header set Access-Control-Allow-Origin "%{ORIGIN_SUB_DOMAIN}e" env=ORIGIN_SUB_DOMAIN
    Header set Access-Control-Allow-Methods "GET, OPTIONS"
    Header set Access-Control-Allow-Headers "Content-Type, Authorization, X-Requested-With"
    Header set Access-Control-Allow-Credentials "true"
</IfModule>

# Handle preflight OPTIONS requests
RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=200,L]