Ds Laravel Package

Getting Started

mahdimajidzadeh/majid-ds is still pre-1.0 (v0.4.0), so treat the public API as provisional and pin it exactly rather than relying on ^0.4.

1. Install and pin

   composer require mahdimajidzadeh/majid-ds:0.4.0
   

   Commit composer.lock. Avoid ^0.4 in composer.json until you have read the diff between releases — 0.x minor bumps are where breaking changes land here.
2. Where to look first — in this order:
   • README.md for the intended entry point (facade vs. injected service vs. trait).
   • src/ for the service provider and any Contracts/ directory — the contracts, not the concrete classes, are what you should type-hint against.
   • config/ for anything publishable. If a config file exists, run php artisan vendor:publish --provider="...ServiceProvider" and read every key before changing one.
   • tests/ for the maintainer's own usage examples — usually more accurate than the README at this stage.
3. First use case — pick the smallest, most isolated thing the package does and wire it into a single Artisan command or a test, not into a controller. Getting one happy-path call working in php artisan tinker confirms autoloading, the provider registration, and config defaults before you commit to an integration shape.

If the README does not clearly state what problem the package solves for you, stop and evaluate whether a first-party Laravel feature (collections, Illuminate\Support\*, queues) already covers it. At v0.4.0 the cost of adopting an unstable dependency should be justified by real functionality, not convenience.

Implementation Patterns

Wrap it, don't spray it. Because the API can change under you in a 0.x minor release, put the package behind one class of your own:

final class ThingAdapter
{
    public function __construct(private readonly PackageService $service) {}

    public function doTheThing(array $input): Result
    {
        return $this->service->handle($input);
    }
}

Bind it in a dedicated service provider and type-hint ThingAdapter everywhere else. When v0.5.0 renames a method, you edit one file.

Resolve from the container, not with new. If the package ships a facade, prefer constructor injection of the underlying contract — facades are convenient in prototypes but make tests brittle and hide the dependency during code review.

Keep package types out of your domain and HTTP layers. Translate to and from your own DTOs at the adapter boundary. This is what makes the package replaceable and keeps composer update from turning into a refactor.

Test against the contract, not the implementation. If a Contracts/ interface exists, write one test suite against it and run it for both the package's implementation and, later, any replacement. Use RefreshDatabase only if the package actually persists; many utility-style packages do not, in which case a plain unit test is faster and less coupled.

Integration points worth checking before you commit:

• Queue workers — if the package does anything long-running, confirm it is serialisable (SerializesModels compatibility) before dispatching it in a job.
• Console commands — good for backfills and one-off operations, and an easy place to roll out a new integration incrementally.
• Scheduled tasks — if the feature is a recurring operation, prefer a thin scheduled command that calls your adapter over embedding package calls in Kernel::schedule().

Keep a short integration note in the repo (a paragraph in the README or a docs/ file) recording which version you pinned, which class is the adapter, and what the exit plan looks like. At 0.x this is the cheapest insurance you can buy.

Gotchas and Tips

• The v0.4.0 changelog is a bare compare link. There are no release notes, so the only source of truth is the diff: https://github.com/MahdiMajidzadeh/majid-ds/compare/v0.3.1...v0.4.0. Read it, specifically looking at src/ signature changes, removed methods, and any composer.json constraint bumps. Do this before bumping, not after CI goes red.
• 0.x semver has no stability guarantee. Minor version bumps legitimately contain breaking changes. Pin exactly, upgrade deliberately, and never let Dependabot auto-merge this dependency.
• Check PHP and Laravel constraints in the diff. Framework version bumps are the most common cause of "the update broke everything" in 0.x packages — often the real change is a dropped Laravel version support.
• Config caching. If you publish a config file, php artisan config:cache will freeze it. Run php artisan config:clear when debugging unexpected default behaviour, and never call config() at runtime inside a class that could be constructed before the cache is warm.
• Provider discovery. Laravel's package auto-discovery can silently stop working after a namespace change. If classes are suddenly "not found" after composer update, check php artisan about or bootstrap/cache/packages.php.
• Debugging a misbehaving call: start with dd() inside your adapter, not inside vendor/. If you must instrument the package, use php artisan tinker plus a temporary ray()/dump() in vendor/, and remember that edit disappears on the next composer install — never rely on a vendor/ patch.
• Extension points to prefer: contracts/interfaces, published config, and container bindings. Avoid subclassing concrete package classes — that couples you to internal structure, which is exactly what will move in v0.5.
• Serialisation. Anything you store on a queue, in a cache, or in a session must survive a package upgrade. If a package object ends up in a payload, flatten it to scalars/arrays at the boundary.
• Exit cost. Before going deep, confirm you can answer: what would replacing this take? If the answer is "a lot", wrap it harder or don't adopt it yet at 0.x.