Documenting Optional Features in Laravel Packages

People who maintain Laravel packages need to show which setup steps every user must complete and which apply only to a feature, integration, or customization. An integration connects a package to another service or library. Publishing copies a package resource, such as a configuration file or view, into the Laravel application so users can change it.

Document package installation, feature setup, and resource publication separately. Give users a short set of steps for ordinary use, then explain each extra step beside the feature or customization that needs it. This keeps a feature-specific requirement from sounding like every user must follow it.

Keep the baseline setup small

Start with the steps users need for ordinary package use. Give the Composer installation command and list any setup every user must complete, such as running a required migration or adding a trait to a model. A migration changes the database structure; a model trait adds package behavior to a Laravel model.

Tell users what Laravel handles automatically. When a package lists its service provider in Composer metadata, Laravel can register it through package discovery, its automatic way to find and register package providers. Discovery does not tell users whether they must also configure an external service, publish a resource, or enable a feature. The Laravel package-development documentation describes provider discovery and the resources packages can register or publish.

Make the baseline path easy to identify with a label such as Required for all users. If a step applies only to a feature, move it out of that path and name the feature in the instruction. For example, “Add this trait to models that use slugs” tells readers who needs the step; “Add this trait” does not.

Put integration requirements beside the integration

Give each optional integration its own subsection. Name the dependency, external service, credentials, and configuration that the integration requires. Then state plainly which users can skip the instructions.

Laravel Scout illustrates the distinction. Its Laravel 13.x documentation says the database search engine needs no external service, while using Algolia requires its PHP SDK and credentials. A package that supports several backends should explain each path separately rather than put every backend’s dependencies in a universal setup checklist.

Composer metadata can reinforce the distinction. Composer’s suggest field lists packages that can add features or work with a package but are not required. Maintainers should still explain which feature uses a suggested package and how to configure it. The metadata entry alone does not tell users when to install it. See Composer’s package schema.

Label the step by who needs it. Required only for Algolia search tells readers more than Optional, which leaves them unsure whether the step is optional for everyone or required for some users.

Explain what publishing changes

For every publishable resource, say what Laravel copies, why a user would publish it, and whether the copy is required. Laravel packages can publish configuration and migrations, as well as views and translations. They can also publish public assets. Separate publish tags let maintainers expose resource groups independently, as described in Laravel’s package documentation.

Explain separately whether a package loads its views and whether users need to publish them. A package can register and load its views without copying them into the application; users publish them when they want to customize them, so calling view publication “required setup” would suggest the package cannot use its views otherwise.

Migrations need package-specific wording. One package may require users to publish and run a migration; another may register migrations through a different mechanism. For example, Spatie Media Library v11 requires publishing and running its migration to create the media table, while its configuration publication is optional. Spatie Sluggable v4 says users need to publish its configuration only when they want to replace the defaults. These versioned examples illustrate package-specific behavior; requirements vary across Laravel packages.

A short resource table can make these distinctions easy to scan:

Adjust the wording to match the package’s actual implementation. If a package requires a migration for its baseline use, label it Required for all users and explain what the migration creates. If it is needed only for a particular capability, name that capability.

Repeat prerequisites on feature pages

Readers often open a feature page directly, so repeat its prerequisites there rather than relying on them to find and remember a general setup section. For example: “Requires the Algolia SDK and Algolia credentials. Skip this section if you use the database engine.” Link to the baseline installation instructions for steps that every user needs.

Keep the labels consistent throughout the documentation: Required for all users, Required only for [feature], Optional: publish to customize, and Alternative setup. Use Optional only when the step is genuinely optional for the users reading that section.

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