How to Create and store a Symfony2 Project in git
How to Create and store a Symfony2 Project in git¶
Though this entry is specifically about git, the same generic principles will apply if you're storing your project in Subversion.
Once you've read through Creating Pages in Symfony2 and become familiar with using Symfony, you'll no-doubt be ready to start your own project. In this cookbook article, you'll learn the best way to start a new Symfony2 project that's stored using the git source control management system.
Initial Project Setup¶
To get started, you'll need to download Symfony and initialize your local git repository:
Download the Symfony2 Standard Edition without vendors.
Unzip/untar the distribution. It will create a folder called Symfony with your new project structure, config files, etc. Rename it to whatever you like.
Create a new file called
.gitignoreat the root of your new project (e.g. next to the
depsfile) and paste the following into it. Files matching these patterns will be ignored by git:
1 2 3 4 5 6
/web/bundles/ /app/bootstrap* /app/cache/* /app/logs/* /vendor/ /app/config/parameters.ini
You may also want to create a .gitignore file that can be used system-wide, in which case, you can find more information here: Github .gitignore This way you can exclude files/folders often used by your IDE for all of your projects.
parameters.inifile is ignored by git (see above) so that machine-specific settings like database passwords aren't committed. By creating the
parameters.ini.distfile, new developers can quickly clone the project, copy this file to
parameters.ini, customize it, and start developing.
Initialize your git repository:
$ git init
Add all of the initial files to git:
$ git add .
Create an initial commit with your started project:
$ git commit -m "Initial commit"
Finally, download all of the third-party vendor libraries:
$ php bin/vendors install
At this point, you have a fully-functional Symfony2 project that's correctly committed to git. You can immediately begin development, committing the new changes to your git repository.
After execution of the command:
$ php bin/vendors install
your project will contain complete the git history of all the bundles
and libraries defined in the
deps file. It can be as much as 100 MB!
If you save the current versions of all your dependencies with the command:
$ php bin/vendors lock
then you can remove the git history directories with the following command:
$ find vendor -name .git -type d | xargs rm -rf
The command removes all
.git directories contained inside the
If you want to update bundles defined in
deps file after this, you
will have to reinstall them:
$ php bin/vendors install --reinstall
You can continue to follow along with the Creating Pages in Symfony2 chapter to learn more about how to configure and develop inside your application.
The Symfony2 Standard Edition comes with some example functionality. To remove the sample code, follow the instructions in the "How to remove the AcmeDemoBundle" article.
Managing Vendor Libraries with bin/vendors and deps¶
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
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
git to downloaded these, solely because these external libraries
themselves tend to be stored via git. The
bin/vendors script also reads
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
vendor/ directory by the
bin/vendors script. But since all
the information needed to download these files is saved in
(which are stored) in the repository), any other developer can use the
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
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.
There is also a
php bin/vendors update command, but this has nothing
to do with upgrading your project and you will normally not need to use
it. This command is used to freeze the versions of all of your vendor libraries
by updating them to the version specified in
deps and recording it
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
gitoption sets the URL of the library. It can use various protocols, like
http://as well as
targetoption specifies where the repository will live : plain Symfony bundles should go under the
vendor/bundles/Acmedirectory, other third-party libraries usually go to
vendor/my-awesome-library-name. The target directory defaults to this last option when not specified.
versionoption 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
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
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
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
Storing your Project on a Remote Server¶
You now have a fully-functional Symfony2 project stored in git. However, in most cases, you'll also want to store your project on a remote server both for backup purposes, and so that other developers can collaborate on the project.
The easiest way to store your project on a remote server is via GitHub. Public repositories are free, however you will need to pay a monthly fee to host private repositories.
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.