Laravel Mayar Laravel Package

Getting Started

• Install the 0.x release explicitly. Because this is the first public cut, pin it in composer.json ("vendor/package": "^0.1") rather than relying on a floating constraint. There is no prior stable line to fall back to, so the constraint you write now is your only protection against a surprise v0.2.0 break.
• Read these four things before writing any code, in this order:
  1. composer.json — the real package name, required PHP/Laravel versions, and autoload/extra.laravel entries (the latter tells you whether the service provider and facade are auto-discovered or must be registered manually).
  2. README.md — the documented "getting started" path. Treat this as the intended happy path, not as a complete API reference.
  3. config/ (if present) — every key you can publish is a knob you will eventually need; read them all once up front.
  4. src/ and tests/ — for a v0.1.0, the test suite is the most reliable specification of actual behaviour, since the prose docs are explicitly labelled as early/incomplete.
• Publish config and diff it into version control before your first commit that uses the package:

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

  Commit the published file so config drift between environments is visible in review.
• First use case: pick a single, low-blast-radius integration point — one controller, one Artisan command, or one queued job — and wire the package in there only. Resist wiring it into a shared base class or a global middleware until you have run it against real data. On an initial 0.x release you want the failure surface to be one call site, not the whole app.
• Get a smoke test in place on day one. A feature test that boots the provider, resolves the package's main entry point from the container, and asserts one round-trip is worth more than any amount of README reading. It becomes your canary when you bump to v0.2.0.

Implementation Patterns

• Resolve from the container; do not new things up. The package ships "basic configuration and setup," which in Laravel terms almost always means a singleton bound in the service provider. Inject the interface or concrete class into constructors and let the container supply the configured instance. This is also what makes the package swappable in tests.
• Keep configuration in config/ and secrets in .env. Read package settings through config('package.key') at the point of use, not at class-construction time, so that config:cache and per-environment overrides behave. If the package reads env() directly in its own source, that is a bug you should report — it breaks under php artisan config:cache.
• Wrap the package behind a thin application-level abstraction. Even at v0.1.0, define your own small interface (e.g. App\\Contracts\\SomethingClient) with one adapter that delegates to the package. Given the release note's explicit warning that "APIs and behavior may change," this adapter is the difference between a one-file upgrade and a codebase-wide search-and-replace at v1.0.0.
• Test against a fake, not the real dependency. Bind a stub implementation of your abstraction in the test container. Reserve one or two integration tests that hit the real package, tagged (e.g. @group integration) so CI can run them separately from the fast suite.
• Watch for publishable assets beyond config. Migration stubs, views, translations, or JS/CSS are common in Laravel packages. Run php artisan vendor:publish interactively once to see the full tag list, then script the specific --tag= calls you actually need in your deploy pipeline rather than publishing everything.
• If the package registers routes, middleware, or scheduled tasks, confirm this in the provider's boot() method and document the resulting URL prefixes and middleware groups in your own repo's README. These are the things that surprise people in staging.
• Pin the version in CI and in production, and let a separate scheduled job test ^0.2 once it exists. That gives you early warning of breakage without exposing production to it.

Gotchas and Tips

• 0.x semver is not stable semver. Under semver, anything in 0.x may break in a minor bump. Treat every v0.2.0, v0.3.0, etc. as a potential breaking change and read its release notes in full before bumping. Never use * or dev-main in a project you intend to maintain.
• The v0.1.0 notes are placeholders, not documentation. They describe "initial implementation of core functionality" without naming a single feature, class, config key, or endpoint. There is no changelog delta to assess, no deprecations (there cannot be, on a first release), and no upgrade path to plan. The practical consequence: budget time to read the source. Do not estimate this package's integration cost from its README.
• No upgrade guide exists yet. Because v0.1.0 is the first release, there is nothing to compare against. Start your own docs/upgrades.md in your repo now, recording the exact version you integrated and every assumption you made. When v0.2.0 lands, that note is your diff baseline.
• Missing/ambiguous signals to chase down before committing:
  • No stated minimum PHP or Laravel version in the notes — check composer.json and confirm it matches your app, especially if you are on the newest Laravel major.
  • Auto-discovery unclear — verify extra.laravel.providers and extra.laravel.aliases exist; if not, register manually in config/app.php (or bootstrap/providers.php on Laravel 11+).
  • No mention of a facade — if one ships, prefer constructor injection anyway; facades are convenient but harder to fake precisely in tests.
• Debugging approach: if behaviour differs from the README, dd() the resolved config array (config('package')) and the container binding (app()->make(...)) first. On an early release, the most common causes are unpublished config (defaults applied silently instead of yours) and a stale config cache — run php artisan config:clear before you start bisecting your own code.
• Extension points to probe deliberately: does the provider bind interfaces (swappable), publish contract stubs (overridable), or fire events (observable)? Each of these is a legitimate place to hook in without forking. If none exist, that is the single most valuable piece of feedback to send upstream — the notes explicitly invite it, and it is the kind of request that actually lands in v0.2.0.
• Feedback timing: the maintainer has flagged feedback as an input to v0.2.0/v1.0.0. If the package's API shape is wrong for your use case, raise it now, while breaking changes are still cheap and expected — after v1.0.0 the same request becomes a major-version negotiation.