Skip to content
PHP Ecosystem
Explore

Frequently asked questions

This content is not available in your language yet.

Which PHP and Composer versions are required?

Section titled “Which PHP and Composer versions are required?”

Foxy 0.4 requires PHP 8.3 or later and Composer 2.10.2 or later. See the requirements.

Why use Foxy instead of documenting frontend dependencies manually?

Section titled “Why use Foxy instead of documenting frontend dependencies manually?”

A PHP library can ship a package.json, but Composer does not merge that file into the consuming application. Without automation, every application must copy dependency names and constraints manually and keep them synchronized with each library release.

Foxy creates local frontend package representations for eligible Composer dependencies, merges them into the project package.json, and delegates version solving and installation to Bun, Deno, npm, pnpm, or Yarn, or performs both itself with the native manager.

An installed Composer package is eligible when it contains the expected package definition and at least one of these conditions applies:

  • It requires php-forge/foxy.
  • It declares extra.foxy=true.
  • The root project enables it through config.foxy.enable-packages.

The root project can also explicitly exclude a package through enable-packages.

How are local frontend packages named and stored?

Section titled “How are local frontend packages named and stored?”

The Composer name is converted to the @composer-asset/ scope. For example, acme/theme becomes @composer-asset/acme--theme.

Mock package definitions are stored under <vendor-dir>/php-forge/composer-asset/ by default. The project package.json refers to those definitions with local file: dependencies. Configure composer-asset-dir to use a different location.

Set config.foxy.manager to bun, deno, native, npm, pnpm, or yarn for deterministic selection. When it is omitted and manager execution is enabled, Foxy first looks for one recognized lockfile and then for an available manager executable. With execution disabled, it uses a single recognized lockfile or npm as the manifest adapter without probing binaries. Multiple recognized lockfiles require explicit selection in either mode. The native manager is selected only explicitly or through its foxy.lock file, never by availability. The choice is made when the first install, update, or audit needs a manager, so other Composer commands neither probe executables nor report selection errors.

Explicit selection and a committed lockfile are recommended for CI.

Can Foxy install frontend dependencies without Node.js?

Section titled “Can Foxy install frontend dependencies without Node.js?”

Yes. Set config.foxy.manager to native. Foxy reads the merged package.json, resolves every dependency against the npm registry with one version per package, downloads and verifies the tarballs, extracts them into node_modules, and records the result in foxy.lock. PHP with the zlib extension is the only requirement. The native manager does not run lifecycle scripts and does not create bin links. See Native manager for the complete scope.

How can frontend dependencies be checked for known CVEs?

Section titled “How can frontend dependencies be checked for known CVEs?”

Run composer foxy:audit. Foxy audits the dependency graph from the selected manager’s own lockfile. The default table, plain, and JSON formats identify the affected package, advisory, severity, vulnerable range, and available CVE identifiers. Use --format=summary for compact counts in CI or --format=json for a versioned machine-readable document.

The registry’s audit response commonly contains a GHSA but no CVE. Foxy resolves that relationship through GitHub’s public advisory API unless --no-cve or --format=summary is supplied. The lookups run concurrently through Composer’s HTTP downloader (at most 12 at once; COMPOSER_MAX_PARALLEL_HTTP changes the limit), and a github-oauth token in Composer’s auth.json applies to them. A lookup failure marks only its own advisory as unavailable without hiding the security finding itself. See Security auditing for options and exit statuses.

Why is a dependency’s package.json not detected?

Section titled “Why is a dependency’s package.json not detected?”

Check the following:

  1. The package uses one of the documented activation methods.
  2. Its package.json exists at the package root or configured Foxy root.
  3. The root application’s enable-packages configuration does not exclude it.
  4. When manager execution is enabled, the selected frontend manager is installed and allowed by its configured version constraint.

Composer must run before a standalone frontend manager command because Foxy creates the local package representations during Composer install and update operations.

What happens when the frontend manager fails?

Section titled “What happens when the frontend manager fails?”

When the manager throws or returns any non-zero status, Foxy reports the error and, by default, restores the previous project package.json, Composer lock data, and installed Composer dependencies. The original manager error is rethrown when restoration succeeds. If a restoration also fails, the rollback error retains the original error as its previous exception.

Set fallback-asset or fallback-composer to false only when retaining partial state is intentional. A Composer rollback installer failure is reported as a RuntimeException rather than being hidden.

The Composer fallback does not restore root composer.json bytes that Composer may change before Foxy takes its snapshot. After a failed composer require or composer remove, inspect that file and revert unintended constraint changes manually.

Why does Foxy do nothing during Composer —dry-run?

Section titled “Why does Foxy do nothing during Composer —dry-run?”

Composer does not install, update, or remove packages during a dry run, so Foxy cannot build an accurate map from the resulting installed packages. Run the real Composer operation to validate the complete Composer and frontend manager operation; enabled fallbacks restore their captured state when asset solving fails.

Can Foxy update package.json without installing frontend dependencies?

Section titled “Can Foxy update package.json without installing frontend dependencies?”

Yes. Set config.foxy.run-asset-manager=false. Foxy will update the package definition without probing or validating the external manager, running its commands, or removing existing node_modules/@composer-asset/* installations during npm reconciliation.

Why are a dependency’s scripts or devDependencies not copied?

Section titled “Why are a dependency’s scripts or devDependencies not copied?”

Foxy mock packages contain only metadata needed for runtime dependency resolution and compatibility checks. Omitting lifecycle scripts, executable definitions, devDependencies, and unrelated publishing metadata prevents an installed Composer dependency from injecting those behaviors into the root frontend install.

Publish built assets with the Composer package, or configure intentional build commands and development dependencies in the consuming application’s own package.json.

Why is my custom composer-asset-dir rejected?

Section titled “Why is my custom composer-asset-dir rejected?”

Foxy deletes and rebuilds its mock package directory on every solve. It refuses filesystem, project, and vendor roots; paths that contain either protected root; symbolic-link directories; and existing non-empty custom directories without Foxy’s .foxy-managed marker.

If the directory predates Foxy 0.3, verify that it contains only generated mock data, remove its contents, and rerun Composer. Foxy accepts an empty custom directory and creates the ownership marker automatically. See Mock package directory.

How can the PHP memory limit be increased?

Section titled “How can the PHP memory limit be increased?”

See Composer’s memory limit troubleshooting guide.

Section titled “How is Foxy related to Fxp Composer Asset Plugin?”

Fxp Composer Asset Plugin made frontend packages available through Composer’s solver. Foxy takes the opposite approach: Composer packages expose frontend definitions and a native frontend manager performs frontend version solving and installation. Foxy is not backward compatible with Fxp Composer Asset Plugin configuration.

Back to documentation