Support installing plugins from single PHP file URLs #486

Copilot · 2026-01-19T09:59:17Z

wp plugin install now accepts URLs to single PHP files (e.g., GitHub Gists), not just ZIP archives.

Example

wp plugin install --activate https://gist.githubusercontent.com/user/id/raw/hash/plugin.php
# Also supports shorter gist page URLs:
wp plugin install --activate https://gist.github.com/user/id

Implementation

Detection: Added is_php_file_url() helper to identify PHP file URLs (plugins only)
Installation: New install_from_php_file() method handles the download and installation flow
GitHub Gist Support:
- Detects both raw URLs (gist.githubusercontent.com) and page URLs (gist.github.com)
- For page URLs, fetches gist metadata from GitHub API to find PHP files
- Automatically converts gist page URLs to raw file URLs
- Supports first PHP file when gist contains multiple files
Security:
- Validates filenames for path traversal attempts (no .., /, \)
- Requires valid WordPress plugin headers (minimum: Plugin Name)
- Verifies .php extension after sanitization
- Checks file existence before downloading (avoids unnecessary requests)
Integration: Returns filename for proper activation handling, supports --force flag

Files Changed

src/WP_CLI/CommandWithUpgrade.php: Core implementation including gist URL handling
src/Plugin_Command.php: Updated documentation and examples
features/plugin-install.feature: Added test coverage for single PHP files, --force flag, and gist page URLs

Original prompt

This section details on the original issue you should resolve

<issue_title>Links to single plugin PHP file should work with plugin install</issue_title>
<issue_description>When using wp plugin install <URL>, WP-CLI currently assumes that the URL is pointing to a ZIP file of a plugin.

This command should also work with a URL to a single PHP plugin file, so that it can for example directly install plugins from GitHub Gists:

Example of such a command that should just work:
wp plugin install --activate https://gist.githubusercontent.com/westonruter/dec7d190060732e29a09751ab99cc549/raw/d55866c2fc82ab16f8909ce73fc89986ab28d727/pwa-manifest-short-name.php
/cc @westonruter (whose numerous Gist plugins make me want to implement the above)</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Links to single plugin PHP file should work with plugin install #233

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: swissspidy <[email protected]>

…oad message timing Co-authored-by: swissspidy <[email protected]>

…plugin headers Co-authored-by: swissspidy <[email protected]>

…dation Co-authored-by: swissspidy <[email protected]>

swissspidy · 2026-01-19T11:33:02Z

@copilot Make sure wp plugin install --activate https://gist.github.com/westonruter/dec7d190060732e29a09751ab99cc549 works too and add a test for that

codecov · 2026-01-19T11:52:21Z

Codecov Report

❌ Patch coverage is 74.74747% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/WP_CLI/CommandWithUpgrade.php	74.74%	25 Missing ⚠️

📢 Thoughts on this report? Let us know!

Co-authored-by: swissspidy <[email protected]>

Copilot

Pull request overview

This PR enables wp plugin install to accept URLs pointing to single PHP files in addition to ZIP archives, with special support for GitHub Gist URLs.

Changes:

Added detection and installation logic for single PHP file URLs
Implemented GitHub Gist page URL resolution to raw file URLs via the GitHub API
Added comprehensive test coverage for PHP file installations, --force flag behavior, and Gist URL handling

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
src/WP_CLI/CommandWithUpgrade.php	Core implementation with Gist URL detection, raw URL conversion via GitHub API, and PHP file installation with security validations
src/Plugin_Command.php	Updated documentation to reflect support for PHP file URLs
features/plugin-install.feature	Added test scenarios for PHP file installations, `--force` flag, and Gist page URLs

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/WP_CLI/CommandWithUpgrade.php

Co-authored-by: Copilot <[email protected]>

swissspidy · 2026-01-19T17:05:47Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a great new feature to install plugins from single PHP file URLs, including from GitHub Gists. The implementation is well-structured and includes good security practices like filename validation and path traversal checks. The feature to resolve Gist page URLs to raw file URLs is a nice touch for user experience.

I've found a couple of areas for improvement:

The Gist URL detection doesn't support anonymous gists.
The checks for .php file extensions are case-sensitive, which could lead to valid files being missed.

I've provided specific suggestions to address these points. Overall, this is a solid contribution.

gemini-code-assist · 2026-01-19T17:10:11Z

src/WP_CLI/CommandWithUpgrade.php

+		if ( preg_match( '#^https?://gist\.github\.com/[^/]+/([a-f0-9]+)/?$#i', $url, $matches ) ) {
+			return $matches[1];
+		}


