Learn Monorepo Common Laravel Package

Getting Started

• Install into a sub-package via a path repository. Inside the monorepo, learn-monorepo-common is normally consumed by sibling packages with a "repositories": [{ "type": "path", "url": "../common" }] entry and a "require": { "feryardiant/learn-monorepo-common": "*" } constraint. Composer symlinks the package, so edits in common/src are immediately visible to consumers without re-publishing.
• Look here first: composer.json (namespace, autoload, extra.laravel provider registration), src/ for the shared classes/traits, config/ for anything publishable, tests/Pest.php (new in v0.0.6) for the test bootstrap contract, and .github/workflows/ for the per-sub-package release automation added in this release.
• First use case: run ./vendor/bin/pest in the package root to confirm the Pest bootstrap works, then add a single test that uses the common test helpers (uses(TestCase::class)->in('Feature') style) before wiring the package into a real sub-package. Because v0.0.6 is infrastructure-only (Pest init + release automation), there is no runtime API change to learn — validate the workflow first, then start pulling shared helpers into your own packages.

Implementation Patterns

• Shared code, consumed not copied. Keep cross-cutting concerns (base test case, shared traits, helper functions, common config) in common and require it from each sub-package. When you are tempted to paste a helper into a second package, that is the signal to promote it here.
• Pest bootstrap reuse. Point each sub-package's tests/Pest.php at the common base test case and expectation set rather than duplicating uses(...) blocks. The typical shape is one uses(CommonTestCase::class)->in('Feature', 'Unit') plus package-specific in() overrides where behavior differs.
• Service provider auto-discovery. If the package registers a provider through extra.laravel.providers, consumers get it for free. For anything optional (config, migrations, commands), expose it via publishes() / mergeConfigFrom() and let the consumer opt in with vendor:publish --tag=....
• Commit scoping drives releases. With per-sub-package release automation in place, commits touching a sub-package's directory are what generate that package's tag/changelog. Write commit messages with the package name in scope (feat(common): ..., fix(http-client): ...) so the automation attributes changes correctly.
• Pin versions deliberately in the monorepo. * constraints are fine while everything is symlinked, but as soon as you tag a release, switch consumers to ^0.x so an accidental breaking change in common fails loudly at composer update instead of silently at runtime.
• Integration tip: run Pest at the monorepo root (or per package in CI matrix) so a change in common re-runs every consumer's suite — that is the main safety net the symlinked path repository gives you.

Gotchas and Tips

• Symlinks and Composer cache. After pulling changes to common, composer update feryardiant/learn-monorepo-common (or delete vendor/ in the consumer) if classes appear stale. Autoload classmaps are the usual culprit; composer dump-autoload fixes most "class not found" surprises.
• Pest scope leakage. uses() and in() are directory- and namespace-scoped. If a shared bootstrap lives in common/tests, the consumer's Pest.php must explicitly require or uses() it — Pest will not discover a sibling package's test bootstrap automatically. Symptom: helper functions undefined only when running from the consumer root.
• Release automation needs clean boundaries. A commit that touches two sub-packages plus common can produce ambiguous or duplicate releases. Split such commits, or accept that the automation will tag the first matching package — check the workflow file to see whether it keys off paths, tags, or commit scopes before trusting it.
• Don't over-share in common. Anything with package-specific config (routes, policies, model bindings) belongs in the consuming package; common should stay dependency-light or you create a diamond where every package inherits every other package's requirements.
• Config caching bites in production. Providers using mergeConfigFrom() are fine, but code reading config() at boot time will freeze values under config:cache. Read config inside handlers/resolvers, not in the provider constructor.
• Extension points worth using: Pest custom expectations (expect()->extend(...)) registered in the shared bootstrap, and macros/traits on the common base test case. Both give consumers leverage without forking common. Keep them additive and documented in the package README — the release automation only logs commit subjects, so undocumented helpers effectively don't exist for new team members.