Composer: good practices

Kuba Werłos

Semantic Versioning

MAJOR.MINOR.PATCH

MAJOR — incompatible (breaking) API changes
MINOR — add functionality in a backwards-compatible manner
PATCH — backwards compatible bug fixes

semver.org

Symfony Backward Compatibility Promise

Semantic Versioning

Dev:		Fixes:
`⟶ 0.1.0`		`⟶ 1.0.1`
Fixes:		Fixes:
`⟶ 0.1.1`		`⟶ 1.0.2`
Breaking changes:		New features:
`⟶ 0.2.0`		`⟶ 1.1.0`
First stable:		Breaking changes:
`⟶ 1.0.0`		`⟶ 2.0.0`

Releasing package

README

LICENSE

CHANGELOG

PHP Package Checklist

Version Constraints

any

*

Version Constraints

exact match

1.0.0 dev-master

Version Constraints

wildcard range

1.0.* 2.*

Version Constraints

hyphen range

1.0 - 2.0 (>=1.0.0 <2.1)

Version Constraints

unbounded range

>=2.0

Version Constraints

operators

(space) ||

Version Constraints

next significant release

~1.2 (>=1.2.0 <2.0.0)

Version Constraints

next significant release

~1.2.3 (>=1.2.3 <1.3.0)

Version Constraints

caret / semver operator

^1.2.3 (>=1.2.3 <2.0.0)

Version Constraints

`~1.2`	(>=1.2.0 <2.0.0)
`~1.2.3`	(>=1.2.3 <1.3.0)

`^1.2`	(>=1.2.0 <2.0.0)
`^1.2.3`	(>=1.2.3 <2.0.0)

Version Constraints

libraries

PHP

PHP extensions

maglnet/composer-require-checker

Version Constraints

composer require acme/package

{
    "require": {
        "acme/package": "^1.2"
    }
}

Overly strict requirements

/* composer.json */
{
    "require": {
        "cool/alice": "~1.3",
        "lazy/bob": "~1.2"
    }
}

/* dependencies */
{
    "name": "cool/alice",
    "require": {
        "monolog/monolog": "~1.6"
    }
}
{
    "name": "lazy/bob",
    "require": {
        "monolog/monolog": "1.3.*"
    }
}

Stabilities

dev ⟶ alpha ⟶ beta ⟶ RC ⟶ stable

Tags
2.0.2 ⟶ stable 2.0.0-alpha2 ⟶ alpha

Branches
2.0 ⟶ 2.0.x-dev (dev) master ⟶ dev-master (dev)

Stabilities

allowing various stabilities

{
    "require": {
        "foo/bar": "^1.0@dev",
        "foo/baz": "^1.0@alpha"
    },
    "minimum-stability": "beta"
}

Minimum stability

Don't set minimum-stability property,

it defaults to stable.

Use stability flags,

… if you REALLY have to.

Specify the production PHP version

{
    "config": {
        "platform": {
            "php": "7.2"
        }
    }
}

`composer.lock`

If does not exist composer install and composer update do the same.

If exists composer install works much faster.

composer.lock in vendor's dependencies will not have any effect.

`composer.lock`

commit it to git in applications

put it into .gitignore in libraries

Check your minimum dependencies

composer update --prefer-lowest

Optimize class map

{
    "autoload": {
        "psr-4": {
            "Acme\\": "src/"
        }
    }
}

composer dump-autoload --optimize
composer dump-autoload --classmap-authoritative

{
    "optimize-autoloader": true,
    "classmap-authoritative": true
}

Commands

{
    "scripts": {
        "post-install-cmd": [
            "MyVendor\\MyClass::warmCache"
        ],
        "analyse": [
            "php-cs-fixer fix --dry-run -v",
            "phpstan analyse"
        ],
        "test": [
            "phpdbg -qrr vendor/bin/phpunit"
        ],
        "verify": [
            "@analyse",
            "@test"
        ]
    }
}

Plugins

brainmaestro/composer-git-hooks

ergebnis/composer-normalize

Awesome Composer # Plugins

Features

depends / prohibits (why / why-not)

$ composer prohibits php:8
doctrine/cache        v1.6.0 requires php (~5.5|~7.0)
doctrine/common       v2.6.1 requires php (~5.5|~7.0)
doctrine/instantiator 1.0.5  requires php (>=5.3,<8.0-DEV)

outdated

$ composer outdated
doctrine/common 2.13.3 3.0.2  PHP Doctrine Common project is a library…
doctrine/dbal   2.12.1 3.0.0  Powerful PHP database abstraction layer…