The regular expression for detecting a Gist URL doesn't account for anonymous gists, which don't have a username in the URL path (e.g., https://gist.github.com/1234567890abcdef). The current regex requires a username segment, causing it to fail for anonymous gists. To support both user-owned and anonymous gists, you should make the username part of the URL path optional.

if ( preg_match( '#^https?://gist\.github\.com/(?:[^/]+/)?([a-f0-9]+)/?$#i', $url, $matches ) ) { return $matches[1]; }

gemini-code-assist · 2026-01-19T17:10:11Z

src/WP_CLI/CommandWithUpgrade.php

+		if ( pathinfo( $dest_filename, PATHINFO_EXTENSION ) !== 'php' ) {
+			return new WP_Error( 'invalid_filename', 'The sanitized filename does not have a .php extension.' );
+		}


The check for the .php extension on the sanitized filename is case-sensitive because it uses pathinfo(). This means a file with an extension like .PHP would be incorrectly rejected. To make this check more robust, you should convert the extension to lowercase before comparison.

if ( strtolower( pathinfo( $dest_filename, PATHINFO_EXTENSION ) ) !== 'php' ) { return new WP_Error( 'invalid_filename', 'The sanitized filename does not have a .php extension.' ); }

gemini-code-assist · 2026-01-19T17:10:11Z

src/WP_CLI/CommandWithUpgrade.php

+		}
+
+		$url_path = Utils\parse_url( $slug, PHP_URL_PATH );
+		return is_string( $url_path ) && pathinfo( $url_path, PATHINFO_EXTENSION ) === 'php';


The check for the .php extension in the URL is case-sensitive. This could cause URLs with an uppercase .PHP extension to be missed. To ensure all valid PHP file URLs are detected, you should perform a case-insensitive comparison.

return is_string( $url_path ) && 'php' === strtolower( pathinfo( $url_path, PATHINFO_EXTENSION ) );

gemini-code-assist · 2026-01-19T17:10:11Z

src/WP_CLI/CommandWithUpgrade.php

