Feb 12, 2019 | composer, jigsaw

A quick introduction to command-line development with Composer

!
Warning: This post is over a year old. I don't always update old posts with new information, so some of this information may be out of date.

Tighten is about to publish a blog post about how to convert your WordPress site to Jigsaw, and I wanted to make sure we had a good tutorial somewhere teaching the basics of working on the command line and using Composer.

So, if you've worked with WordPress before, but you've never worked on the command line or you don't have experience working with Composer, this is for you.

Getting comfortable with the command line

First, let's get you set up with a terminal client, or the application that allows you to interact with your computer's command line.

Linux

If you're working with desktop Linux, you already know how to open up a terminal session. No new steps here.

macOS

If you're working with a Mac, you can find an application named "Terminal" in your Applications folder, under the "Utilities" folder. Open that, and you're ready to go.

If you want a bit of an upgrade, there's a free Terminal replacement named iTerm2 that most developers prefer to Terminal.

Windows

I asked on Twitter about the best way to get a functioning terminal on Windows, and the answers varied, but the most common recommendation was GitBASH, followed by CMDer.

I'm going to recommend GitBASH; you need to have installed Git on your Windows machine anyway, and it comes with GitBASH, so that seems a good place to start. Check out the Git for Windows web site to learn how to install Git and get access to GitBASH.

If you want to upgrade your terminal a little, here's a quick video on how to install and use CMD-er after you install GitBASH: https://www.youtube.com/watch?v=Xm790AkFeK4&feature=youtu.be

If you're running Windows 10, you can get system-level support for terminal access with the WSL (Windows Subsystem for Linux). I don't know exactly how easy it is to set up, but a lot of folks recommended it; here's an intro video: https://www.youtube.com/watch?v=Cvrqmq9A3tA

Getting used to the terminal

The first thing you'll want to get used to is how the terminal works. You're going to see a prompt in front of you that looks something like this:

A screenshot of the default macOS terminal

Exactly what you're going to see here will change based on your environment and the theme loaded by your shell, but most terminals will show at least these details:

  • Machine Name (Launchpad-McQuack): This is the machine-friendly name of your local machine.
  • Path (~): This is where you are in your directory structure. If you see a tilde (~) in the path, that means your user's home directory. On macOS this is /Users/your-user-name-here/.
  • Username (mattstauffer): This is your username on your local machine.
  • The prompt ($): There will be a character to the left of your cursor that just means: "You can type here". It's often a $ or a >, but some terminal themes use other characters.

Moving around, and paths

If you want to move to another directory, you'll want to use the cd command. So, if I want to move to the directory /Users/mattstauffer, I can type cd /Users/mattstauffer.

Because that path starts with a /, I'm telling my terminal that I'm defining the absolute path I want to go to. That means "this path I'm defining is at the root of the computer's file system". Like this: Root / Users directory / mattstauffer directory.

But if I were to start it without the /, that would mean "go to this path beneath the directory I'm already in". So if I typed cd Users/mattstauffer, and I was already in the /Users directory, I'd be saying "take me to /Users/Users/mattstauffer", which, of course, wouldn't work.

For me, all of my web projects live in the /Users/mattstauffer/Sites directory, which I can shorten to ~/Sites. So here's what it looks like when I open up my terminal and want to work on my web site:

cd ~/Sites
cd mattstauffer-com
# (which is the same as:)
cd ~/Sites/mattstauffer-com
# (which is the same as:)
cd /Users/mattstauffer/Sites/mattstauffer-com

Listing files

If you want to list all of the files in your current directory, you'll want to use the ls command. I prefer adding the -al flags when I call it, which makes the listing a lot more readable:

ls -al

Here's a sample output:

drwxr-xr-x   28 mattstauffer  staff     896 Feb 12 09:46 .
drwxr-xr-x   50 mattstauffer  staff    2912 Feb  7 14:07 ..
-rw-r--r--    1 mattstauffer  staff      18 Aug 21  2017 README.md
-rw-r--r--    1 mattstauffer  staff    1286 Dec 20 10:10 package.json
drwxr-xr-x   29 mattstauffer  staff     928 Jan 14 09:43 source

You can technically ignore all of the columns except the far right column, which is the name of the directory or file. If you want to know whether it's a directory or a file, look at the far left character of the far left column; if it's a - it's a file, and if it's a d it's a directory.

The first, third, and fourth columns are about permissions. The second column is basically useless. The fifth (896, etc.) is the file size, in bytes. Then you get the date, and the time, and then the file/directory name.

Installing and using Composer

So, what exactly is Composer? It's primarily a dependency manager. Your project will define its dependencies--the other projects it needs to have access to in order to do its job--and then Composer will install those projects, or packages, and make them accessible to your code.

You'll use a file at the root of your project named composer.json to define those dependencies, and that will auto-generate a file named composer.lock that saves the version of the dependencies you installed so you get those same verisons the next time you install.

Installing Composer

Let's get Composer installed.

You can find the instructions to download and install Composer on your machine on the Composer Downloads page. If you're working with Windows, there's a special installer which you can learn about in the Composer intro docs.

The goal is that, at the end of this installation process, you can run composer from anywhere on the command line and it'll work--which means it's "installed globally" and "in your PATH". My hope is that Composer's installation instructions will be enough to get you there, but if you follow them and this following command doesn't work from any directory on your machine, please let me know on Twitter:

composer -v

Using Composer

Once you have Composer installed, there are a few primary ways you can use it.

Installing an existing project's dependencies

If you clone an existing project that uses Composer, you'll see that it has a composer.json and a composer.lock file in it. But if you try to run the project, it probably won't work. The error usually looks something like this:

Warning: require(/Users/mattstauffer/Sites/symposium/bootstrap/../vendor/autoload.php): failed to open stream: No such file or directory in /Users/mattstauffer/Sites/symposium/bootstrap/autoload.php on line 17

That's because it's trying to access the files Composer loads, but you haven't created them yet; those files are ignored in most projects' version control, with the expectation that you're going to use Composer to install them after you clone. So, let's install them! Run this command from your project's root directory:

composer install

This command reads composer.json and composer.lock and installs all of your required files for you. It'll take a bit, especially the first time you run it, but then your site should just work!

Tip: The files that Composer installs for you go into the vendor directory. You may be familiar with NPM and its node_modules directory. Same deal here.

Adding a dependency to your project

If you need to add a new dependency to your project, or create a project that has a single dependency, you can use composer require packagenamespace/packagename.

In an existing project, this command will add that package to your composer.json and composer.lock files and then install it.

In a new project, that will create your composer.json and composer.lock files and add just that package to them.

Conclusions

There's a lot more to learn about the command line and about Composer, but hopefully this is enough to get you up and running with the basics.

Terms

  • Terminal: An application that lets you access and interact with the command line shell of your computer.
  • Command line: An interface with which computer users issue commands to the computer through successive lines of text.
  • Shell: The specific interpreter or environment a user is interacting with. By default, on most machines, the command line shell will be BASH.
  • BASH: The default command line shell on most machines.
  • Composer: A dependency manager for PHP.

Commands

  • cd: Change directory
  • ls: List files

Comments? I'm @stauffermatt on Twitter


Tags: composer  •  jigsaw

Subscribe

For quick links to fresh content, and for more thoughts that don't make it to the blog.