Add --slug option to plugin/theme install for custom directory naming

[Copilot]

Installing a plugin or theme from a ZIP file often results in a directory name that doesn't match the intended slug (e.g., archives with branch names like my-plugin-master). This adds a --slug=<slug> option to wp plugin install and wp theme install to control the installation directory name.

Changes

• CommandWithUpgrade::install(): Reads --slug from assoc args; errors early if combined with multiple sources; adds an upgrader_source_selection filter that renames the extracted directory to the provided slug, taking precedence over the existing GitHub auto-rename heuristic
• Plugin_Command / Theme_Command: Doc block updated with [--slug=<slug>] option
• Behat tests: Added scenarios for installing from a remote ZIP with --slug, and for the error case when --slug is combined with multiple sources

Example

# Install a ZIP but place it under a known slug instead of the archive's directory name
wp plugin install https://example.com/my-plugin-1.2.3.zip --slug=my-plugin
# Renamed 'my-plugin-1.2.3' to 'my-plugin'.
# Plugin installed successfully.

# Errors when used with multiple sources
wp plugin install plugin-a.zip plugin-b.zip --slug=foo
# Error: The --slug option can only be used when installing a single item.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Allow theme slug renaming</issue_title>
<issue_description>Please allow theme slug renaming. For example:
wp install theme .zip --slug=foo

I just encountered that need when I used URLs from GitLab. I installed a parent theme, and it was given a weird name that the host probably derives from its commit ID.
Then I tried to install its child theme, and got an error, because it couldn't find its parent theme.
If I could install the parent theme and set its slug, that wouldn't have happened.</issue_description>

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

@danielbachhuber > Please allow theme slug renaming. For example: > wp install theme .zip --slug=foo

How is this different than using unzip?</comment_new>
<comment_new>@schlessera
WP-CLI already supports an action that is similar to unzip, namely installing a plugin/theme from a ZIP file, instead of from the plugin repository.

As we already have that functionality, we should make sure that it is useful in all of the common scenarios, ZIP files having the wrong slug is a very common scenario, so I think we should add support for that.</comment_new>
<comment_new>@danielbachhuber
Couple other pieces of relevant information:

• WP-CLI already has magical renaming behavior for GitHub URLs: wp plugin install when using GitHub URLs, remove -master wp-cli#2994
• wp theme install <theme|zip|url>... supports multiple sources. A --slug=<slug> argument could only work with one theme specified because multiple themes can't be installed to the same directory.</comment_new>
  <comment_new>@schlessera
  Yes, when I looked through the code and saw the renaming for the Github URLs, I thought we could build the slug parameter so that:
• --adapt-slug=<name> will put the theme into a folder <name>
• --adapt-slug will extract the ZIP, check the plugin/theme header for the name and use that as slug.

The second variation (without argument) could also be used for multiple archives.</comment_new>

• Fixes Allow theme slug renaming #74

---

💡 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.

[swissspidy]

This repo does not exist yet and needs to be created first