Laravel Populated Factory Laravel Package

Getting Started

Version 1.1.0 adds PHP 8 support, so the install floor is now php: ^8.0 alongside your Laravel version constraint. Start by confirming your environment matches before touching the package:

php -v                     # must be >= 8.0
composer why-not vendor/package 1.1.0   # surfaces the blocking constraint
composer require vendor/package:^1.1

If you are upgrading from 1.0.x on PHP 7.4, treat this as a runtime migration, not a feature upgrade — see the gotchas below before rolling to production.

Where to look first, in this order:

1. CHANGELOG.md / release diff — "PHP 8 support" usually ships alongside signature changes (union types, promoted constructors, mixed/static return types). Read the diff even when the notes are terse.
2. The package service provider — confirm what is still auto-discovered and whether new bindings were registered.
3. config/*.php after php artisan vendor:publish --tag=config — diff it against your published copy; new keys defaulting to null will silently disable behaviour.
4. The facade / entry class — this is where named arguments and union types land first, and where your IDE will fail to resolve if the stubs are stale.

First use case worth wiring: resolve the package's main class from the container in a small artisan command or Tinker session and exercise one happy path. This proves autoloading, config resolution, and any facade alias registration in a single step before you build anything real on top of it.

php artisan tinker
>>> app(Vendor\Package\Client::class);

Implementation Patterns

Constructor injection over facades. With PHP 8 promoted constructors the package's collaborators are cheap to compose. Inject the concrete class into your own services and keep facades for controllers/blade only — it makes the dependency swappable in tests and keeps you off static state.

final class SyncOrders
{
    public function __construct(private Vendor\Package\Client $client) {}

    public function __invoke(Order $order): void
    {
        $this->client->push($order->toPayload());
    }
}

Bind a configured singleton. Most Laravel packages register a default binding that reads from config(). If you need per-tenant credentials, rebind in your own provider rather than mutating config at runtime — runtime config()->set() breaks under config:cache.

$this->app->singleton(Vendor\Package\Client::class, fn ($app) => new Vendor\Package\Client(
    token: $app['config']->get('services.vendor.token'),
));

Use named arguments at the boundary, positional inside. The PHP 8 win is readability on package calls with long optional parameter lists. Do it in your application code, but avoid it in code you ship as a library — parameter renames in a patch release become instant breakage.

Wrap package calls behind a thin adapter if the API surface is wide. You get a single seam to test against, and a single file to touch when the package ships a 2.0. This is worth it the moment you find yourself mocking three package classes in one test.

Queue and event integration. Push package calls to jobs so slow HTTP/IO does not sit in the request cycle; add $tries/backoff and make the job idempotent via a package-side unique key, not just a Laravel ShouldBeUnique lock. If the package dispatches events, prefer listening to them over polling for state changes.

Testing. Use the package's fake/swap hook where offered; otherwise bind a mock through the container in setUp(). Turn on Http::preventStrayRequests() so an unmocked package call fails loudly rather than hitting a sandbox.

Gotchas and Tips

"PHP 8 support" often means PHP 7 support is gone. Check composer.json for "php": "^8.0" versus ">=7.3". If 7.x was dropped, this is a breaking change disguised as a minor bump — your CI matrix, Docker base image, and any downstream consumers all need updating before composer update runs.

Union and return types break mocks. If 1.1.0 tightened signatures (string|int instead of untyped, or added : void), hand-rolled test doubles and PHPUnit getMockBuilder()->setMethods() stubs will fatal. Regenerate mocks or move to Mockery::mock() against the interface.

Named arguments are not covered by semver. The package author is free to rename a parameter in a patch release; that silently invalidates foo(limit: 10) with an Unknown named parameter error at runtime, not at static-analysis time. Pin the version and let Renovate/Dependabot surface the diff.

PHP 8 deprecation noise. Running 1.1.0 on 8.1/8.2 will emit E_DEPRECATED for implicit nullable parameters and dynamic properties. Don't let that mask a real error — set error_reporting(E_ALL & ~E_DEPRECATED) in the package's test suite only, not application-wide.

Nullsafe operator hides the failure you need to see. $result?->value() returning null because the package returned null is indistinguishable from a missing config key. Log at the call site before chaining.

Config cache is the #1 cause of "works locally, dead in prod." Any runtime config()->set(), env() call outside config/, or conditional binding must move into a config file. After every config change: php artisan config:clear locally, config:cache in the deploy pipeline.

Stale IDE stubs after a signature change. Regenerate with composer dump-autoload and restart the language server; phantom "undefined method" warnings after a package bump are almost always cached reflections, not real breakage.

Debugging order when behaviour changes post-upgrade: (1) php -v on the actual runtime, including FPM vs CLI — they frequently differ; (2) composer show vendor/package to confirm what is really installed; (3) php artisan about for cached vs live config divergence; (4) diff your published config against the new stub.

Extension points to check before forking. Look for a published interface, an abstract base class, or a Macroable trait on the main class — most Laravel packages expose one. Extending beats vendoring, and it survives the next minor release.