WordPress Develop

https://github.com/wordpress/wordpress-develop
Admin
WordPress is a free and open-source content management system (CMS) that allows users to create...
Tokens:780,142
Snippets:5,624
Trust Score:9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Set up local development environment

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Initial setup commands to install dependencies, build the project, start the environment, and install WordPress. Run these after forking and cloning the repository. The site will be accessible at http://localhost:8889.

```bash
npm install
npm run build:dev
npm run env:start
npm run env:install
```

--------------------------------

### Install Node.js dependencies

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentynineteen/contributing.txt

Run npm install to install all required dependencies for the theme.

```bash
npm install
```

--------------------------------

### Install from a branch

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tools/php-ai-client/README.md

Run the installer script with the --branch flag to install from a specific branch.

```bash
bash tools/php-ai-client/installer.sh --branch=main
```

--------------------------------

### Start development environment

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Starts the development environment again with a single command.

```bash
npm run env:start
```

--------------------------------

### Install specific release version

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tools/php-ai-client/README.md

Run the installer script with the --version flag to install a specific release version of the PHP AI Client.

```bash
bash tools/php-ai-client/installer.sh --version=1.0.0
```

--------------------------------

### Output structure of installed package

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tools/php-ai-client/README.md

Shows the directory layout after installation, including autoload.php, src/, and third-party/ directories.

```text
src/wp-includes/php-ai-client/
├── autoload.php      # Generated autoloader
├── src/              # AI Client source (WordPress\AiClient\*)
└── third-party/      # Scoped dependencies (WordPress\AiClientDependencies\*)
    ├── Http/
    └── Psr/
```

--------------------------------

### Run WP-CLI help command

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Example of running the WP-CLI help command using the environment's WP-CLI wrapper.

```bash
npm run env:cli -- help
```

--------------------------------

### Run Actionlint on workflow files

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Runs Actionlint to statically scan YAML workflow files in `.github/workflows` for quality and security issues. Recommended to install locally before submitting changes.

```bash
actionlint
```

--------------------------------

### Watch for changes with npm run dev

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Starts the file watcher to build or copy files as you make changes to WordPress core files. Stop it by pressing ctrl+c.

```bash
npm run dev
```

--------------------------------

### Copy remote file locally and analyze with getID3()

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-includes/ID3/readme.txt

Downloads a remote file over HTTP or FTP to a temporary local file, then runs getID3()->analyze() with optional original filesize and filename parameters (available since v1.9.9-20150212) to get accurate playtime estimates when only a portion of the file is downloaded. The temporary file is deleted after analysis.

```php
// Copy remote file locally to scan with getID3()
$remotefilename = 'http://www.example.com/filename.mp3';
if ($fp_remote = fopen($remotefilename, 'rb')) {
	$localtempfilename = tempnam('/tmp', 'getID3');
	if ($fp_local = fopen($localtempfilename, 'wb')) {
		while ($buffer = fread($fp_remote, 32768)) {
			fwrite($fp_local, $buffer);
		}
		fclose($fp_local);

		$remote_headers = array_change_key_case(get_headers($remotefilename, 1), CASE_LOWER);
		$remote_filesize = (isset($remote_headers['content-length']) ? (is_array($remote_headers['content-length']) ? $remote_headers['content-length'][count($remote_headers['content-length']) - 1] : $remote_headers['content-length']) : null);

		// Initialize getID3 engine
		$getID3 = new getID3;

		$ThisFileInfo = $getID3->analyze($localtempfilename, $remote_filesize, basename($remotefilename));

		// Delete temporary file
		unlink($localtempfilename);
	}
	fclose($fp_remote);
}
```

--------------------------------

### Run PHPStan via npm in Docker

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Launches PHPStan in the Docker container using the npm script. Requires PHP and Composer dependencies installed.

```bash
npm run typecheck:php
```

--------------------------------

### Hash notation example in a @param docblock

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Shows the WordPress hash notation format used in function docblocks to document array parameters. The @type tags describe optional keys with defaults. This example is used to illustrate how HashNotationVisitor translates the hash into a PHPStan shape like array{post_type?: string, post_author?: int, ...}.

```php
/**
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type string $post_type   Post type. Default 'post'.
 *     @type int    $post_author Post author ID.
 * }
 */
```

--------------------------------

### Pass additional flags to PHPStan via npm

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Shows how to pass PHPStan flags through the npm script using `--`. Includes examples for memory limit, specific file, and verbose debug output.

```bash
# to increase the memory limit from the default 2G to 4G:
npm run typecheck:php -- --memory-limit=4G

# to analyze only a specific file:
npm run typecheck:php -- src/wp-includes/template.php

# To scan with verbose debugging output:
npm run typecheck:php -- -vvv --debug
```

--------------------------------

### getID3() one-line function to parse ID3v1 tag

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-includes/ID3/readme.txt

A one-line PHP function that reads the last 128 bytes of a file and unpacks the ID3v1 tag structure, extracting fields like title, artist, album, year, comment, track, and genre ID. This is a minimal example from the project's history.

