Essential Tools for Modern PHP

Git

Git is one of the most popular version control systems, originally created for aiding development of the Linux kernel.

To start working with Userfrosting, you will need to use git. Git is important to use with UserFrosting for four reasons:

  1. Many of the asset management tools that UserFrosting depends on, use git;
  2. It makes it easier to merge updates in UserFrosting into your project;
  3. It makes it easier for you and your team to keep track of changes in your code, and allows your team to work simultaneously on different features;
  4. It makes it easy to deploy and update your code on your production server (if you're using a VPS or dedicated hosting).

git is not the same as GitHub! GitHub is a "social coding" company, while git is the open-source software around which GitHub was built. Many open source projects choose to use GitHub to host their git repositories, because GitHub offers free hosting for public repositories. However, you should be aware that there are other companies that offer free git hosting such as Atlassian (Bitbucket). Unlike GitHub, Atlassian also offers free private repositories. You can also set up your own server to host repositories, or use a third-party package such as Gitlab, which has GitHub/Bitbucket-like features such as issue tracking, code review, etc.

Installing git (MacOS)

By default, MacOS and other *nix operating systems should come with git preinstalled. If you would like to update your version of git, you can do so with their installer.

Installing git (Windows)

Git has an installer that you can use for Windows - Git Download.

Composer

Up until March of 2012, PHP didn't really have a good project-level package manager. There was PEAR, but it failed to keep up with the evolution of the PHP community. In March of 2012, on the heels of the PHP Standard Recommendations (PSR) project, Composer was released and a new era of PHP began.

If you've been out of the PHP world for a while, you might have missed this critical shift. Over the past few years, Composer has risen to become the de facto package manager for PHP, with Packagist as its main public package repository. This means that the best way to incorporate third-party code (which you definitely should do) is by installing and using Composer - at the very least, in your development environment.

Composer also handles autoloading, which means that the days of needing long blocks of include or require statements in your code are over. It fully implements the PSR-4 standard for autoloading, which further helps the PHP community develop a consistent approach to releasing and consuming packages.

To check if Composer is already installed:

$ composer --version
Composer version 1.3.1 2017-01-07 18:08:51

The full instructions for installing Composer can be found at their website. We strongly recommend that you install Composer globally on your system. This will let you run Composer using the composer command. For convenience, we recap the global installation instructions here:

Installing Composer (MacOS and *nix)

  1. Download and run the installer as per the instructions on the downloads page.
  2. Run mv composer.phar /usr/local/bin/composer to make composer available as a shell command.

You may need to run the above command(s) with sudo.

On some versions of MacOS the /usr directory does not exist by default. If you receive the error "/usr/local/bin/composer: No such file or directory" then you must create the directory manually before proceeding: mkdir -p /usr/local/bin.

Installing Composer (Windows)

Composer has a special installer that you can use for Windows - Composer-Setup.exe. If this gives you trouble, you can try the manual installation instructions.

Node.js

Node.js is an an extremely popular JavaScript runtime built on Chrome's V8 JavaScript Engine. In recent years it has become extremely popular for creating multiplatform applications, and for its role in providing a means to run the platform independent build tools, like gulp and grunt, to name just a few. Node.js also includes npm (Node.js Package Manager).

Finally, you will need to install Node.js, Javascript runtime. Although UserFrosting does not run on Node.js, it does use several Node-based tools to fetch client-side Javascript and CSS dependencies, as well as perform critical build tasks.

The Node.js website provides easy-to-use installers for most operating systems. We recommend using the latest version of Node.js (7.x at the time of this writing), however any version later than 4.x will suffice.

To check if Node.js is installed:

$ node -v
v7.4.0

Even though we'll be using these tools to get our application ready for deployment, you don't actually need to install Node.js on your live server. You can install it locally, perform your installation and build tasks, and then push the built application to the live server afterwards.

Installing Node.js (MacOS and Windows)

Node.js has an installer that you can use for MacOS and Windows - Node.js Download.

npm

npm stands for Node Package Manager. npm is to Node.js as Composer is to PHP - it is used to grab the various Node packages that are required by UserFrosting's installation and build tools. When you installed Node, it should have automatically installed npm as well. However, we still recommend updating npm (if unable to update, any version later than 3.x will suffice):

$ npm install [email protected] -g

UserFrosting also uses Bower, a frontend package manager. If you do not have this installed, don't worry! UserFrosting's build scripts will automatically install it for you.

Coding and style standards

Standards are boring. But guess what? "Boring" == "predictable" - a good thing when it comes to writing code. Most of your time spent as a developer is actually spent reading, not writing code. Without a clean set of standards and good comments, it can be difficult to read your own code 3 months after you wrote it, let alone someone else's code.

The increasingly modular and community-driven nature of software development means that it is important not just to have internal coding standards, but community-wide standards as well. We strongly recommend that you familiarize yourself with some basic standards for PHP, Javascript, and CSS:

  • PHP: PHP-FIG
  • HTML and CSS: Code Guide by @mdo
  • Javascript: The Javascript community (which, let's face it, is HUGE) has so far failed to adopt a single set of coding standards. Over the past few years, Airbnb's coding guidelines have started to gain a lot of traction. It is extremely thorough and widely used, and for these reasons we recommend it.

Comments and API documentation generators

Sooner or later, you may want to generate some low-level documentation for every class and function in your application. Don't try to do this by hand!

Instead, by following a specific set of standards for in-code comments ("doc blocks"), you can use automated tools that will scan your codebase and generate the appropriate documentation.

PHP

For PHP code, use the phpDoc standard to document your classes, methods, and member variables. You can then use ApiGen to automatically generate clean, attractive, fully searchable API documentation for your application.

Javascript

For Javascript, use the JSDoc standard and tool to comment your code and generate an attractive set of API documentation. It is consistent with Airbnb's commenting standards.