Project Structure

Page last updated on July 27, 2017

One of the first things to do after getting your hands on the project files is to look around the folders and files.  There are plenty of those.  In this section, we will give you a map of what’s there, to help you navigate around.

Ancestry

Before we look at the actual files, let’s take a moment and understand where all those files are coming from.  There are some variations between different Qobrix applications, but the structure is the same across all of them. Here’s how we set this up.

Project Template

From day one, we knew that we’ll be working on a variety of projects, possibly combining different technologies, and adhering to different standards.  So, very early on, we decided to create a project template that we could use for any PHP-based project.  You can find this setup at project-template GitHub repository.  Given the very generic nature of this template, it only covers the basics of the basics, such as:

  • initial folder structure, that provides a place for public web resources, source code, configuration files, tests, etc,
  • integrations with common development tools, such as PHPUnit, Composer, and others,
  • default settings for quick bootstrapping of any project, be that an application or a library.

Project Template CakePHP

For all our CakePHP-based work, we have created project-template-cakephp.  This repository inherits everything from the generic project template, and adds some more.  As you have probably already guessed, the purpose of this template is to speed up the setup of a CakePHP project.  It brings together the CakePHP framework, a bunch of our plugins, which we consider to be useful for any CakePHP project out there, AdminLTE theme, utilities, and more.

Qobrix Platform

The next level of reuse is the Qobrix platform itself.  It includes everything from the CakePHP project template, and by proxy, everything from the generic project template.  The purpose of the Qobrix Platform is to provide a set of tools and processes for rapid development of the business applications.  So, at this level, we add a few more CakePHP plugins, which are not necessarily useful for every CakePHP application, but are useful for any business application.  We also adjust some configurations for a more specific setup, throw in some integration tests, documentation, etc.

Qobrix Applications

We use Qobrix Platform to build all kinds of business applications.  For completely custom applications, we use the Qobrix Platform as the base.  But for more generic projects, we have a Qobrix Intranet setup, Qobrix CRM setup, and Qobrix Portal setup.  Like with all the previous templates, these applications inherit everything from the previous level.  So any fixes, improvements and new features that we introduce into Qobrix Platform, or CakePHP project template, or the generic project template, will be inherited by the Qobrix CRM, Qobrix Intranet, and Qobrix Portal.  Each of these applications also further fine-tunes the configuration for a more specific use, and introduces more specific functionality.

Qobrix Verticals

With generic tools like CRMs, Intranets, and Portals, we can cover a lot of ground pretty fast.  But we can move even faster if we get more specific.  For us, Forex and Real Estate industries are of the most interest, so we have built some project templates for those too.  For now, we think that’s enough with abstraction.  You get the idea.

Files and Folders

Root Folder

OK, now that you have an idea of what to expect and where things are coming from, let’s look at the root folder of the project.

$ ls -1FA --group-directories-first
bin/
build/
config/
docs/
etc/
.git/
logs/
plugins/
src/
tests/
tmp/
vendor/
webroot/
bitbucket-pipelines.yml
composer.json
composer.lock
.editorconfig
.env
.env.example
.gitattributes
.gitignore
.htaccess
index.php
LICENSE
Phakefile.php
phpcs.xml.dist
phpunit.xml.dist
README.md
.travis.yml

That’s not a lot, is it?  It’ll make even more sense in a second.  Instead of looking at everything alphabetically, let’s group the chunks of this output by purpose.

Git

First things first.  As we mentioned before, we use git version control software to manage all the changes to the project files.  Here are the git-related files and folders:

.git/
.gitattributes
.gitignore

If you are not very familiar with Linux/UNIX file system, keep in mind that:

  • Dot as the first character of a file or folder name means it’s a hidden entity.  You see these in the above listing, because we’ve included a special parameter to show all files, including hidden.
  • Filenames are case-sensitive.
  • You need to keep an eye on the file permissions.  Hint: rwxrwxrwx is not a good thing.

