Developer Experience Laravel Package

Getting Started

This package is a development-time foundation layer, not a runtime feature. Treat it as scaffolding + diagnostics you adopt once per project and then keep in require-dev.

1. Install as a dev dependency

composer require --dev liberusoftware/developer-experience

Keep it out of require. Anything it registers (commands, service provider, health endpoint) is for developers and CI, not production traffic.

2. Discover what it actually registered

With 0 stars and no dependents, there is no community knowledge base to lean on — the source is the documentation. After install:

php artisan list | grep -iE 'dx|dev|diag|quality'
php artisan about

Laravel auto-discovery will have loaded the service provider; about shows you the provider and any config it merged. Then read vendor/liberusoftware/developer-experience/src/ — look for Console/, config/, and any stubs/ directory. Those three tell you 90% of the package's surface area in about five minutes.

3. Publish config before running anything destructive

php artisan vendor:publish --provider="Liberu\DeveloperExperience\DeveloperExperienceServiceProvider"

Check the published tags first (--tag=config) so you don't blindly overwrite your pint.json, phpstan.neon, or CI workflows. Commit your current state to git before this step.

4. First real use case: baseline an existing codebase

The stated purpose ("reproducible development/quality conventions") maps to the single most valuable workflow: run the diagnostics command on a messy legacy app, get a report of what's non-conforming, and use that as your adoption backlog. Run it before you touch any config so you have a "before" snapshot.

Implementation Patterns

The diagnostics-as-a-gate pattern. The highest-leverage integration is wiring the diagnostics command into CI as a non-blocking report first, then a blocking gate once you're clean:

# .github/workflows/quality.yml
- run: composer install --no-interaction --prefer-dist
- run: php artisan dx:diagnose --format=github   # verify actual command name
  continue-on-error: true                        # phase 1

Flip continue-on-error to false only after the baseline is green. Going straight to blocking on a 0.x package with no dependents means a patch release can red your pipeline overnight.

Composer script façade. Don't make the team memorize vendor command names. Wrap them so a future swap-out is a one-line change:

"scripts": {
  "dx": "@php artisan dx:diagnose",
  "dx:fix": "@php artisan dx:fix",
  "check": ["@dx", "pint --test", "phpstan analyse"]
}

Onboarding pattern. In a fresh clone, the sequence "install → publish config → run diagnostics → run fixer" is exactly a new-hire's first hour. Put those four commands in README.md under "Local setup" so the package doubles as onboarding documentation. This is where the "reproducible conventions" claim actually pays off.

Modular monolith usage. The module- prefix in the repo name signals Liberu's module ecosystem. If your app is split into modules, run diagnostics per-module (--path=modules/Billing or equivalent) rather than repo-wide, so one un-migrated module doesn't drown the signal. Confirm path-scoping support in the command signature (php artisan help dx:diagnose).

Pre-commit hook. Point a pre-commit (or Husky/simple-git-hooks) hook at the fixer + diagnostics pair so violations never reach CI. This is the cheapest enforcement point and the one developers actually tolerate, because fixes are instant and local.

Environment parity. If the package ships a diagnostics endpoint or env-check, gate it behind app()->environment('local') and never expose it on a public hostname — a diagnostics endpoint that dumps PHP extensions, env keys, and file permissions is a reconnaissance goldmine.

Gotchas and Tips

--no-dev will break your deploy if you're careless. If you ever invoke a package command from a deploy script, it won't exist in production. Keep every invocation in scripts blocks that run only in dev/CI, or guard with class_exists().

Config caching hides changes. After editing the published config, run php artisan config:clear. In CI, run config:cache before diagnostics to catch configs that only fail under caching (closures in config arrays are the classic offender).

Publishing overwrites silently. vendor:publish with no --tag can clobber phpstan.neon/pint.json/workflow files. Always git status immediately after publishing, and prefer --tag= plus --force only when you mean it.

Path and working-directory assumptions. Quality tools that shell out to vendor/bin/* or resolve absolute paths frequently break when run from a subdirectory or in Docker with a different mount point. If diagnostics report "tool not found" locally but pass in CI (or vice versa), this is almost always the cause — check for base_path() vs getcwd() usage in the source.

Exit codes and output formats. Verify the command returns non-zero on failure — some early-stage packages print errors but exit 0. Test explicitly:

php artisan dx:diagnose; echo "exit=$?"

Pipe-friendly --format=json output is what you want for dashboards; if it's absent, extend the command rather than parsing human text.

Interactions with existing tooling. Do not assume the package owns Pint/PHPStan/Rector versions. Run composer why pint and check for duplicate/conflicting constraints; a 0.x dev tool that pins a different PHPStan major than your app will cause confusing "config key unknown" errors. Prefer letting the package invoke your binaries rather than replace them.

Debugging. Add -vvv, and check storage/logs/laravel.log — diagnostics commands often log the underlying tool output there rather than to stdout. A silent, generic failure message usually means the real error was swallowed a layer down.

Extension points to look for. In order of likelihood: a config array of "checks" you can append to, a container binding for a reporter/formatter interface, and event dispatching around check completion. A custom check class implementing the package's check contract is the cleanest way to encode your team's rules (e.g. "no env() outside config", "every module has a README") without forking.

Version discipline. Zero dependents and 0.x-era maturity means pin conservatively — "liberusoftware/developer-experience": "~1.0.0" style constraints once a stable tag exists, and read CHANGELOG/diff on every bump. Vendor the config into your repo (published, committed) so an upstream default change can't silently alter your gate thresholds.

When to bail. If the diagnostics are thin wrappers over Pint/PHPStan/Rector with no added orchestration, the same value comes from three composer scripts and no dependency. Adopt it for the conventions it encodes; drop it the moment you're maintaining the tool more than it's maintaining your codebase.