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 .gitignore at the root of your new project (e.g. next to the deps file) and paste the following into it. Files matching these patterns will be ignored by git:
/web/bundles/ /app/bootstrap* /app/cache/* /app/logs/* /vendor/ /app/config/parameters.ini
Copy app/config/parameters.ini to app/config/parameters.ini.dist. The parameters.ini file is ignored by git (see above) so that machine-specific settings like database passwords aren't committed. By creating the parameters.ini.dist file, 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.
Managing Vendor Libraries with bin/vendors and deps¶
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 our repository), any other developer can use our 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.
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 into the deps.lock file.
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.
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.