composer-packages

composer-packages

When to use

Use this skill when creating, maintaining, or publishing Composer library packages — including Laravel packages with service providers, Artisan commands, and config publishing.

Procedure: Work with Composer packages

1. Read the package's composer.json for structure and dependencies.
2. Check if it's a Laravel package (look for extra.laravel.providers).
3. Read the package's README.md and CHANGELOG.md.
4. Check the agents/ directory in the package for package-specific docs.

Known packages

Check the project's composer.json for organization-specific packages. Check agents/overrides/skills/composer-packages.md for the package registry and known packages list.

Package structure

my-package/
├── src/                    # Source code
│   ├── App/
│   │   └── Providers/      # Laravel service providers
│   └── ...
├── config/                 # Publishable config files
├── tests/                  # Package tests
├── composer.json           # Package manifest
├── README.md               # Documentation
├── CHANGELOG.md            # Version history
└── agents/                 # Package-specific agent docs

composer.json essentials

Required fields

{
    "name": "vendor/my-package",
    "type": "library",
    "description": "Clear, concise description",
    "require": {
        "php": "^8.2"
    },
    "autoload": {
        "psr-4": {
            "Vendor\\MyPackage\\": "src/"
        }
    }
}

Laravel package auto-discovery

{
    "extra": {
        "laravel": {
            "providers": [
                "Vendor\\MyPackage\\App\\Providers\\PackageServiceProvider"
            ]
        }
    }
}

Composer scripts / plugins

Packages can hook into Composer lifecycle events:

{
    "scripts": {
        "post-install-cmd": [
            "MyNamespace\\ComposerScripts::onInstall"
        ]
    }
}

Version constraints

Use wide version ranges for library packages to maximize compatibility:

{
    "require": {
        "php": "^8.1 || ^8.2 || ^8.3 || ^8.4",
        "illuminate/support": "^10.0 || ^11.0 || ^12.0"
    }
}

Libraries should use || ranges. Applications should use ^ (caret).

Advisories, abandoned packages, audit

• composer audit --locked checks the lockfile against the Packagist advisory database; CI should run it so a known advisory is a red check, not a surprise. It exits non-zero when it finds something — that is the answer, not an error.
• config.audit in composer.json (abandoned: fail, ignore with a reason per advisory ID) makes Composer itself refuse on install; an ignore without a reason is a silenced finding, not an accepted one.
• Abandoned packages show in composer outdated --direct and in composer audit; pick the suggested replacement before the abandonment becomes an unpatched advisory.
• The Composer binary is a dependency too — it has had its own advisories; keep it on a supported release (composer self-update --stable).
• Ongoing monitoring between changes: agent-config audit:deps refresh reads the lockfile, the declared PHP version and the PHP release feed, and names what needs action today.

Local development

Path repositories

In the consuming project's composer.json:

{
    "repositories": [
        { "type": "path", "url": "../packages/my-package" }
    ]
}

Then: composer require vendor/my-package:@dev

Development project

If the organization has a dedicated development sandbox for testing packages, use it for local testing.

Publishing

Private registry (GitHub Packages / Satis)

Packages are published to a private Composer registry. Check the organization's Satis or GitHub Packages setup.

Pre-publish checklist

1. composer validate — verify composer.json is valid.
2. composer dump-autoload — verify autoloading works.
3. Run tests: vendor/bin/phpunit or vendor/bin/pest.
4. Run quality tools: PHPStan, ECS, Rector.
5. Update CHANGELOG.md with the new version.
6. Tag the release: git tag v1.2.3.

Conventions

• Follow the organization's namespace convention (check existing packages).
• Use declare(strict_types=1) in all PHP files.
• Use typed properties, parameters, and return types.
• Follow the same coding standards as the main projects (see php-coder skill).
• Include agents/ directory for package-specific documentation.

Output format

1. Package files following standard Composer structure
2. Updated composer.json with correct autoloading and dependencies
3. Service provider and config publishing (if Laravel package)

Auto-trigger keywords

• Composer package
• library development
• package versioning

Gotcha

• Don't add composer.lock to library packages — it should be in .gitignore for libraries (not apps).
• Minimum stability must be explicit — don't assume stable.
• The model tends to set overly restrictive version constraints — use ^ (caret) not = (exact).

Do NOT

• Do NOT use * version constraints in library packages.
• Do NOT require specific patch versions — use ^ or || ranges.
• Do NOT include dev dependencies in require — use require-dev.
• Do NOT forget to run composer validate before publishing.
• Do NOT publish without updating the changelog and tagging.