PHP Composer Basics

Submitted by NanoDano on Sat, 03/21/2020 - 16:02

Introduction

Composer is a command-line tool for managing dependencies in PHP projects. In this guide we will look at how to install Composer and use it to add and install some project dependencies.

Install Composer

On all platforms, you can download and use composer.phar directly. Go to the downloads page and scroll to the "Manual Download" section. The latest version at the time of writing is 1.10.0. You will of course need PHP installed also.

php composer.phar --help

To help with the setup process, you can use a composer setup script. Download this file and name it composer-setup.php: https://getcomposer.org/installer.

# You can delete `composer-setup.php` after running
php composer-setup.php
composer --help

In MacOS, you can also use Homebrew to install:

brew install composer
composer --help

In Windows, you have a couple additional options. There is a Windows installer that will setup composer on your PATH.

Another Windows option is to use Chocolatey to install:

choco install composer
composer --help

Start a new project

To start a new project, you simply need a composer.json file. You can generate one using the command:

composer init

This will create a composer.json with your project information like name and dependencies. As long as you have a name entry in your composer.json then you can import your project in to other composer projects as a dependency.

Add required dependencies

To add a requirement for a project, use composer require like this:

composer require laravel/framework
composer require cakephp/cakephp

This will update your composer.json and add the dependencies

Install dependencies

To download all dependencies specified in the composer.json file, run:

composer install

This will create a vendor/ directory with all the dependencies.

Including dependencies in source

You can import dependencies from the vendor/ directory manually, or you can simply include one special file (vendor/autoload.php) and have access to everything in your vendor directory.

In your main PHP file, you can include the file like this:

// Reference script relatively
require 'vendor/autoload.php';

A better way to import it, ensuring it always has the correct absolute path is like this using the __DIR__ constant.

require __DIR__ . '/vendor/autoload.php';

After this require, you can reference any imported class by its namespace.

Require a local package

If you want to load a composer package locally instead of from a remote repository, you can add it as a local repository of type path with the url of the relative or absolute path to the package. Your composer.json might look like this:

{
    "repositories": [
        {
            "type": "path",
            "url": "../library"
        }
    ],
    "require": {
        "devdungeon/example": "*"
    }
}

Create your own library

Let's look at how to create your own custom library for use in your application.

To see the example on GitHub, check out https://github.com/DevDungeon/PHP-Composer-Package-Example.

Example directory structure of library:

library/
├── composer.json
└── src/
    └── MyClass.php

Here is an example library/composer.json. The name is the name of your package, the name you will require in your main application. The autoload section is important, and here it tells PHP to map every file in the src/ directory to the DevDungeon\ namespace. For example, library/src/MyClass.php that contains a class named MyClass would map to \DevDungeon\MyClass.

{
    "name": "devdungeon/example",
    "version": "1.0.0",
    "description": "An example PHP composer package",
    "authors": [
        {
            "name": "John Leon",
            "email": "nanodano@devdungeon.com"
        }
    ],
    "require": {},
    "autoload": {
        "psr-4": {
          "DevDungeon\\": "src/"
        }
      }
}

Here is the example source code for library/src/MyClass.php:

<?php
// The filename should match the class name

namespace DevDungeon;

class MyClass {
    var $something = 'Some text';
    public function say_hello() {
        echo 'Hello!';
    }
}

To use the library, in your application, add the local library path as a repository and specify the package name and version in the require

Here is an example composer.json from an application directory that lives next to the library directory. For example:

library/
application/
application/main.php
application/composer.json

{
    "repositories": [
        {
            "type": "path",
            "url": "../library"
        }
    ],
    "require": {
        "devdungeon/example": "1.0.*"
    }

}

Install with composer install to create the vendor/ directory and setup autoloading. Then your main.php file might look like this:

<?php
require_once __DIR__ . '/vendor/autoload.php';


$object1 = new \DevDungeon\MyClass();
echo $object1->something;

// Or

use \DevDungeon\MyClass;
$object2 = new MyClass();
$object2->say_hello();

Conclusion

After reading this guide you should understand how to perform basic tasks with Composer like initializing a project, adding depenencies, and importing the dependencies for use.