```php
function getID3($filename) { return unpack('a3TAG/a30title/a30artist/a30album/a4year/a28comment/c1track/c1genreid', substr(file_get_contents($filename), -128)); }
```

--------------------------------

### Navigate to theme directory

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentynineteen/contributing.txt

Change to the twentynineteen theme directory before running npm commands.

```bash
cd /my-computer/local-wordpress-install/src/wp-content/themes/twentynineteen
```

--------------------------------

### Configure docker-compose.override.yml for Apple Silicon

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Create a `docker-compose.override.yml` file with these contents when using older MySQL/MariaDB versions on Apple Silicon machines. Also disable the 'Use Rosetta for x86/AMD64 emulation on Apple Silicon' setting if applicable.

```yaml
services:

  mysql:
    platform: linux/amd64
```

--------------------------------

### Build CSS files

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentynineteen/contributing.txt

Run npm run build to compile SCSS changes into CSS. May need to run twice to update style-rtl.css.

```bash
npm run build
```

--------------------------------

### Change to theme directory

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentytwentytwo/contributing.txt

Navigate to the twentytwentytwo theme directory in a command line interface before running npm commands.

```bash
cd /my-computer/local-wordpress-install/src/wp-content/themes/twentytwentytwo
```

--------------------------------

### Run E2E tests with npm run test:e2e

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/e2e/README.md

Runs the full E2E test suite using a headless browser. Requires a production-like environment at http://localhost:8889 with username admin and password password by default.

```bash
npm run test:e2e
```

--------------------------------

### Run PHP and end-to-end tests

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Runs the PHP and end-to-end test suites. Use these commands to execute the respective test suites.

```bash
npm run test:php
npm run test:e2e
```

--------------------------------

### Run a single E2E test file

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/e2e/README.md

Runs a single E2E test file by specifying its path. Useful for focusing on a specific test during development.

```bash
npm run test:e2e tests/e2e/specs/hello.test.js
```

--------------------------------

### Run a WP-CLI command

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Runs a WP-CLI command in the local environment. Replace <command> with the WP-CLI command you want to execute. Use this instead of running wp directly.

```bash
npm run env:cli -- <command>
```

--------------------------------

### Create a Genericons icon with .my-icon:before

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentyfourteen/genericons/README.txt

Create an icon by adding a :before pseudo-element with the Genericons font. The content value '\f101' outputs a comment icon; copy it from the helper tool at http://genericons.com/.

```css
.my-icon:before {
	content: '\f101';
	display: inline-block;
	-webkit-font-smoothing: antialiased;
	font: normal 16px/1 'Genericons';
	vertical-align: top;
}
```

--------------------------------

### Run E2E tests with custom environment variables

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/e2e/README.md

Runs the E2E tests with custom environment credentials. Overrides the default base URL, username, and password. Do not run in production as tests delete all content.

```bash
WP_BASE_URL=http://mycustomurl WP_USERNAME=username WP_PASSWORD=password npm run test:e2e
```

--------------------------------

### Run JavaScript QUnit tests

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Runs the JavaScript (QUnit) tests. `qunit:compiled` builds first, then runs the suite. A plain `npm run grunt qunit` requires a completed `npm run build` first; without a build, every test fails with a `jQuery is not defined` error.

```bash
npm run grunt qunit:compiled
```

--------------------------------

### Generate optimized HTML5 named character references class

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpunit/data/html5-entities/README.md

Run this command from the WordPress development root to regenerate the optimized HTML5 named character reference lookup class. The expected output confirms successful generation.

```bash
~$ php tests/phpunit/data/html5-entities/generate-html5-named-character-references.php
OK: Successfully generated optimized lookup class.
```

--------------------------------

### Watch for SCSS changes

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentynineteen/contributing.txt

Run npm run watch to automatically rebuild CSS whenever a .scss file changes.

```bash
npm run watch
```

--------------------------------

### Run PHP tests with filters or groups

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Pass extra parameters into the PHP tests by adding `--` followed by command-line options. Use `--filter` to run specific tests or `--group` to run tests by group name or ticket number.

```bash
npm run test:php -- --filter <test name>
npm run test:php -- --group <group name or ticket number>
```

--------------------------------

### Create a Genericon icon with CSS

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentyfifteen/genericons/README.md

Use this CSS rule to display a Genericon icon before elements with a given class. The content value '\f101' is a specific icon code that can be copied from the helper tool at genericons.com or from example.html in the font directory. Keep the -webkit-font-smoothing and -moz-osx-font-smoothing properties for best rendering in Firefox and WebKit browsers.

```css
.my-icon:before {
	content: '\f101';
	font: normal 16px/1 'Genericons';
	display: inline-block;
	-webkit-font-smoothing: antialiased;
	-moz-osx-font-smoothing: grayscale;
}
```

--------------------------------

### Restart development environment

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Restarts the development environment. Use after making changes to `docker-compose.yml` or `.env` files.

```bash
npm run env:restart
```

--------------------------------

### Run E2E tests in interactive UI mode

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/e2e/README.md

