Documenting a Laravel Package v1 to v2 Upgrade

When a Laravel package moves from v1 to v2, users need to update their Composer requirements, configuration, code, and stored data. An upgrade guide should put those changes in order and mark which steps every user must take and which apply only to certain configurations or features.

A package’s configuration file contains its settings. Users can publish a copy to their Laravel project and customize it there. A database migration changes stored data or the way it is organized. Because both affect existing projects, the guide should say what users need to keep, replace, or run. It should also identify v1 methods and features that have replacements or have been removed.

Start with a verified change inventory

Before writing the guide, compare the package’s v1 and v2 code, tests, default settings, database migrations, and dependency requirements. At the top, list the PHP and Laravel versions the package supports and any new dependencies users must install. Laravel includes dependency compatibility in major-release planning, but package users need the versions supported by the package itself. They should not assume those versions from the framework requirements in the Laravel release notes.

Record each change, such as a changed setting, public method or property, method arguments or behavior, command, event, exception, container binding, database structure, or dependency. This list helps maintainers find changes beyond renamed methods. A package will not necessarily have changes in every category.

For each change, use one of these labels: renamed, removed, behavior changed, or new requirement. Use a label that tells users what to do: give the new name for a renamed method, say what to delete or use instead of a removed feature, and explain the effect of changed behavior. The Laravel Badge major-version guidance lists areas to review.

Keep examples tied to the package they describe. For instance, Tenancy for Laravel’s v1-to-v2 guide says its rewrite changed the tenant identity from uuid to id; that is a change specific to that package, not a convention for Laravel upgrades generally.

Explain how users should migrate configuration

For each changed setting, show the v1 key or value and its v2 replacement. Explain what users should do with custom values: edit the existing file, replace it, or publish a new file and copy their settings over. If v2 removes a key, say whether users should delete it or use another setting to get the same behavior.

Laravel packages can provide default settings. A Laravel project can publish a configuration file and use it to override those defaults. Laravel’s package-development documentation explains how packages publish configuration and merge defaults. It notes that mergeConfigFrom merges only the first level of a configuration array. If v2 changes settings inside nested arrays, explain how users can preserve their overrides.

If users must carry over custom values, telling them to republish the configuration file is not enough. Tenancy for Laravel’s guide tells users to publish and configure the v2 file again, but does not list every old and new key on that page. A guide with the same limitation should tell users to compare their existing settings with the new defaults.

Show renamed methods and changed behavior

For each change to a public API, show code from before and after the change. Include changes to arguments, return values, and behavior, not just a renamed method. When relevant, show affected calls in templates or JavaScript as well as PHP.

For example, Livewire’s v2-to-v3 guide says to replace emit() with dispatch() and emitTo() with dispatch()->to(). It also says event parameters now need names. These examples show how to present a change, but they apply to Livewire, not to Laravel packages in general. The Livewire upgrade guide shows them in context.

Explain return-value changes just as clearly. Tenancy for Laravel documents that tenancy() returns a TenantManager, while tenant() returns the current Tenant or null if no tenant has been identified. The guide also describes changing the tenant identifier from uuid to id. These details affect how users write code that calls the methods, not just which method or property name they use.

If v1 methods still work as compatibility aliases, say so and explain whether the package plans to remove them. If they no longer work, name the error users will encounter, such as a missing-method error, and show the replacement.

Describe removals and their alternatives

Explain each removed feature on its own. Tell users what to delete, what behavior they will lose, and whether v2 provides another way to get the same result. If there is no replacement, say so.

Tenancy for Laravel’s v1-to-v2 guide says the package dropped Predis support and removed the old domain field or key as part of its multi-domain changes. Livewire’s v2-to-v3 guide says it removed emitUp() because events now bubble by default, and removed wire:click.prefetch entirely. These examples show why guides should clearly separate removals from renames. They describe changes in those packages, not in an unspecified package.

Separate database changes from code changes

Explain database changes separately so users know what will happen to their stored data. Name the tables or columns that change, say whether users need to convert existing data, and give the migration command to run. Make clear whether users must publish migration files into their project or run migrations that the package provides directly.

Tenancy for Laravel’s v2 upgrade notes describe a database-driver change in Tenancy for Laravel. The change renames the tenant uuid column to id and removes domain. It also adds a domains table. The guide also says the old migration was renamed. Users who publish the migrations again must delete the old migration file to avoid creating the same table twice. This instruction applies to that package’s migration history. Maintainers should give similar instructions only if their package has the same issue.

Explain any step that deletes data or cannot be undone. If a migration drops a column, say what data the column contains and whether users must copy or convert that data first. If users should delete or replace a migration file, explain when and why.

Put the upgrade steps in dependency order

Give users an ordered sequence that fits the package’s code and deployment needs. The order below is a guide, not a rule for every Laravel package. Mark each step as required or conditional so users know which actions apply to their installation.

1. Check compatibility. Confirm the required PHP, Laravel, and dependency versions.
2. Prepare a reversible change. Tell users to work in a branch and back up any configuration or data that a later step will replace.
3. Update the Composer constraint. Provide the exact package requirement and installation command for the package being documented.
4. Migrate configuration. Say whether users should publish a new file, edit the existing one, or replace it. Explain how to keep their custom values.
5. Apply database changes. Explain whether users must publish migrations, remove old or duplicate files, convert existing data, and run the migrations.
6. Update code and integrations. Replace methods, properties, commands, events, or other interfaces, including changes in templates or JavaScript.
7. Remove unsupported features. Tell users what to delete or what v2 mechanism replaces it.
8. Run package-specific checks. Include cache clearing or asset rebuilding only when the package requires it, then tell users what behavior to test.

The Laravel ClickUp API v1-to-v2 changelog shows how clear ordering helps. It tells users to update Composer, back up and replace the configuration, publish migrations, and run them. That order applies to this package. Another package may require users to convert data before changing configuration, or to deploy code and migrations in a different order.

Verify the path and state compatibility

Test the instructions on a project running v1. Include a published configuration file and existing database data when the package uses them. Run each command in the stated order and confirm users can get the v2 behavior without taking undocumented manual steps.

Tell users what to check after upgrading. If the package stores data in a database, name the feature that should still work after the migrations. If behavior depends on configuration, name the setting or output that shows the new configuration is active. If the package provides an automated upgrade command, explain what it changes and what users must still check. For example, Livewire’s guide warns that its upgrade command does not complete the migration on its own.

Finally, say whether v1 remains supported and whether deprecated methods still work in v2. Some maintainers keep old methods for compatibility; others remove them. Explain the package’s policy and what it means for users. Do not suggest that every major release handles compatibility the same way.

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