+		$php_files = [];
+		$files     = (array) $decoded_body->files;
+		foreach ( $files as $filename => $file_data ) {
+			if ( is_object( $file_data ) && isset( $file_data->raw_url ) && pathinfo( $filename, PATHINFO_EXTENSION ) === 'php' ) {


When searching for PHP files within a Gist, the check for the .php extension is case-sensitive. This means files with extensions like .PHP would be ignored. To ensure all PHP files in a Gist are found, you should convert the file extension to lowercase before comparing it.

if ( is_object( $file_data ) && isset( $file_data->raw_url ) && 'php' === strtolower( pathinfo( $filename, PATHINFO_EXTENSION ) ) ) {

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-19T17:10:40Z

src/WP_CLI/CommandWithUpgrade.php

+		$api_url = 'https://api.github.com/gists/' . $gist_id;
+		$token   = getenv( 'GITHUB_TOKEN' );
+
+		$request_arguments = $token ? [ 'headers' => [ 'Authorization' => 'Bearer ' . $token ] ] : [];


The authorization header format is inconsistent with the existing code. In get_the_latest_github_version() at line 1070, headers are passed as a string value, but here they are passed as an array. This inconsistency should be fixed to match the existing pattern used elsewhere in the codebase.

Suggested change

$request_arguments = $token ? [ 'headers' => [ 'Authorization' => 'Bearer ' . $token ] ] : [];

$request_arguments = $token ? [ 'headers' => 'Authorization: Bearer ' . $token ] : [];

Copilot · 2026-01-19T17:10:40Z

src/WP_CLI/CommandWithUpgrade.php

+		if ( 403 === $response_code ) {
+			return new \WP_Error(
+				'api_rate_limit',
+				$this->build_rate_limiting_error_message( $decoded_body ),
+				[ 'status' => 403 ]
+			);


There's a potential null pointer issue when handling rate limiting errors. The build_rate_limiting_error_message() method expects an object with message and documentation_url properties, but if the decoded_body is null or malformed, this could cause a fatal error. This check should occur before calling build_rate_limiting_error_message().

Copilot · 2026-01-19T17:10:40Z

src/WP_CLI/CommandWithUpgrade.php

+
+		// Ensure plugin directory exists.
+		if ( ! is_dir( WP_PLUGIN_DIR ) ) {
+			wp_mkdir_p( WP_PLUGIN_DIR );


After calling wp_mkdir_p() to ensure the plugin directory exists, there's no verification that the directory was successfully created. If wp_mkdir_p() fails, the subsequent realpath() checks could return false unexpectedly. Consider checking the result of is_dir(WP_PLUGIN_DIR) after the wp_mkdir_p() call to ensure the directory was created successfully.

Suggested change

wp_mkdir_p( WP_PLUGIN_DIR );

wp_mkdir_p( WP_PLUGIN_DIR );

// Verify that the plugin directory was successfully created.

if ( ! is_dir( WP_PLUGIN_DIR ) ) {

return new WP_Error( 'invalid_path', 'Unable to create plugin directory.' );

}

Copilot · 2026-01-19T17:10:41Z

src/WP_CLI/CommandWithUpgrade.php

+		if ( preg_match( '#^https?://gist\.github\.com/[^/]+/([a-f0-9]+)/?$#i', $url, $matches ) ) {
+			return $matches[1];


The regex pattern uses a case-insensitive flag (i) but the character class [a-f0-9]+ may not match uppercase hexadecimal digits (A-F) in gist IDs. While the 'i' flag makes literal characters case-insensitive, character classes typically need explicit uppercase ranges. If GitHub gist IDs can contain uppercase letters, this pattern should be [a-fA-F0-9]+ or [0-9a-f]+ with case normalization of the gist ID before matching.

Copilot · 2026-01-19T17:10:41Z

src/WP_CLI/CommandWithUpgrade.php

+		if ( null === $decoded_body || ! is_object( $decoded_body ) || ! isset( $decoded_body->files ) ) {
+			return new \WP_Error(
+				'invalid_gist_api_response',
+				'Invalid response from GitHub Gist API.',
+				[ 'status' => 500 ]
+			);
+		}


The error handling for HTTP response codes only explicitly handles 403 (rate limit) and 404 (not found), but other error codes like 401 (unauthorized), 500 (server error), or 503 (service unavailable) fall through to the generic "Invalid response from GitHub Gist API" error message. Consider adding more specific error handling for common HTTP error codes to provide clearer feedback to users.

Initial plan

55a4daa

Copilot AI assigned Copilot and swissspidy Jan 19, 2026

Copilot started work on behalf of swissspidy January 19, 2026 09:59 View session

Copilot AI and others added 6 commits January 19, 2026 10:08

Add support for installing plugins from single PHP file URLs

da838b3

Co-authored-by: swissspidy <[email protected]>

Add documentation and additional tests for PHP file installation

1f1924d

Co-authored-by: swissspidy <[email protected]>

Address code review feedback: add validation and improve code structure

075cb79

Co-authored-by: swissspidy <[email protected]>

Add security validations for path traversal and improve UX with downl…

0b4d7aa

…oad message timing Co-authored-by: swissspidy <[email protected]>

Fix security validations: properly check path traversal and validate …

78e54f7

…plugin headers Co-authored-by: swissspidy <[email protected]>

Optimize: check file existence before download and simplify path vali…

82f7819

…dation Co-authored-by: swissspidy <[email protected]>

Copilot AI changed the title ~~[WIP] Add support for installing plugins from PHP file URLs~~ Support installing plugins from single PHP file URLs Jan 19, 2026

Copilot AI requested a review from swissspidy January 19, 2026 10:20

Copilot finished work on behalf of swissspidy January 19, 2026 10:20

github-actions bot added command:plugin-install Related to 'plugin install' command scope:testing Related to testing labels Jan 19, 2026

Copilot started work on behalf of swissspidy January 19, 2026 12:00 View session

This comment was marked as resolved.

Sign in to view

Copilot started work on behalf of swissspidy January 19, 2026 13:25 View session

This comment was marked as resolved.

Sign in to view

Copilot started work on behalf of swissspidy January 19, 2026 15:33 View session

Add support for GitHub Gist page URLs (gist.github.com)

551fe3e

Co-authored-by: swissspidy <[email protected]>

This comment was marked as resolved.

Sign in to view

Copilot finished work on behalf of swissspidy January 19, 2026 15:39

swissspidy requested a review from Copilot January 19, 2026 16:09

Copilot started reviewing on behalf of swissspidy January 19, 2026 16:09 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

swissspidy and others added 3 commits January 19, 2026 17:18

Update src/WP_CLI/CommandWithUpgrade.php

3a4d190

Co-authored-by: Copilot <[email protected]>

Update src/WP_CLI/CommandWithUpgrade.php

584d505

Co-authored-by: Copilot <[email protected]>

Update src/WP_CLI/CommandWithUpgrade.php

9f699f1

Co-authored-by: Copilot <[email protected]>

swissspidy requested a review from Copilot January 19, 2026 17:05

Copilot started reviewing on behalf of swissspidy January 19, 2026 17:06 View session

gemini-code-assist bot reviewed Jan 19, 2026

View reviewed changes

Copilot AI reviewed Jan 19, 2026

View reviewed changes

	$request_arguments = $token ? [ 'headers' => [ 'Authorization' => 'Bearer ' . $token ] ] : [];
	$request_arguments = $token ? [ 'headers' => 'Authorization: Bearer ' . $token ] : [];

		if ( preg_match( '#^https?://gist\.github\.com/[^/]+/([a-f0-9]+)/?$#i', $url, $matches ) ) {
		return $matches[1];

Support installing plugins from single PHP file URLs #486

Are you sure you want to change the base?

Support installing plugins from single PHP file URLs #486

Conversation

Copilot AI commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Example

Implementation

Files Changed

Comments on the Issue (you are @copilot in this section)

Uh oh!

swissspidy commented Jan 19, 2026

Uh oh!

codecov bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swissspidy commented Jan 19, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 19, 2026 •

edited

Loading

codecov bot commented Jan 19, 2026 •

edited

Loading