{dev_notes}

Composer

Published 4 years ago.
Last updated

Composer is a tool for library dependency management in PHP. Declare what libraries a project depends on and Composer will manage (install/update) them for you.

Composer is not a package manager like Yum or Apt are. Yes, it deals with "packages" or libraries, but it manages them on a per-project basis, installing them in a directory (e.g. vendor) inside your project in a JSON file called composer.json. By default, it does not install anything globally. Thus, it is a dependency manager. It does however support a "global" project for convenience via the global command.

This idea is not new and Composer is strongly inspired by Node's npm and Ruby's Bundler.

How Composer Works

Composer puts these three things in the root directory of a project:

  • composer.json, a file listing the dependencies specified for the project.
  • composer.lock, a file listing the specific versions of all dependencies actually downloaded and used in the project.
  • vendor, the directory where all the libraries Composer has downloaded for the project are stored.

The composer.json file along with composer.lock are the only two files needed to integrate composer into a project. composer.json describes the dependencies of a project and may contain other metadata like the project name and version among other things.

Running composer install from the project root directory resolves all dependencies listed in the composer.json file and downloads the latest version of their files into the vendor directory in the project.

When Composer has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the composer.lock file, locking the project to those specific versions.

Running composer update from the project root directory will fetch the latest matching versions of all dependencies listed in composer.json, resolve and download any new files, and update the composer.lock file with the new versions.

Install composer via Homebrew

  • Switch to an admin user.
  • Install compser via brew.
  • Exit-out of the admin user
$ su - dwattsadmin
$ brew install composer
$ exit

Test composer:

$ composer --version
Composer version 2.8.2 2024-10-29 16:12:11
PHP version 8.3.13 (/opt/homebrew/Cellar/php/8.3.13_1/bin/php)
Run the "diagnose" command to get more detailed diagnostics output.
  • Run composer to see the list of available options.

Basic Compser Project Setup

compser.json

To setup composer in a vanilla (non-framework) PHP project, start by simply creating a compser.json file in the project root directory.

nano composer.json

Place this basic config into the file and save it:

{
    "name": "vendor-name/project-name",
    "require": {
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

The only thing you will need to change is the name attribute.

The package name consists of a vendor name and the project's name seperated by a slash. Often these will be identical - the vendor name only exists to prevent naming clashes. For example, it would allow two different people to create a library named json. One might be named igorw/json while the other might be seldaek/json. It is customary for the vendor name to be your github user name if you plan on sharing packed publically.

Next, from the project root directory run the command composer update to set up Composer in the project. Compser will create a vendor directory where all composer-ralted files will be stored, and a composewr.lock file where specific library verion numbers will be kept.

$ composer update
Loading composer repositories with package information
Updating dependencies
Nothing to modify in lock file
Writing lock file
Installing dependencies from lock file (including require-dev)
Nothing to install, update or remove
Generating autoload files
No installed packages - skipping audit.

You will need to require the /vendor/autoload.php file into your project in order to use composer libraries.This can go whereever you already require an autoloader, or in the bootstap file or right into the file you will be useing to call the library.

autoload.php

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

Install a Composer Library

To install a composer library use the composer require command followed by the vendor and package name of the library from your project root directory:

$ composer require league/csv
./composer.json has been updated
Running composer update league/csv
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking league/csv (9.18.0)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Downloading league/csv (9.18.0)
  - Installing league/csv (9.18.0): Extracting archive
Generating autoload files
1 package you are using is looking for funding.
Use the `composer fund` command to find out more!
No security vulnerability advisories found.
Using version ^9.18 for league/csv

composer require downloadd the library into a new directory in the vendor directory and updates the compser.jsonand composer.ock files with the new code for the library.

Uninstall a Composer Library

To remove a composer library use the composer remove command followed by the vendor and package name of the library from your project root directory:

$ composer remove league/csv
./composer.json has been updated
Running composer update league/csv
Loading composer repositories with package information
Updating dependencies
Lock file operations: 0 installs, 0 updates, 1 removal
  - Removing league/csv (9.18.0)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 0 installs, 0 updates, 1 removal
  - Removing league/csv (9.18.0)
Generating autoload files
10 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
No security vulnerability advisories found.

composer remove should have removed the library from the vendor directory and updated the composer.jsonand composer.lock files.

Using a Composer Library

Using a library class is dependant on the library you downloaded, but the vendor should give you instructions. You will need to putuse lines at the top of the file to point to the library classes before you use it, it might look something like this:

use League\Csv\Reader;
use League\Csv\Statement;

// Use a library class.
$csv = Reader::createFromPath('/path/to/your/csv/file.csv', 'r');

Packagist

Packagist is the main Composer repository, a place where you can get packages. Packagist aims to be the central repository that everybody uses. This means that you can automatically require any package that is available there, without further specifying where Composer should look for the package.

Any open source project is encouraged to publish their packages on packagist.org. A library does not need to be on packagist.org to be used by Composer, but it enables discovery and adoption by other developers more quickly.

NOTES:

  • Ignore the vendor directory in version control. All third part code can be downloaded by Composer directly on the server where the project is deployed, simplifying the repository.
  • Track both the composer.json and composer.lock files for the project in version control.