Documenting Laravel Package System Requirements

A Laravel package’s system requirements tell developers which PHP runtime and Laravel components they need. They also list the PHP extensions required to install and use the package. Maintainers declare requirements Composer can enforce in composer.json, the file Composer reads to resolve dependencies. They also explain those requirements in the README, which describes the package for readers. Both sources should agree: Composer checks the constraints during installation, and the README explains what each requirement supports.

Set requirements based on the package’s code and supported features. Laravel’s general server requirements do not automatically apply to every package. State the minimum versions the package needs. Separate optional features from core behavior. Published compatibility claims should match the versions maintainers intend to support.

Set requirements from the package’s code

Set a PHP version range that includes the language features the package uses and the PHP versions maintainers support. Composer treats PHP as a platform dependency: it checks the constraint against the PHP environment used to resolve dependencies. A README statement such as “PHP 8.3 or newer” informs readers, but only a constraint such as ^8.3 in composer.json blocks installation in an incompatible environment.

Declare Laravel compatibility through the framework components the package uses. Laravel’s package-development documentation says a package that uses the base service provider should require illuminate/support. If the package uses a more specific framework API, require the matching illuminate/* component. Set the version constraint to match the Laravel major releases the package supports. Laravel’s release documentation recommends explicit constraints such as ^13.0 for framework references because a major release can include breaking changes.

Laravel’s support policy does not define which Laravel releases a package supports. A package might support only some releases, even when Laravel itself supports a wider PHP range. List the Laravel versions the package supports separately. Keep the README’s compatibility claims consistent with its Composer constraints and the versions maintainers intend to test.

Declare required and optional dependencies

Add a PHP extension to require when the package needs it for core behavior. Composer identifies extensions with the ext- prefix. For example, if all core behavior depends on the Mbstring extension, the package could declare:

{
  "require": {
    "php": "^8.3",
    "illuminate/support": "^13.0",
    "ext-mbstring": "*"
  }
}

These values show the format. Maintainers must use constraints that match their package. The * constraint requires the extension without naming a specific extension version. Composer checks for a missing required extension while resolving dependencies. Developers can use composer show --platform to see which PHP extensions are available in an environment, as described in Composer’s platform dependency documentation.

Check the package’s code and dependencies before copying Laravel’s full server extension list into its manifest. Laravel’s deployment requirements describe the baseline for a web server running a Laravel application. The framework’s Composer manifest lists a different and narrower set of required extensions. Because these sources cover different needs, maintainers should identify which extensions their package requires.

Use Composer’s suggest field for optional packages or extensions that enable a feature but are not required for core behavior. A suggestion tells the installer about the dependency, but Composer does not enforce it, and the feature will not work without it. Laravel’s framework manifest connects suggestions to specific features, such as Redis support or a testing helper. Name the feature and explain what the dependency enables. In the README, say what happens when users do not install the optional dependency.

Keep developer tools separate from runtime requirements. Use Composer’s require-dev field for development dependencies, such as testing and code analysis tools. Composer documents this field as root-only and allows users to exclude development dependencies with --no-dev. Put tools used to test the package in require-dev; put dependencies consumers need at runtime in require.

Present compatibility in the README

Summarize which Laravel versions and minimum PHP versions each package release line supports. If compatibility changes between releases, show the differences instead of using one broad statement that might misrepresent a release. A Laravel package prerequisite page shows this table format.

After the version summary, list required extensions by their Composer identifiers, such as ext-mbstring. Separate these from extensions used only by optional features. Explain which features optional Composer packages enable. If a feature also needs an external service or server configuration that Composer cannot describe with a dependency constraint, state that requirement in the README.

Make the README easy to read and precise. For example, “Laravel 12 and 13” names the supported major versions more clearly than “recent Laravel versions.” If a package release has different PHP minimums for those Laravel versions, show each minimum instead of implying that one applies to every combination.

Keep the declared range aligned with support

A Composer constraint tells the dependency resolver which versions it can install. It does not prove that the package works with every combination in that range. Before publishing the compatibility table, compare it with the package’s composer.json and the combinations maintainers intend to support and test. When the package drops a Laravel major version or raises its PHP minimum, update the constraint and the table together.

Laravel’s release page lists PHP version ranges and support dates for framework releases. These details change over time. Use them as context when choosing which versions to support, but set a separate compatibility policy for the package. The package’s README should list the versions the package supports; Laravel’s documentation lists the versions Laravel supports.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com