Media Laravel Package

Getting Started

Because this release is version-aligned with the framework (v7.0.0 = "first release for Laravel 7"), treat the package major version as a hard contract: ^7.0 belongs on Laravel 7, and nothing else. Start by confirming the environment matches Laravel 7's floor — PHP 7.2.5+, Composer 1.10+/2.x, and a Laravel 7 skeleton (laravel/framework: ^7.0). Installing into a Laravel 8+ app is not supported by this major and will usually fail at the Composer constraint level before it fails at runtime.

Minimal path:

composer require <vendor>/<package>:^7.0
php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
php artisan migrate   # only if the package ships migrations

Where to look first, in order:

1. composer.json → extra.laravel.providers / extra.laravel.aliases. Laravel 7 uses package auto-discovery, so the service provider and facades should register without touching config/app.php. If auto-discovery is disabled in the host app ("extra": {"laravel": {"dont-discover": [...]}}), you must register manually.
2. config/<package>.php after publishing — this is the real API surface for most Laravel packages. Read it top to bottom before writing code; most "how do I…" questions are answered by a key in this file.
3. The service provider's register()/boot() methods — reveals container bindings, singletons, and what is deferred. This tells you whether you can resolve the package from the container in your own code.
4. The package's UPGRADE/CHANGELOG — since this major tracks a framework major, the diff from the previous Laravel 6 line is where the breaking changes live.

First meaningful use case: get one end-to-end call working against a real model/route before customising config. Publish config, run the default migration, hit the package's default facade call, confirm the result, then start changing config values. Debugging a package through a heavily customised config on day one is the most common way to lose an afternoon.

Implementation Patterns

Pin to the framework major, and upgrade them together. The v7.0.0 naming convention signals that the package will not maintain backward compatibility across a Laravel major bump. Model this in composer.json with a caret constraint (^7.0) and budget the package major bump as part of every Laravel upgrade task, not as an afterthought.

Container-first integration. Resolve the package from the container rather than instantiating it, so your tests can swap it:

// app/Http/Controllers/ReportController.php
public function __invoke(ReportGenerator $generator) // resolved from the package binding
{
    return $generator->forPeriod(now()->subWeek(), now())->toArray();
}

Where the package exposes only a facade, alias it in config/app.php and inject the underlying contract in your own classes so the dependency stays visible.

Config over code. Drive behaviour from config/<package>.php plus env() values, and keep a committed .env.example. Config keys are the stable extension point; internal classes are not. Wrap env reads in the package's published config rather than scattering env() calls through app code — env() returns null once php artisan config:cache has run outside the config files.

Middleware registration (Laravel 7 style). Laravel 7 still uses the HTTP Kernel, so package middleware goes in app/Http/Kernel.php:

• global → $middleware
• grouped → $middlewareGroups['web'|'api']
• named → $routeMiddleware (note: $middlewareAliases did not exist until Laravel 10)

If the package ships middleware, register it as an alias and attach it per-route rather than globally — global middleware ordering bugs are painful to unwind.

Blade component tags. Laravel 7 introduced <x-…> tags. If the package ships views, prefer the component/anonymous-component syntax over @include so you inherit attribute and slot handling, and override the package's views by publishing to resources/views/vendor/<package>/.

Queues and events. Wrap package calls that touch external services in a job, and let the package's events (if published) own the side effects. In Laravel 7 you can use the Http facade for outbound calls; keep those calls inside your own job rather than letting a package perform blocking I/O on a request path you didn't expect.

Testing. Use RefreshDatabase with the package's migrations, and set package config per-test via config([...]) in setUp() rather than editing the published config file. If the package ships a fake or an in-memory driver, prefer it — real network calls in the suite are the single biggest source of flake.

Feature-flag the rollout. Since v7.0.0 is a first release for a new framework major, ship it behind a branch, run the full suite plus a smoke test of every package integration point, then merge. There is no v7.0.1 history to lean on yet.

Gotchas and Tips

Laravel 7 is end-of-life. Framework security fixes for Laravel 7 stopped in late 2021. A package whose newest line is "first release for Laravel 7" is effectively a legacy branch — usable for maintaining existing apps, not for new work. Confirm a Laravel 8+/9+ line exists before adopting, and treat ^7.0 as a bridge version you plan to leave.

The version number is the API contract. v7.0.0 is not "semver on its own merits"; the major tracks the framework. The jump to 7 almost certainly carries breaking changes from the Laravel 6-era release — renamed config keys, dropped facade aliases, changed method signatures, removed service provider bindings. Read the changelog before bumping; do not assume ^6 → ^7 is a drop-in.

Config and package caches will hide your changes. After publishing or editing config:

php artisan config:clear   # or config:cache for prod
php artisan package:discover
composer dump-autoload

A published config file that shadows an updated package default is a classic "why is my new setting ignored" trap — Laravel merges package defaults only where your published file doesn't already define the key. Diff your published config against the package's after every minor bump.

Auto-discovery fails silently in specific cases. A typo'd provider class name in extra.laravel.providers, or a host app with dont-discover, leaves you with a "class not found" or, worse, a facade that resolves to a null binding. Verify registration explicitly:

dd(app()->getLoadedProviders());   // is the service provider there?
dd(app()->bound(SomeContract::class));

Don't assume later-framework ergonomics. Things you'll reach for reflexively but that do not exist on Laravel 7: class-based model factories (User::factory() as a class — Laravel 7 uses the string/factory() helper form), php artisan about (Laravel 9), $middlewareAliases (Laravel 10), Sanctum (Laravel 7 shipped Airlock, renamed later), and schema dumping. Copying snippets from current docs is the fastest way to introduce a BadMethodCallException.

Laravel 7 renamed things. Sanctum/laravel/airlock, the Str::of() fluent string helpers, and Blade component tags all landed in this cycle — if the package's docs mix Laravel 6 and 7 idioms, trust the code, not the prose.

Extension points, in order of safety:

1. Published config — the sanctioned surface.
2. Published views/migrations — safe, but you own merge conflicts on upgrade.
3. Container rebinding — bind your own implementation to the package's contract after the package's provider registers (a later-registered app provider works; ordering matters).
4. Macros on the package's classes (Facade::macro(...)) — cheap and upgrade-friendly for small additions.
5. Subclassing package internals — last resort; these are the most likely to break on v7.x minors.

Debugging checklist for a misbehaving call: confirm the provider loaded → confirm the config key resolved to the value you expect (config('package.key')) → confirm you're not in a cached-config environment → confirm the facade root matches the binding → only then read package source. Nine times in ten the failure is step 2 or 3.

Log, don't guess, at the boundary. Wrap package calls that cross a process or network boundary in a try/catch that logs the package's own context (job id, model key, config snapshot). Because this is a first release on a new major, expect at least one edge case; the log is what turns a support thread into a patch.