composer.json Basics

Every Composer-managed project has a composer.json file sitting in its root folder. It's the project's manifest — a plain JSON file that declares what your project needs (its dependencies), plus metadata about the project itself (its name, description, and more). Composer reads this file to know what to download, and writes back to it whenever you add or remove a package.

Common Top-Level Fields

Creating One Interactively with composer init

Rather than hand-writing composer.json from scratch, you can let Composer build it for you by answering a short set of prompts:

$ composer init

It will ask for a package name, description, author, the type of project, license, and whether you'd like to interactively add dependencies right away. Once you confirm the generated JSON, Composer writes it out to composer.json in the current folder.

A Full Annotated Minimal Example

{
    "name": "acme/my-app",
    // short, human-readable summary of the project
    "description": "A small demo application",
    // packages required at runtime
    "require": {
        "php": ">=8.1",
        "monolog/monolog": "^3.0"
    },
    // packages only needed for development/testing
    "require-dev": {
        "phpunit/phpunit": "^10.0"
    },
    // maps our own namespace to a folder for autoloading
    "autoload": {
        "psr-4": {
            "Acme\\MyApp\\": "src/"
        }
    }
}

Note that JSON doesn't actually support comments — the // lines above are only there to explain each part; a real composer.json would omit them (Composer will error on genuine comments in the file).

Version Constraint Syntax Basics

The values inside require aren't just exact version numbers — they're constraints that tell Composer which versions are acceptable. The three you'll see most often: