The Composer Asset Plugin allows you to manage project assets (css, js, etc.) in your composer.json without installing NPM or Bower.

This plugin works by transposing package information from NPM or Bower to a compatible version for Composer. This allows you to manage asset dependencies in a PHP based project very easily.

The next major version of Composer Asset Plugin is so different, but also incompatible with the current version, that it became a new project named Foxy.

Foxy is the new way to manage the assets of PHP libraries, because it works nativelly with all the features of NPM or Yarn. However, this plugin will continue to be maintained by the community, without having new features.

Features include:
  • Works with native management system versions of VCS repository of composer
  • Works with public and private VCS repositories
  • Lazy loader of asset package definitions to improve performance
  • Import filter with the dependencies of the root package and the installed packages, for increased dramatically the performance for the update
  • Automatically get and create an Asset VCS repository defined in:
  • NPM Registry
  • Bower Registry
  • Private Bower Registry
  • Automatically get and create the Asset VCS repositories of dependencies defined in each asset package (dev dependencies included)
  • Mapping conversion of asset package to composer package for:
    • NPM Package — package.json
    • Bower Package — bower.json
    • Conversion of Semver version to the composer version
    • Conversion of Semver range version to the composer range version
    • Conversion of dependencies with URL to the composer dependencies with the creation of VCS repositories
    • Conversion of multiple versions of the same dependency to different dependencies of composer
    • Add manually the multiple versions of a same dependency in the project
    • Add a custom config of VCS Repository
    • Override the config of VCS Repository defined by the asset registry directly in config section of root composer
    • VCS drivers for:
      • Git
      • GitHub (compatible with repository redirects)
      • Git Bitbucket
      • Mercurial
      • Mercurial Bitbucket
      • SVN
      • Perforce
      • Local cache system for:
        • package versions
        • package contents
        • repository redirects
        • Custom asset installers configurable in the root file composer.json
        • For Bower, all files defined in the section ignore will not be installed
        • Disable or replace the deleting of the ignore files for Bower
        • Enable manually the deleting of the ignore files for NPM
        • Use the Ignore Files Manager in the Composer scripts
        • Configure the plugin per project, globally or with the environment variables
        • Compatible with all commands, including:
          • depends
          • diagnose
          • licenses
          • remove
          • require
          • search (bower only)
          • show
          • status
          • Why this plugin?

            There already are several possibilities for managing assets in a PHP project:

            1. Install Node.js and use NPM or Bower command line in addition to Composer command line
            2. Do #1, but add Composer scripts to automate the process
            3. Include assets directly in the project (not recommended)
            4. Create a repository with all assets and include the composer.json file (and use Packagist or an VCS Repository)
            5. Add a package repository in composer.json with a direct download link
            6. Create a Satis or Packagist server
            7. Other?

            It goes without saying that each javascript, CSS, etc. library should be developed with the usual tools for that language, which front-end developers know well. However, in the case of a complete project in PHP, it shouldn’t be necessary to use several tools (PHP, Nodejs, Composer, NPM, Bower, Grunt, etc.) to simply install these assets in your project.

            This plugin has been created to address these issues. Additionally, most developers will not add a composer.json file to their projects just to support php based projects, especially when npm and/or bower already exist and are widely used.


            The bulk of the documentation is located in Resources/doc/ :


            All the installation instructions are located in documentation.


            This composer plugin is under the MIT license. See the complete license in:


            Fxp Composer Asset Plugin is a François Pluchino initiative. See also the list of contributors.

            Reporting an issue or a feature request

            Issues and feature requests are tracked in the Github issue tracker.

            Установил последней версии composer Поставил последнюю версию composer-asset-plugin 1.2.0

            Пытаюсь установить yii2 через композер composer create-project —prefer-dist yiisoft/yii2-app-basic basic Вылетает ошибка

            • yiisoft/yii2 2.0.9 requires bower-asset/jquery 2.2.@stable | 2.1.@stable | 1.11.@stable | 1.12.@stable -> no matching package found.
            • yiisoft/yii2 2.0.8 requires bower-asset/jquery 2.2.@stable | 2.1.@stable | 1.11.*@stable -> no matching package found.
            • yiisoft/yii2 2.0.7 requires bower-asset/jquery 2.2.@stable | 2.1.@stable | 1.11.*@stable -> no matching package found.
            • yiisoft/yii2 2.0.6 requires bower-asset/jquery 2.1.@stable | 1.11.@stable -> no matching package found.
            • yiisoft/yii2 2.0.5 requires bower-asset/jquery 2.1.@stable | 1.11.@stable -> no matching package found.
            • Installation request for yiisoft/yii2 >=2.0.5 -> satisfiable by yiisoft/yii2[2.0.5, 2.0.6, 2.0.7, 2.0.8, 2.0.9].

            Погуглив, рецепта не нашел. Все равно вылетает одна и та жа ошибка. Подскажите, плиз, что делать.

            Решил все снести и заново поставить композер на макбук согласно инструкции

            sudo mv composer.phar /usr/local/bin/

            alias composer="php /usr/local/bin/composer.phar"

            Далее через терминал поставил плагин composer global require "fxp/composer-asset-plugin:^1.2.0" (папки bower-asset в папке .composer не обнаружил)

            Запустил через терминал в рабочей папки composer create-project —prefer-dist yiisoft/yii2-app-basic basic и вылетают те же самые ошибки, что требуется requires bower-asset/jquery 2.*@stable

            пробуя разные советы из форумах и на стековерфлоу так и не смог разобраться почему не ставится bower-asset/jquery через плагин fxp/composer-asset-plugin (пробовал разные версии)

            в итоге поставил yii2 в ручную, но все же не дает пок, чем вызвана проблема с композером. У кого были похожие проблемы с установкой на мак плиз отпишите как их решали. Спасибо!

            See the Release Notes to know the Composer version required.

            Global scope (per user) installation

            Project scope installation

            The installation in the project scope is not supported (see the issue #7).

            Usage with asset repository

            Adding a dependency on an asset, you must add the asset to the property require of the composer.json of your project.

            It must be prefixed with -asset/ .

            Example for twitter bootstrap:


            Usage with Private Bower Registry

            You can work with your private Bower server build with Hacklone Private Bower:

            Adding the URL to your Private Bower Server in the composer.json in the section config . This Asset Plugin automaticly look if there is a private Bower URL defined and search for your Private Bower Package.


            Usage with VCS repository

            If your asset is not listed on the NPM- or Bower-Repository, or it is a private package, you can create a VCS repository for it. The repository must have an asset package file for NPM ( package.json ) or Bower ( bower.json ).

            In addition, the repository must respect the specifications of [Bower Spec] ( or NPM Spec for the package files. Concerning the version numbers and the tags, they must respect the [Semver 2.0] ( format.

            If your repository does not contain a tag that repsent the number, you must put the flag @dev or directly use the development branch dev-master .


            Add the following to your composer.json :

            Availables drivers:

            Drivers NPM Bower
            auto npm-vcs bower-vcs
            Git npm-git bower-git
            GitHub npm-github bower-github
            Git Bitbucket npm-git-bitbucket bower-git-bitbucket
            Mercurial npm-hg bower-hg
            Mercurial Bitbucket npm-hg-bitbucket bower-hg-bitbucket
            SVN npm-svn bower-svn
            Perforce npm-perforce bower-perforce

            Overriding the config of a VCS Repository

            If you must use a repository other than that indicated by the registry of NPM or Bower, you must specify the name of the package with the asset prefix in the config of the VCS Repository.


            You can also use the standard format of Composer for naming your VCS Repository:

            Usage with multiple versions of the same dependency

            If you need to use multiple versions of the same asset, you can do this by simply adding a version number after the package name, separated with the "-" character.

            Example with Jquery:

            The dependencies will then be placed in the following directories:

            • vendor/bower-asset/jquery for 1.11.*
            • vendor/bower-asset/jquery-2.0.x for 2.0.x
            • vendor/bower-asset/jquery-2.1.0 for 2.1.0

            Reduce the number of requests for getting the package definitions

            The root Composer package has a feature: all asset dependencies added will have automatically a filter applied, before the importation of the branches and the tags.

            In this way, all versions are not accepted by the constraint of version and they will be skipped to the importation, and will not be injected in the Pool . Of course, all constraints of versions are functional (exact version, range, wildcard, tilde operator).

            For example:

            The root composer.json :

            In case you have an dependency that that requires a sub asset dependency, and given that this optimization cannot be performed with the sub dependencies, you can add this asset dependency directly to the root Composer package, in the same way that if you wanted to use a well-defined version of this dependency.

            Disable the import filter using the installed packages

            By default, and for dramatically optimize performance for the update , the plugin filters the imports of definitions packages. In addition to filter with the dependencies in the root Composer package, the plugin filters the imports of packages definitions with the previous versions of the packages installed.

            However it may happen that Composer throws an exception, indicating that it can not find a compatible version. This happens if a dependency uses a new version lower than the installed version.

            Of course, several solutions can work around the problem (see the [FAQs] (, but the solution below may be used in another use case.

            You can disable the import filter using the versions of installed packages with the option config.fxp-asset.optimize-with-installed-packages in the root Composer package:

            Change/Disable the skip of versions by pattern

            By default, the plugin does not import the patch versions for increase dramatically performance. However, it is possible to change the pattern or to disable this feature.

            Example for change the pattern:

            Example for disable the pattern:

            Disable the conjunctive option of the import filter

            You can disable the conjunctive mode of the import filter with the option config.fxp-asset.optimize-with-conjunctive in the root Composer package:

            This option is used only if the optimization with the installed packages is enabled

            Define a custom directory for the assets installation

            By default, the plugin will install all the assets in the directory vendors/-asset and packages will be installed in each folder with their asset name.

            But you can change the installation directory of the assets directly in the root composer.json -file of your project:

            For Bower, all files defined in the section ignore will not be installed

            Disable or replace the deleting of the ignore files for Bower

            For Bower, all files defined in the section ignore will be delete just after the installation of each package. Of course, this behavior can be disabled or replaced.

            Example for disable the list of ignored files:

            Example for replace the list of ignored files:

            Enable manually the deleting of the ignore files for NPM

            For NPM, there is no section ignore , but you can manually add the patterns for delete the files:

            Work with the NPM scopes

            NPM can manage the package with the vendor scopes ( @ / ), but Composer has already a namespace for vendors, and this plugin create a virtual vendor for the NPM assets ( npm-asset/ ). Futhermore, the @ character is not managed by Composer for the package name.

            For this reason, the NPM scope @ / is converted into — .

            NPM package name Composer package name
            @ / npm-asset/ —

            Use the Ignore Files Manager in the Composer scripts

            Sometimes you need to clean a package that is not considered an NPM/Bower Asset Package. To do this, you can use the script helper FxpComposerAssetPluginComposerScriptHandler::deleteIgnoredFiles for the post-package-install or post-package-update script events.


            Override the main files for Bower

            The bower.json specification allows packages to define entry-point files which can later be processed with taskrunners or build scripts. Some Bower plugins like main-bower-files, wiredep and asset-builder have a feature to override the package main files in the project configuration file.

            You can do the same with composer-asset-plugin, just add a section config.fxp-asset.main-files in the root project composer.json file with the package name and the files you want to mark as main files.


            Disable the search for an asset registry

            If you want to disable the search for an asset registry, you can add the option config.fxp-asset.registry-options.-searchable in the root project composer.json -file.


            Use no-api option of VCS Githhub driver

            If you want to use the no-api option for your Github assets, you can add the option config.fxp-asset.vcs-driver-options.github-no-api in the root project composer.json file. By default, this option is to false . The option config.fxp-asset.pattern-skip-version can be used to exclude tags via a regular expression.

            You can further define this option for each package:

            With this configuration, all your github packages will use the native Git, except for the bower-asset/example-asset1 package.

            Solve the conflicts of asset dependencies

            Bower include a resolution section to solve the conflicts between 2 same dependencies but with different versions.

            As for NPM, it’s possible to install several versions of the same dependency by different dependencies, which is not the case for Bower and Composer. Only the installation of a single version compatible for all dependencies is possible.

            The dependency resolution would force (replace) a version or range version directly in the root Composer package.


            Result, all asset packages with the bower-asset/jquery dependency will use the ^3.0.0 range version.

            Note: Be careful when replacing the version, and check the compatibility before.

            Define the config for all projects

            You can define each option ( config.fxp-asset.* ) in each project in the composer.json file of each project, but you can also set an option for all projects.

            To do this, you simply need to add your options in the Composer global configuration, in the file of your choice:

            • /composer.json file
            • /config.json file

            Note: The composer global config command cannot be used, bacause Composer does not accept custom options. But you can use the command composer global config -e to edit the global composer.json file with your text editor.

            Define the config in a environment variable

            You can define each option ( config.fxp-asset.* ) directly in the PHP environment variables. For this, all variables will start with FXP_ASSET__ and uppercased, and each — will replaced by _ .

            The accepted value types are:

            • string
            • boolean
            • integer
            • JSON array or object


            Can be overridden by FXP_ASSET__PATTERN_SKIP_VERSION="(-build)" environment variable.


            Can be overridden by FXP_ASSET__VCS_DRIVER_OPTIONS='<"github-no-api": true>’ environment variable.

            Config priority order

            The config values are retrieved in priority in:

            1. the environment variables starting with FXP_ASSET__
            2. the project composer.json file
            3. the global /config.json file
            4. the global /composer.json file
            5. the deprecated config extra.asset-* of the project composer.json file

            Disable the plugin

            When you working on multiple PHP projects, you do not necessarily need to use the plugin. It’s possible to disable the plugin with the config.fxp-asset.enabled option with the false value.

            For example, you can disable the plugin globally (for all your projects), and enable it only for projects requiring the plugin.


            Note: If you disable the plugin, and your project require this plugin, Composer will throw an exception indicating that the asset dependencies does not exist.