Documenting Spatie Laravel Package-Tools Integrations

Spatie package maintainers need installation docs that tell users what each package asks Laravel to do. Laravel Package Tools helps package authors configure these steps. A package’s service provider, a Laravel class that registers package services, can declare resources such as configuration files and migrations. It can also define a command that combines setup tasks. These declarations determine what the package provides, so installation steps vary by package.

Use the README and user docs to explain how users install the package: how Laravel loads its provider, which resources work automatically, what users can publish, and whether an install command handles setup. When these details change, update the instructions and examples together. Then compare them with the package’s current provider configuration.

Describe the package’s actual installation path

Name the Composer package and explain what users must do after Composer installs it. Laravel can find a package provider from information in the package’s Composer metadata. If users need to register the provider manually, explain that separately and give the correct location for the Laravel version covered by the docs. Laravel’s package development documentation covers provider discovery and manual registration.

Explain required setup separately from optional setup. Some packages need no published files; others provide configuration or migrations for users to publish. A package can also provide an install command, but Package Tools does not create one for every integration. Its usage documentation describes this command as an option.

For example, the Laravel Permission v8 instructions explain how to install with Composer, register the provider automatically, publish configuration and migrations, complete package-specific checks, and run the migrations. These steps apply to the documented version, not every Spatie package. Put prerequisites, such as editing configuration before running migrations, in the order users must follow them.

Keep provider examples aligned with package code

Here, bootstrapping means Laravel registers and starts a package’s services and resources. Package Tools integrations typically extend Spatie\LaravelPackageTools\PackageServiceProvider and configure a Package instance in configurePackage. This provider configuration names the package and declares its resources and setup behavior.

When you change a provider example, check it against the package code. Include only methods the package uses, such as hasConfigFile(), hasViews(), hasMigration(), or hasInstallCommand(). The provider implementation shows that Package Tools calls configurePackage during registration and handles package startup separately. Keep examples of provider configuration separate from explanations of what Laravel does when it starts the package.

Keep maintainer code separate from user instructions. Maintainer docs can show how the package provider extends Package Tools. User docs should say whether Laravel discovers that provider or users must register it. When the package name, resource path, or view namespace changes, check examples that use those values. Package Tools documents path conventions and publish-tag naming in its README, so examples copied from it must match the package’s configuration.

Match publishing notes to declared resources

For each publishing instruction, name the resource, the command users run, and the expected result. Package Tools provides resource declarations, and the package’s configuration shows which ones it uses. Its README documents these common patterns:

Explain publishing and running migrations as separate actions. Package Tools documents publishing migrations with a timestamp prefix, while runsMigrations() registers migrations without requiring users to publish them. State which approach the package uses and whether users must run migrations themselves. Do not combine the two approaches into the vague instruction to “set up the database.”

If an install command handles publishing or other setup, describe only the steps configured for that package. The command might publish resources or prompt users to run migrations. It might also copy a provider or perform custom actions. Check what the command actually does before replacing manual instructions with a single command. Keep manual instructions when the package has no install command.

Recheck docs when the workflow changes

When Package Tools releases a new version, check whether the integration’s user instructions need an update. The Package Tools changelog records releases and compatibility changes. Compare those changes with your provider configuration and the Laravel versions your package supports.

When a package’s installation steps change, review them from Composer installation through the last required setup step. Check whether Laravel discovers the provider or users must register it manually. Compare each publish tag and destination with the resource declarations. Confirm whether users publish migrations or the package registers them to run, and whether users must edit configuration before migrating. If the package adds or removes an install command, update the recommended steps and any supported manual alternative.

When a package changes its provider implementation, explain how users should update provider files they published. The Laravel Permission upgrade notes give a version-specific example: users who published or extended a provider need to update their references. Include this warning only when the package change requires it, and name the package versions the instruction covers.

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