Foxy 0.3 requires PHP 8.3 or later and Composer 2.10.2 or later. See the requirements.
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, npm, pnpm, or Yarn.
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.
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, npm, pnpm, or yarn for deterministic selection. When it is omitted and manager
execution is enabled, Foxy first looks for one recognized native 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.
Explicit selection and a committed native lockfile are recommended for CI.
Run composer foxy:audit. Foxy audits the dependency graph from the selected manager's native 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 native registry 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. A lookup failure is shown as unavailable
without hiding the native security finding. See Security auditing for options and exit
statuses.
Check the following:
- The package uses one of the documented activation methods.
- Its
package.jsonexists at the package root or configured Foxy root. - The root application's
enable-packagesconfiguration does not exclude it. - 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.
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 Composer 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.
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.
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.
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.
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.
See Composer's memory limit troubleshooting guide.
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.