Designing a Minimal Public API for Laravel Packages

When you maintain a Laravel package, every documented method, published setting, and supported container binding gives users a way to depend on your code. A package’s public API is the set of those supported ways to use or customize it. A smaller, deliberate API leaves more room to change internal code without requiring users to change theirs.

Semantic Versioning, or SemVer, is a versioning convention that ties version numbers to compatibility changes. After a package reaches version 1.0.0, SemVer calls for a major version when a change breaks the declared public API. The practical task is to define that API clearly: expose the operations and choices users need, and keep implementation details outside the supported boundary.

Decide which package surfaces you support

Start by listing every way an application can interact with the package. The public API may include PHP classes and methods, configuration keys, and container bindings that tell Laravel’s service container what to provide. It may also include facades, Artisan commands, published files, and ways for consumers to add or replace behavior, such as interfaces or callbacks. Laravel’s package development documentation describes several of these integration mechanisms, while SemVer explains why maintainers should declare which ones users can rely on.

Treat every documented or deliberately supported feature as something users can rely on, and preserve it or make a compatible change. For example, if your documentation tells users to resolve a particular service from Laravel’s container, that binding belongs in your API inventory. If users can publish a configuration file and set one of its keys, that key and its meaning also belong there.

A short inventory helps you separate the ways users are meant to access the package from details they should not rely on. Record the main tasks consumers perform and the configuration they can change. List the container bindings they can use, along with the commands and files they can access. Also record how they can add or replace behavior. If users should not depend on a class or binding, do not present it as a normal way to use the package.

Expose operations, not internal steps

Make public methods correspond to tasks package consumers need to perform. Keep methods that coordinate internal steps, expose a temporary algorithm, or mirror the current class structure out of the supported API unless consumers have a concrete reason to call them.

PHP visibility controls access to class members. A public member is accessible from anywhere, a protected member is accessible within its class and subclasses, and a private member is accessible only within the class that defines it. Use private for helpers that consumers should not call or override. Use protected when subclass customization is a deliberate extension mechanism. The PHP visibility rules also make explicit declarations important: members without a visibility modifier are public.

PHP visibility rules do not let you restrict a top-level class to use only within a package. A class can remain autoloadable and instantiable even when the package maintainer considers it internal. Namespaces, directory layout, and documentation can signal that status, but they do not enforce a language-level boundary. Keep internal classes out of the documented usage path and direct users to the supported entry point.

Keep configuration focused on user decisions

Expose a configuration option when consumers need to make that choice, such as selecting a supported driver or choosing how the package behaves. Avoid keys that merely reflect internal class names, algorithms, or wiring. Applications can rely on each published key, so changing its name or meaning can require a compatibility change.

For each supported option, document its default and accepted values. Explain its effect as well. Laravel’s package guide describes publishing configuration and merging package defaults. It also notes two version-specific constraints for Laravel 10.x: mergeConfigFrom merges only the first level of an array, and configuration files should not define closures because config:cache cannot serialize them correctly. Check the documentation for the Laravel versions your package supports before applying those details more broadly.

Choose extension points deliberately

Add an interface, callback, or driver mechanism when consumers need to supply or replace behavior. Avoid making every internal collaborator replaceable by default. Each extension point asks users to understand and maintain a contract, and it limits how freely you can change the implementation behind it.

Laravel’s service providers connect package services and resources to the framework. The Laravel 13.x provider guidance says to use register for container bindings and to register routes, event listeners, and other functionality elsewhere, such as boot. These rules explain when the provider connects package features to Laravel. They do not mean application code should rely on every provider detail or every binding. Name the bindings consumers may rely on and leave internal bindings undocumented.

A facade offers convenient access to a service; a contract makes the dependency explicit through an interface. Laravel’s contracts documentation treats the choice as context-dependent. Choose a primary usage path where that keeps the package straightforward, and document both paths if you intentionally support both.

A smaller boundary eases compatibility work

SemVer sets different expectations for changes to public and private code. After version 1.0.0, a backward-incompatible public API change calls for a major version; backward-compatible public functionality belongs in a minor version, and backward-compatible fixes belong in a patch version. SemVer also treats the public API of a 0.y.z release as unstable.

A smaller declared API gives maintainers fewer details to preserve when they refactor. If consumers rely on a helper method or internal class, they may treat it as a promise the package must keep, even if the package never intended to support it. The benefit is a reasoned consequence of compatibility rules, not a measured guarantee that every small API reduces upgrade time.

Keep the boundary broad enough to cover the tasks and customizations you promise. An API that hides a needed capability can force users to build workarounds. Test documented consumer paths and supported configuration overrides. Include promised extension points too, so tests cover what users rely on without locking in internal structure.

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