benecaster_install_template()
benecaster_install_template( string $zip_path ): array|WP_ErrorValidates and installs a Benecaster design template from a zip file. The zip must contain a benecaster-template.json manifest and a screenshot.png, optionally inside a single root directory. Installed templates land in {uploads}/benecaster-templates/{slug}/ and are recorded in the benecaster_installed_templates option.
Installing does not activate. The active template is a separate setting; installation only makes the template available to choose.
Parameters
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
$zip_path |
string |
— | Yes | Absolute filesystem path to the template zip. |
Return Value
Type:
array|WP_Error
The installed template's manifest as an array — name, slug, version, requires, author, author_url, description, screenshot, install_path, built_in — or a WP_Error with code benecaster_template_install_failed on any failure.
Example
$manifest = benecaster_install_template( $zip_path );
if ( is_wp_error( $manifest ) ) {
return $manifest;
}
// Array access, not object property access.
printf(
'Installed %s v%s',
esc_html( $manifest['name'] ),
esc_html( $manifest['version'] )
);
Notes
Two deliberate departures from TemplateUpload::install(), and code copied from the older class-based examples will break on both.
1. It returns an array, not a TemplateManifest object. Use $manifest['slug'], not $manifest->slug. Handing back the object would make TemplateManifest part of the published surface, which is the exact coupling this layer exists to remove. The array is the manifest's own to_array() shape — the same rows stored in the option — so nothing is lost but the class reference.
2. It returns WP_Error instead of throwing. The class method signals failure with a RuntimeException, which is fine internally and a poor public contract — an uncaught throw from a template upload takes down the request. Every failure comes back as a WP_Error: unreadable zip, over the 50 MB ceiling, missing or invalid manifest, extraction failure. Replace try/catch with is_wp_error().
Authorisation is the caller's job. This writes to the uploads directory and to options and performs no capability check — exactly as the class method it wraps performs none, because core's own REST route checks manage_options before calling it. A CLI command or a background installer has no current user to check, so the check cannot live here. If you are calling this from anything a request can reach, do the capability and nonce checks yourself first — see benecaster_rest_permission_admin().
Need this built rather than just documented? See our services →