Laravel Pagerender Laravel Package

Getting Started

1.0.0 is the first stable release, which means the maintainers are now committing to semver — this is the right moment to adopt, and the right moment to pin. Start by reading composer.json in the package before anything else: check the illuminate/support / laravel/framework constraint to confirm it supports your Laravel version, and check extra.laravel.providers to see whether the service provider is auto-discovered (most are — you should not need to edit config/app.php).

composer require vendor/package:"^1.0"
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"

Where to look first, in order:

• README quickstart — for a 1.0 release this is the contract. Treat it as the API surface until proven otherwise.
• The package's config/ file — comments usually document every option and the defaults are the sane ones.
• The service provider — the register()/boot() methods tell you what is bound into the container, which is the real entry point for everything else.
• tests/ — the highest-signal documentation of intended usage, especially for edge cases the README skips.

First use case: prove one end-to-end happy path in isolation before touching application code. In php artisan tinker, resolve the main class from the container and call a read-only method:

app(Vendor\Package\Client::class);   // does it resolve?
config('package.key');               // is config loaded?

If both work, wire a single scratch route or command next. Do not integrate it across the codebase until one path is green.

Caveat: this assessment is built from the 1.0.0 release announcement, not from an enumerated API. Verify class names, config keys, and publish tags against the README and composer.json before committing to a design.

Implementation Patterns

Resolve from the container, never new. Constructor-inject the package's main class (or app(...) where injection isn't possible). Direct instantiation bypasses config, bypasses any singleton binding, and makes the class un-mockable in tests. This one habit determines whether the package is testable at all.

Wrap it in your own thin interface. Bind a small app-level contract in a dedicated service provider and have the package call sit behind it:

$this->app->bind(Notifications::class, PackageNotifications::class);

Costs an hour; buys you the ability to swap implementations on a major upgrade without touching call sites.

Keep configuration environment-driven. Values go in .env, referenced from config/, consumed by the package. Never edit the vendor copy. Remember php artisan config:cache freezes everything — re-run it after any .env change, and add it to your deploy script if it isn't there.

Handle background work deliberately. If the package dispatches jobs, give it a named queue and connection rather than the default, so a slow third-party call can't starve your critical queue. Ensure php artisan queue:restart runs on every deploy — workers hold old code in memory and will fail on renamed classes after an upgrade.

Test at the boundary. Use the package's own fakes if it ships them. Otherwise bind a mock of your interface in a test service provider, and lean on Http::fake() / Bus::fake() / Queue::fake() to intercept whatever the package sends outward. Assert on the outbound call, not on internal package state.

Debug against a checkout, not a tag. When something is ambiguous, add a path repository pointing at a local clone and read the source directly — faster than a guess/edit/tag cycle:

"repositories": [{ "type": "path", "url": "../package" }]

Version policy. Applications: pin ^1.0 and commit composer.lock. Libraries: let patch and minor float, and read the changelog on every bump.

Ship behind a flag. First integration goes in behind a config-driven feature flag. If 1.0.0 turns out to have a rough edge in production, you disable it without a redeploy.

Gotchas and Tips

• Published config drifts. A config key added in a 1.1 release will not appear in your published copy, and the package may fall back to a default you didn't expect. After each upgrade, re-publish to a temp directory and diff: php artisan vendor:publish --provider="..." --force --tag=config into a scratch copy first.
• 1.0.0 is a promise, not a guarantee. Packages that spent a long time in 0.x often still ship behavioral changes in minor releases during the first year of stability. Your defence is a test suite pinned to the integration surface — the outbound calls and the values you read back — not to internal details.
• Auto-discovery cache staleness. package:discover runs on composer install. If a class is suddenly "not found" after a deploy, delete bootstrap/cache/packages.php and bootstrap/cache/services.php before debugging anything else.
• Don't Facade::shouldReceive(). Mock the underlying container binding instead. Facade mocking couples your tests to an accessor name that is among the first things to change in a major version.
• Publish migrations rather than running vendor ones. If the package ships migrations, publish them into database/migrations so you control ordering relative to your own schema and can roll back predictably.
• Debugging checklist, in order: php artisan about (shows whether config is cached) → php artisan tinker with app()->bound(...) / app()->make(...) to inspect bindings → config('...') returning null almost always means a stale config cache or a typo'd key.
• Prefer the sanctioned extension points — published config, container bindings that override defaults, published views and components. Subclassing a package class is the last resort: it is the single most common source of breakage across a major upgrade.
• Write a short decision record — why this package, the pinned constraint, the interface you wrapped it in, and the one or two things you'd need to verify to replace it. When 2.0 lands, that note turns a day of archaeology into a ten-minute assessment.