Eloquent Lockable Laravel Package

Getting Started

v1.0.0 is an initial release with minimal release notes, so treat the source and README as the source of truth rather than the changelog. There is no migration path to plan for and no deprecations to work around — but also no documented feature list to trust.

First steps:

1. Install into a scratch Laravel app before touching your main project:

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

2. Check what was auto-registered. Laravel package discovery means a ServiceProvider (and often a Facade) is already active; run php artisan about and php artisan list to see whether new commands, bindings, or config keys appeared.
3. Look in this order: README.md → CHANGELOG.md → composer.json (require, extra.laravel) → src/*ServiceProvider.php (register() and boot()) → config/*.php. The service provider tells you more about real capabilities than the release notes do.
4. Publish config and any assets if the provider exposes them:

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

5. Run the package's own test suite locally (composer test or vendor/bin/phpunit) to confirm it's green on your PHP/Laravel versions.

First meaningful use case: pick the single smallest thing the package does — one command, one facade call, one Blade component — and wire it into a throwaway route or tinker session. Because this is a 1.0.0 with no prior assessment, your goal in the first hour is to establish what the package actually does and whether its supported Laravel/PHP matrix matches yours, not to integrate it deeply.

Implementation Patterns

Pin the version explicitly. For a brand-new 1.0.0, use ^1.0 in composer.json but commit composer.lock. Early minor releases in a fresh package are where the rough edges get sanded off.

Isolate the integration behind your own boundary. Wrap package calls in a small application-level service or interface rather than sprinkling facade calls through controllers. If v1.x turns out to be short-lived or gets replaced, you swap one class instead of grepping the codebase.

// app/Services/YourWrapper.php
final class YourWrapper
{
    public function __construct(private readonly PackageContract $package) {}

    public function handle(Input $input): Result
    {
        return $this->package->run($input);
    }
}

Bind configuration in a dedicated config file. Publish the package config into config/ and reference it via config('package.key') with env fallbacks, so per-environment differences (queue names, API endpoints, credentials) live in .env and not in vendor defaults.

Test-double via the container. If the provider registers a singleton or binds a contract, $this->swap() / $this->instance() in tests works cleanly. If it only exposes a facade with a hard-coded concrete class, that's a signal the package is hard to test around — worth noting before you build on it.

Queue and schedule integration. If it ships jobs or commands, run them through your normal scheduler and queue rather than calling synchronously from request handlers; new packages commonly default to sync behaviour that won't survive production load.

Feature-flag the rollout. Ship behind a config flag or Feature::active() so you can disable the integration in production without a deploy if v1.0.0 misbehaves.

Gotchas and Tips

• The release notes carry no information. "Initial version" tells you nothing about supported Laravel versions, PHP constraints, or intended scope. Read composer.json's require block and the package's CI matrix before assuming compatibility.
• Auto-discovery can surprise you. Check extra.laravel.providers and extra.laravel.aliases in the package's composer.json; a provider that boots migrations or publishes routes on install can change your app's behaviour without an explicit line in your code.
• Migrations from vendor packages should be reviewed before running php artisan migrate. Publish them (--tag=migrations) and inspect column types, indexes, and foreign keys — defaults chosen by a package author rarely match your schema conventions.
• Config caching traps. After publishing config, php artisan config:cache will freeze values; if behaviour changes unexpectedly between local and production, that's usually stale cached config. Use php artisan config:clear when debugging.
• No upgrade guide exists yet. Since this is the first release, treat every future 1.x bump as potentially breaking until the package establishes a changelog discipline. Watch for ## Changed and ## Removed sections in subsequent releases.
• Debugging hooks. Enable query logging (DB::listen) and check storage/logs/laravel.log first; new packages often log verbosely under a dedicated channel defined in their config. php artisan package:discover -v re-runs discovery and surfaces provider errors that fail silently at boot.
• Extension points to inspect early. Look for interfaces or abstract classes the package exposes (Contracts/), events it dispatches, and any Macroable traits — these are your sanctioned customisation surface. Anything you override by extending a concrete class is likely to break on a minor bump.
• Vendor lock-in risk. With zero release history, budget for the possibility that the package stalls. Keeping usage behind your own wrapper (see above) is the cheapest insurance.