Back to git.  Git keeps all repository related information in a single .git/ folder in the root of the project.  Unlike, for example, Subversion, that uses an .svn/ folder in each folder and sub-folder of a project.  We think, it’s way cleaner and better with a single folder.  So here you go.  gitattributes is a special configuration file for git, that tells it how to handle different file types.  Some of the parameters you can control with this file are end of line characters, text vs. binary, and change comparison tools.  gitignore is another configuration file, which tells git which files and folders should be excluded from the version control.  This file usually contains paths to temporary files, user uploads, caches, thumbnails, etc.

Composer

Second comes Composer, the dependency manager.

bin/composer
vendor/
composer.json
composer.lock

We include a copy of composer (bin/composer) with every project, mainly for two reasons:

  1. It saves a few clicks and seconds when installing a project to a new environment.
  2. Project composer version matches the version that was used to generate the dependencies configuration.

composer.json is the file where dependency configurations and rules are described.  composer.lock is the automatically generated file with specific versions of dependencies required for the current version of the project.  vendor/ is the folder where all the dependencies are installed.

Build and Deploy

The next group of files are there for the build and deploy processes.  They also provide the environment configuration.

build/
.env
.env.example
Phakefile.php

build/ folder is there to collect the artifacts of the build and deploy process.  Things like source code API documentation, unit test coverage, and build version files go there.  .env file provides the environment configuration for the current installation.  It is ignored by git, and can be edited manually (usually on the development environments) or provisioned automatically (usually on server environments).  .env.example is an example configuration, where you can find some documentation and default values for supported parameters.  You can copy .env.example into .env to get started with environment configuration.  Phakefile.php is the configuration and setup script for the build and deploy process.  Look at phake and phake-builder to understand it better.

Quality Assurance

The following files and folders are to assist with project’s quality assurance.

tests/
bitbucket-pipelines.yml
phpcs.xml.dist
phpunit.xml.dist
.travis.yml

tests/ folder contains the automated tests for integration, user interface, environment, etc.  These are usually only the tests for the top level of the project itself.  All components are tested separately, with tests included within their respective repositories. bitbucket-pipelines.yml is the BitBucket Pipelines configuration file, much like .travis.yml is the one for TravisCI.  If you don’t know how to setup a complete environment for testing and running the project, these are your best friends.  phpunit.xml.dist is our default configuration for PHPUnit.  Same way as phpcs.xml.dist is our default setup for PHP CodeSniffer.

CakePHP

Qobrix is built on top of the CakePHP framework, so naturally, we inherit a few files and folders from that project to.  (A few more than just below, but it makes sense to group them this way.)

bin/
config/
logs/
plugins/
src/
tmp/

bin/ folder is there for command line tools and scripts.  config/ contains CakePHP framework configurations, plugin settings, and so on.  logs/ is for application log files.  plugins/ is a legacy folder (mostly empty now) for third-party  plugins.  src/ folder is for PHP source files of the application.  tmp/ folder is for temporary files, like locks and cached data.

Web Root

The following locations are for publicly available files.

webroot/
.htaccess
index.php

It is STRONGLY recommended that you configure your web server to serve files from the webroot/ folder, rather than from the project’s root.  This will make your application much more secure, preventing any kind of access from the source code files, logs, configurations, etc.  But just in case you can’t, both .htaccess and index.php will do the next best thing – redirect any request into the webroot/ folder.

Project Templates

The rest of the files are inherited from the project templates.

bin/phpserv
docs/
etc/
LICENSE
README.md

bin/phpserv is a quick and handy script to fire up the PHP built-in web server.  docs/ folder contains some documentation.  etc/ is for project template related configuration files.  LICENSE is the legal fallback.  README.md is the starting point for the documentation and basic project information.

Variations

It is entirely possible that you see some minor variations in your folder to the above listing.  There are a few reasons for why this can happen:

  • Outdated documentation.  As much as we try to keep documentation up-to-date, sometimes our code writing skills are ahead of our technical writing.
  • Temporary migrations.  Restructuring the project layers and components takes time.  We try to keep things as upgrade-safe as possible, so sometimes you might see a temporary state of things.
  • Project-specific files.  In some cases, you’ll find files and folders specific to your project or environment, which we are not including in the general public documentation.

Whatever the case, don’t panic.  You can use git version control to find out who added the files, when and why.  And you can always ask us too.