How does it work?¶

Every Symfony project uses a group of third-party "vendor" libraries. One way or another the goal is to download these files into your vendor/ directory and, ideally, to give you some sane way to manage the exact version you need for each.

By default, these libraries are downloaded by running a php bin/vendors install "downloader" script. This script reads from the deps file at the root of your project. This is an ini-formatted script, which holds a list of each of the external libraries you need, the directory each should be downloaded to, and (optionally) the version to be downloaded. The bin/vendors script uses git to downloaded these, solely because these external libraries themselves tend to be stored via git. The bin/vendors script also reads the deps.lock file, which allows you to pin each library to an exact git commit hash.

It's important to realize that these vendor libraries are not actually part of your repository. Instead, they're simply un-tracked files that are downloaded into the vendor/ directory by the bin/vendors script. But since all the information needed to download these files is saved in deps and deps.lock (which are stored) in the repository), any other developer can use the project, run php bin/vendors install, and download the exact same set of vendor libraries. This means that you're controlling exactly what each vendor library looks like, without needing to actually commit them to your repository.

So, whenever a developer uses your project, he/she should run the php bin/vendors install script to ensure that all of the needed vendor libraries are downloaded.

Hacking vendor libraries¶

Sometimes, you want a specific branch, tag, or commit of a library to be downloaded or upgraded. You can set that directly to the deps file :

1
2
3
4

[AcmeAwesomeBundle]
    git=http://github.com/johndoe/Acme/AwesomeBundle.git
    target=/bundles/Acme/AwesomeBundle
    version=the-awesome-version

• The git option sets the URL of the library. It can use various protocols, like http:// as well as git://.

• The target option specifies where the repository will live : plain Symfony bundles should go under the vendor/bundles/Acme directory, other third-party libraries usually go to vendor/my-awesome-library-name. The target directory defaults to this last option when not specified.

• The version option allows you to set a specific revision. You can use a tag

  (version=origin/0.42) or a branch name (refs/remotes/origin/awesome-branch). It defaults to origin/HEAD.

Updating workflow¶

When you execute the php bin/vendors install, for every library, the script first checks if the install directory exists.

If it does not (and ONLY if it does not), it runs a git clone.

Then, it does a git fetch origin and a git reset --hard the-awesome-version.

This means that the repository will only be cloned once. If you want to perform any change of the git remote, you MUST delete the entire target directory, not only its content.

Vendors and Submodules¶

Instead of using the deps, bin/vendors system for managing your vendor libraries, you may instead choose to use native git submodules. There is nothing wrong with this approach, though the deps system is the official way to solve this problem and git submodules can be difficult to work with at times.