Support Laravel Package

Getting Started

1. Establish whether you're using it or just carrying it. Most installs are transitive via orchestra/testbench. Find out before writing code against it:

composer why orchestra/support
composer show orchestra/support

If nothing in your src/ references Orchestra\Support, it's a dev-only dependency. If you want to actually leverage it in application code, promote it to require and pick a version deliberately:

composer require "orchestra/support:^7.0"

v7 requires Laravel 9+ / PHP 8.0+ (8.1 for Laravel 10, 8.2 for Laravel 11). On Laravel 8, pin 6.x and don't start here.

2. Read the source first — there is no docs site. The v7.0.0 changelog is one line. Spend your first 20 minutes on:

ls -R vendor/orchestra/support/src

You'll find four families of files that matter day-to-day:

• A base service provider — the scaffolding you extend in your own packages.
• A message collection (Messages / MessageProvider-style) — a bag for accumulating notices and errors before rendering.
• An in-memory registry (Memory) — shared runtime data without threading arguments through call stacks.
• Str / Arr helpers and traits — the string utilities Orchestra packages depend on.

Check composer.json autoload for file-loaded helper functions. If they're not file-autoloaded, you must import the class explicitly.

3. First use case: a base provider for one of your own packages. This is the highest-value, lowest-risk entry point. If you maintain more than one Laravel package, inheriting a shared provider base kills the "how did we register routes/config/facades in the other package?" review cycle:

namespace Acme\Billing;

use Orchestra\Support\ServiceProvider as BaseServiceProvider;

class BillingServiceProvider extends BaseServiceProvider
{
    public function boot(): void
    {
        parent::boot();

        $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
    }
}

Confirm the exact base-class name and hooks in src/ before you rely on boot() semantics — the hooks are the whole value proposition, so read them rather than guess.

4. Prove it in a scratch package. Run it through orchestra/testbench in a throwaway package before it touches a product repo. That's your whole evaluation and it costs an afternoon.

Implementation Patterns

1. Inherit the provider base across every package in the portfolio. The reason to adopt this package is convention. If you extend the base for package A but hand-roll register()/boot() for package B, you paid the dependency cost and kept the drift:

// Every package provider in the portfolio:
class InventoryServiceProvider extends BaseServiceProvider { /* ... */ }

Keep the vendor parent class name in one place — an internal Acme\Support\PackageProvider that extends theirs — so a future major version surfaces in one file.

2. Use the message collection instead of bespoke arrays. The most common day-to-day reach is accumulating validation or business-rule failures in a shape that renders and flashes consistently:

use Orchestra\Support\Messages;

$messages = new Messages;
$messages->add('error', 'Payment gateway rejected the charge.');
$messages->add('notice', 'Retry scheduled for 10 minutes.');

return back()->with('messages', $messages);

Because it's MessageProvider-shaped, it slots into Laravel's error-rendering path without a conversion layer. If you need different key names, wrap it (pattern 5) rather than fork it.

3. Register the in-memory registry as a singleton for request-scoped sharing. The registry is for data that needs to be readable from several places within one request without threading arguments through:

// In a service provider
$this->app->singleton('acme.registry', fn () => new Memory());

// Anywhere afterwards
app('acme.registry')->put('tenant', $tenant);
app('acme.registry')->get('tenant');

Namespace your keys (billing.gateway, tenant.id). An unnamespaced shared registry across many packages is how you get a collision at 6pm on a Friday. And if a worker or Octane process serves multiple requests, reset in a terminate() handler or middleware — a singleton registry is exactly the kind of long-lived state that leaks between requests.

4. Prefer Illuminate\Support for generic work; use Orchestra helpers only where they encode a convention. Str::slug, Str::studly, Arr::get, Arr::wrap, Collection — battle-tested and universally understood. Reach for the Orchestra equivalents only when they add a convention (an Orchestra-specific naming scheme, a package-name transform, a config-key derivation), not a synonym. If you can't articulate the difference in one sentence, use the Laravel one.

5. Wrap everything you actually call. A thin internal facade is the single most valuable thing you can build on adoption day:

namespace Acme\Support;

class Notices
{
    public static function make(): \Orchestra\Support\Messages
    {
        return new \Orchestra\Support\Messages();
    }
}

Call sites reference Acme\Support\Notices, not the vendor class. When v8 renames something — or the package is abandoned — you fix one file instead of grepping the estate. This also gives you a free seam for tests.

6. Test with the real thing, not mocks. Any package extending the provider base should be exercised through orchestra/testbench, which registers the Orchestra environment you actually ship into. A mock of a service provider proves nothing.

7. Sequence version bumps as two PRs. When the next major lands: framework upgrade first (lockfile-only), package bump second (lockfile-only), each behind normal CI. Never combined — you want a regression to be unambiguously attributable.

Gotchas and Tips

Version floor is the whole story of v7. The only documented v7 change is Laravel 9+. That means the real estimate is your Laravel migration; the package bump is a constraint change plus a regression pass. Don't let a ticket called "upgrade orchestra/support" absorb framework work — and never push the package ahead of the framework. On Laravel 8 you'd pin 6.x and carry a dated remediation ticket.

Expect the v6 → v7 diff to be under-documented. A one-line changelog for a major version is a contract reset with no paper trail. Read the source diff yourself and look specifically for renamed classes, changed method signatures, and facade-alias changes. Those are the failures that cost days, and they won't be in the release notes.

Resolve Composer conflicts empirically. Don't reason from the changelog. When a repo refuses the bump:

composer why-not orchestra/support ^7.0

The usual cause is the transitive intersection of illuminate/* ranges in apps that pin framework components individually.

Namespace collision with Illuminate\Support. Both ecosystems expose Str, Arr, and provider bases. Two rules prevent 90% of the confusion:

use Orchestra\Support\Str as OStr;      // alias at the top of the file
use Illuminate\Support\Str;

and: never let a single class use both vocabularies. If a file imports both, that file is doing two jobs.

Facades and aliases need registration. If you rely on the package's facades, confirm the alias is registered in your own package provider (or import the FQCN). An alias that works in a Testbench test and fails in production is almost always a provider loaded only in the dev environment — usually testbench pulling the package in as require-dev.

Confine transitive dev dependencies. If composer why shows it arrives only via testbench, pin it in require-dev and keep it out of the production autoload path. Removing a foundational dependency nobody calls is a net risk reduction and takes ten minutes.

Clear caches after provider changes. Provider and facade changes hide behind compiled manifests:

php artisan config:clear && php artisan route:clear && php artisan package:discover

Put these in the deploy checklist when you land a provider change, or you'll debug a cached alias.

A singleton registry in a queue worker or Octane is a bug waiting to happen. In-memory sharing is per-process. Reset in terminate(), or scope the registry per request. This is the single most likely production incident from this package.

Where to extend safely. The provider base class and traits are the intended extension points — subclass and override; don't patch vendor/. Extend the message collection by composition (hold one, add your own formatting) rather than overriding internals, because the internals are undocumented and unstable across majors.

Bus factor is the standing risk. No stars, no listed dependents, one effective maintainer. Mitigations, in order of cost:

1. Name an internal owner who watches upstream releases — unowned dependencies become debt silently.
2. Wrap the API (pattern 5) so replacement is one file.
3. Treat its Laravel support ceiling as a line item in the platform roadmap, because a foundational package that stalls on the next Laravel major freezes every dependent package simultaneously — highest impact, lowest visibility.
4. Keep it off customer-critical paths, and price the fork-or-replace option before you need it.