Laravel News Laravel Package

Getting Started

v1.3.0 is the release that adds Laravel 5.3 support, so this is the first version to target if your application is on 5.3. Start by confirming compatibility before anything else:

composer require vendor/package:^1.3

Check the package's composer.json for its illuminate/* constraints — that, not the changelog, is the authoritative statement of what "5.3 support" means in practice (5.3.x only, or ^5.3 spanning later releases too).

Where to look first, in order:

1. The changelog/diff between 1.2.x and 1.3.0. The release note is a single line, so there is no migration guide. Diff the tag (git diff 1.2.0..1.3.0) to see whether "support" meant constraint loosening only or actual code changes for 5.3 APIs.
2. The package service provider — everything it binds, registers, and publishes is your public surface.
3. The published config file, which lists the extension points you are expected to tune.

First use case: register the provider and facade manually (see Gotchas — 5.3 has no auto-discovery), publish the config, and resolve the package once from the container in php artisan tinker to confirm it constructs cleanly against 5.3's container.

If you are still on 5.2, stay on the 1.2.x line; there is no reason to take a framework-compatibility bump you cannot exercise.

Implementation Patterns

Manual registration. In config/app.php, add the service provider to providers and, if the package ships one, the facade to aliases. Publish config and any migrations/views in one pass:

php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider"
php artisan migrate

Prefer constructor injection over the facade. Resolve the package's contract or concrete class in your controller/job constructor so tests can substitute it. Facades are convenient in Blade and quick scripts, but they couple you to a global container state that is easy to lose in queued jobs and Artisan commands.

Configure per environment. Set package keys in config/package.php with env() defaults, then override narrowly in AppServiceProvider::boot() only where you need runtime values (tenant IDs, per-user limits). Keeping runtime overrides in one place makes it obvious what differs from the published defaults.

Test by swapping the binding. Where the package talks to an external service, rebind in setUp():

$this->app->instance(PackageContract::class, new FakeClient());

Use DatabaseTransactions for anything touching a published migration so tests stay fast on 5.3's default tooling.

Version-guard shared code. If one codebase spans 5.3 and later, guard divergent calls with version_compare(app()->version(), '5.4.0', '<') rather than duplicating the integration.

Gotchas and Tips

• No package auto-discovery before 5.5. This is the single most common failure on 5.3: the package installs, but you get Target class [...] does not exist or a facade that resolves to nothing. The provider must be in config/app.php's providers array. The README may show a 5.5-style install for later versions — check the version-specific docs, not the top of the page.
• composer why-not is your first tool on constraint conflicts. If another dependency pins illuminate/support to ^5.4, Composer will silently keep you on 1.2.x and you will debug the wrong thing.
• Clear compiled state after registration changes: php artisan clear-compiled && composer dump-autoload. Stale bootstrap/cache/services.json-era artifacts and cached configs cause "I added the provider and nothing changed."
• Config caching breaks closures and env() calls outside config files. After php artisan config:cache, any env() inside a service provider returns null. Move those reads into config/.
• vendor:publish --force overwrites your edits. Diff published config before re-publishing on upgrade; treat the published file as yours, not the package's.
• Web middleware is not implicit. In 5.3, routes you register from a package provider only get sessions/CSRF if you wrap them in the web group. Missing session data is usually this.
• Debugging resolution: app(PackageContract::class) in tinker, then dump() the binding in the provider's register() to confirm ordering relative to your own providers.
• Extension points to reach for before forking: interface bindings in the provider, package events, publishable views/lang for presentation changes, and config([...]) set before first resolution for behavioural tweaks. Forking should be the last resort, and if you do, pin the fork explicitly.
• Pin with a caret and commit the lock file. ^1.3 accepts future 1.x releases whose Laravel constraints may drift; the lock file is what actually protects you.