Launches Playwright's UI Mode for interactive debugging. Provides a time travel experience with watch mode, allowing individual tests to be run, viewed, watched, and debugged.

```bash
npm run test:e2e -- --ui
```

--------------------------------

### Reset development environment

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Resets the development environment. This destroys the database and attempts to remove pulled container images.

```bash
npm run env:reset
```

--------------------------------

### Run Zizmor on all workflow files

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Runs Zizmor for all workflow files (note the trailing period). Issues are reported to GitHub Code Scanning and surfaced through a status check, not as a workflow run failure.

```bash
zizmor .
```

--------------------------------

### Run baseline generator via Composer

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Runs the baseline generator via Composer when not using the Docker environment. The `--` is required so Composer passes flags to the script; without it flags are silently discarded and every baseline is regenerated.

```bash
composer phpstan:baselines

composer phpstan:baselines -- --identifier=variable.undefined
composer phpstan:baselines -- --combined
composer phpstan:baselines -- --help
```

--------------------------------

### Generate code coverage report

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Generates a PHP code coverage report. Requires xDebug, which can slow down PHPUnit significantly. Generates three coverage reports in HTML, PHP, and text formats, saved in the `coverage` folder.

```bash
npm run test:coverage
```

--------------------------------

### Stop development environment

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/README.md

Stops the development environment to preserve computer power and resources when not in use.

```bash
npm run env:stop
```

--------------------------------

### Regenerate all baselines with npm run typecheck:php:baselines

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Regenerates all PHPStan baselines. Runs the generator in the Docker container. Baselines should not be edited by hand.

```bash
npm run typecheck:php:baselines
```

--------------------------------

### Pass flags to npm baseline generator

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Shows how to pass flags to the baseline generator via npm. Flags are passed after `--`. The `--combined` option prints every error as one baseline without writing anything; `--help` lists remaining options.

```bash
# a single identifier:
npm run typecheck:php:baselines -- --identifier=variable.undefined

# several, either comma separated or by repeating the option:
npm run typecheck:php:baselines -- --identifier=variable.undefined,isset.variable
npm run typecheck:php:baselines -- --identifier=isset.variable --identifier=empty.variable

# print every error as one baseline, writing nothing:
npm run typecheck:php:baselines -- --combined

# the remaining options:
npm run typecheck:php:baselines -- --help
```

--------------------------------

### Run PHPStan via Composer directly

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Runs PHPStan using Composer when not using Docker. Note the `--` is required for Composer to pass flags to PHPStan; without it, flags are silently discarded.

```bash
composer run phpstan

composer run phpstan -- --memory-limit=4G
composer run phpstan -- src/wp-includes/template.php
composer run phpstan -- -vvv --debug
```

--------------------------------

### Baseline entry for variable.undefined

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Shows the structure of a baseline entry in baselines/variable.undefined.neon. The entry is scoped to a file and includes an exact occurrence count; a new occurrence of the same error does not match the entry and is reported as a new error.

```neon
-
	message: '#^Variable \$wpdb might not be defined\.$#'
	identifier: variable.undefined
	count: 4
	path: ../../../src/wp-trackback.php
```

--------------------------------

### Embed Genericons webfont with @font-face

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentyfourteen/genericons/README.txt

Place the font folder in your stylesheet directory and paste this CSS to embed the Genericons webfont. Note that this only works if you don't use a CDN; if you do, use the syntax embedded in genericons.css.

```css
/* =Genericons, thanks to FontSquirrel.com for conversion!
-------------------------------------------------------------- */
@font-face {
    font-family: 'Genericons';
    src: url('font/genericons-regular-webfont.eot');
    src: url('font/genericons-regular-webfont.eot?#iefix') format('embedded-opentype'),
         url('font/genericons-regular-webfont.woff') format('woff'),
         url('font/genericons-regular-webfont.ttf') format('truetype'),
         url('font/genericons-regular-webfont.svg#genericonsregular') format('svg');
    font-weight: normal;
    font-style: normal;

}
```

--------------------------------

### Edit @font-face in genericons.css to load WOFF/TTF/SVG directly

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/src/wp-content/themes/twentysixteen/genericons/README.md

Replace the default base64-encoded @font-face in genericons.css with this declaration to load the font files directly. This avoids the 25% filesize overhead of base64 encoding but requires that you can serve fonts without cross-origin restrictions or have server config to allow it.

```css
@font-face {
	font-family: 'Genericons';
		src: url('Genericons.woff') format('woff'),
		url('Genericons.ttf') format('truetype'),
		url('Genericons.svg#genericonsregular') format('svg');
	font-weight: normal;
	font-style: normal;
}
```

--------------------------------

### Clear PHPStan cache after editing source files

Source: https://github.com/wordpress/wordpress-develop/blob/trunk/tests/phpstan/README.md

Clears the PHPStan cache directory. Required after editing files in this directory because the per-file reflection cache is keyed by source file contents and does not detect changes from visitors like HashNotationVisitor that alter the syntax tree without changing bytes on disk.

```bash
rm -rf .cache
```
Tokens:
Raw