The web root of your project is never the same thing as the root of your source control folder. Typically I recommend an
src directory for all code, then a subdirectory called something like
public which will be your web root. The web root contains only the entry point for your application’s endpoints, typically an
This may or may not form part of your repository. If it does, it should go in a source folder such as the
src example I gave above. You may chose to bring the code in from its own repository, using source control features like submodules in git or externals in SVN. Alternatively, you may consider that the libraries are a platform dependency, place them on each server where they are needed, and either symlink to them or include them as appropriate. This is particularly useful where you have several sites building on the same shared libraries; just put them in a shared place.
Using a tool like phing or ant to repeatably perform tasks within your project is an excellent practice as it can really help to make sure things are done quickly and correctly every time. Any project which takes advantage of these types of tools should include the configuration files (e.g.
build.xml for phing). These should live separate from any application code, perhaps in a
tools directory, or even in the root of the project.
Configuration might be different for every platform that an application runs on, but we still need a template to start from when we work with configuration. To achieve this, create files called something like
config.php.dist which contain example settings that are needed for the config (for bonus points, make these settings correct for the live platform, so that if you ever get this wrong, this platform is fastest to fix!). Every installation will need to copy the file and call it something like
config.php – this should then be ignored by your source control tools so that any changes to it, on any platform, are not shared.
For systems with automated deployments, it can be useful to keep the config file(s) separately on the server, and at deploy time insert a symlink at the point that the application expects the config file to be.
Many applications have extra tools around them, for example I have an open source project that has a command-line tool for trying out the API, and a tool that generates sample data you can use with the application. Both of these are integral to the project and should be kept in the repository – perhaps each inside their own directory.
Most applications will have some way of keeping track of changes to the structure of their databases, and these are as much part of the project changes as the code is! There are tools to help with database changes, and I wrote a post about database patching strategies myself, but either way they usually result in both patch files, and files to manage the patches. Both of these should be in a
database directory or similar, as part of the repo.
Tests are definitely part of your project, so keep those in the repo! This ties in nicely with the comments about phing files, which can be a great way to make it easy for people to run the various test suites that you have. Whether your project uses traditional PHPUnit testing, has functional or behavioural testing, API testing, or all of the above – check all those tests into the repository so that everyone can keep the versions up to date and run them easily.
Everything and the Kitchen Sink
Anything you need for your project belongs in the repo, it’s not unusual to also have documentation as well as everything mentioned above, plus several other things I’ve probably forgotten – so add a comment to tell me what you store in your repo that I didn’t mention?