Data Grid Laravel Package

Getting Started

The package is installed with Composer and, like most Laravel packages, relies on package auto-discovery to register its service provider and facade:

composer require <vendor>/<package>:^7.1

Start by confirming the installed version and the PHP constraint it declares:

composer show <vendor>/<package>
composer why-not <vendor>/<package> 7.1.*

v7.1.0 is the first release with an explicit PHP 8 constraint, so if your application runs on PHP 8 this is effectively your floor — anything below 7.1.0 will either fail the platform check outright or install with --ignore-platform-reqs and then break at runtime on signature mismatches. Do not work around the constraint; upgrade the package.

First use case, in order:

1. Publish the package assets (config, migrations, views) if the package ships them:

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

2. Skim config/<package>.php — this is where the majority of day-to-day behaviour is toggled, and it is the file you will return to most often.
3. Run the package's own migration/install command if one is documented, then exercise the smallest possible happy path (a single facade call, a single dispatched job) before wiring it into a real feature.

Where to look first when reading the source: the registered service provider (what it binds and merges), the facade's getFacadeAccessor() (the concrete class you actually call through), and the config file. Those three files tell you 80% of how the package behaves.

Implementation Patterns

Resolve from the container, not from new. Bind the package's contract in a service provider or accept it via constructor injection so tests can swap it for a fake. Facades are fine in controllers and Blade; prefer injection in services, jobs, and listeners.

Wrap the package behind a thin adapter. Even a one-method wrapper class (App\Support\Thing delegating to the package) pays off at upgrade time — when a major version renames a method, you change one file instead of grepping the codebase. This matters more than usual here: a major-version bump from 6.x to 7.x is the kind of release where public signatures move.

Pin the version range you test against. Use "^7.1" rather than "*", and commit composer.lock in the application (not in libraries). Since PHP 8 support landed in a minor release, treat 7.1.0 as a hard minimum in composer.json rather than relying on transitive resolution.

Run a matrix in CI. Add PHP 8.0/8.1/8.2 to the pipeline alongside whatever 7.x versions you still support, and assert the package version in a test so a silent downgrade fails loudly.

Use the package's extension points rather than patching. Most Laravel packages expose config-driven class names (custom drivers, custom handlers, custom formatters). Override by pointing the config key at your own class, and register any additional bindings in your AppServiceProvider — that survives package upgrades; editing vendor/ does not.

Queue and transaction boundaries. If the package dispatches events or jobs, wrap the calling code in DB::transaction() only when the package documents afterCommit behaviour; otherwise you can fire jobs that read uncommitted data. Default to dispatching after the transaction commits.

Gotchas and Tips

• composer update is not enough on its own. Laravel caches the compiled container and config. After upgrading, run php artisan config:clear && php artisan cache:clear (or optimize:clear) before debugging phantom behaviour.
• PHP 8 is a platform requirement, not an opt-in. If CI installs with --ignore-platform-reqs, you'll get green builds that fatal in production with Error: Undefined method or argument-count mismatches. Remove that flag.
• Named arguments are a real upgrade hazard. Any positional call into package methods breaks if the package renames a parameter in a later minor. Call package APIs positionally in your own code so the blast radius stays inside your adapter.
• Strict types and nullability. PHP 8 makes coercions stricter in places. If you were relying on an implicit null or string-to-int cast flowing into a package method, an upgraded signature may now throw TypeError instead of silently coercing. Search for calls that pass null where a scalar is expected.
• Deprecation noise. Running on PHP 8.1+ surfaces ReturnTypeWillChange-style deprecations from packages only claiming PHP 8.0 support. They're warnings, not failures — but they mask real errors in logs. Filter by channel rather than suppressing globally.
• Config caching and closures. If you point any package config key at a closure, php artisan config:cache will break it. Use invokable class names instead.
• Auto-discovery can be disabled. If composer.json has "dont-discover", the provider won't register and you'll get "target class does not exist" with no obvious cause. Check bootstrap/providers.php / config/app.php in that case.
• Debugging tip: when a package call misbehaves, app()->bound('<accessor>') and get_class(app('<accessor>')) in tinker confirms which concrete implementation you're actually hitting — often a cached one, or a stub bound by a test service provider.
• Extension points to prefer: config-driven class overrides, published migrations you can edit, and package events you can listen to. Avoid extending internal classes — those are the first to change across majors.