Skeleton Laravel Package

Getting Started

This is the first formal assessment for qh-8/skeleton, covering the v4 line (v4.0.2 current, superseding v3.0.0). Because the published release notes for v4.0.2 are only a compare link (v3.0.0...v4.0.2), treat the diff itself as the changelog and read it before upgrading — a 3.x → 4.x jump is a major-version signal and should be assumed breaking until proven otherwise.

Minimal adoption path:

1. composer require qh-8/skeleton in the target Laravel app (or composer create-project if you are consuming it as a scaffold rather than a dependency).
2. Confirm the Laravel/PHP constraints in the package's composer.json match your app before installing — see Gotchas.
3. php artisan vendor:publish --provider="Qh8\Skeleton\SkeletonServiceProvider" to pull out any config, migrations, or stubs, then php artisan migrate if migrations shipped.
4. php artisan config:clear && composer dump-autoload before your first smoke test.

Where to look first, in order:

• README.md — for a package named skeleton, the README is usually the whole contract; it tells you whether this is a library you require or a template you copy.
• composer.json — autoload.psr-4, extra.laravel.providers / aliases (auto-discovery), and the require block. This is the fastest way to see what v4 changed.
• src/ — providers, console commands, and any contracts/interfaces intended for extension.
• config/ and database/ — publishable surface area.

First use case: get the package's primary entry point running against a throwaway branch — either the Artisan command it registers (php artisan list | grep skeleton) or its facade/contract binding resolved out of the container. Confirm the happy path end-to-end before wiring it into anything real.

Implementation Patterns

Treat it as scaffolding, not a runtime dependency, unless the README says otherwise. "Skeleton" packages are typically either (a) a package-development boilerplate you clone once, or (b) a generator that emits files into your app. The day-to-day workflow differs sharply:

• Clone-once: fork/vendor the template, rename the namespace, strip the example command and test, and commit it as the seed of your own package. Do not keep it in require.
• Generator: keep it in require-dev, run the generator, and commit its output — then review generated diffs in PRs so scaffolding changes are visible.

Provider registration. If auto-discovery is enabled in extra.laravel, do nothing. If not, register manually in bootstrap/providers.php (Laravel 11+) or config/app.php (10 and below) — and register it after the framework providers if it decorates core behaviour.

Configuration over modification. Bind defaults through the published config file and environment variables, never by editing files under vendor/. For anything you need to vary per-environment, prefer a thin wrapper in your own App\ namespace that reads the package config and resolves the package's contract, so an upstream v4.x patch cannot break your call sites.

Extension points. Look for interfaces/contracts in src/Contracts and bind your own implementation in a ServiceProvider::register(). This is the supported seam for custom behaviour; subclassing concrete classes is the fallback and is the first thing to break across majors.

Testing. If the package ships a TestCase base class, extend it for your integration tests so you inherit its fixture setup rather than re-deriving it. Keep at least one test that asserts the package's contract resolves from the container — that test catches major-version regressions faster than anything else.

CI. Pin the package to a caret range (^4.0) and run a separate job against the lowest supported PHP/Laravel combination the package declares. For skeleton-style packages, also add a job that runs the generator/scaffold and asserts it produces a bootable app — that is the actual behaviour you depend on.

Gotchas and Tips

• The v4.0.0 boundary is the risk, not v4.0.2. The only published artefact is a v3.0.0...v4.0.2 compare link, so the substantive breaking changes almost certainly landed in 4.0.0 and are undocumented here. Open the GitHub compare view and read composer.json, the service provider, and any renamed/removed classes before bumping. If you cannot get that information, pin ^3.0 and upgrade deliberately rather than opportunistically.
• Namespace and package-name collisions. Skeleton templates usually ship a placeholder vendor/namespace. If you cloned it, grep the entire tree for the original namespace — miss one reference in composer.json's psr-4 map and you get class-not-found errors that look like autoload cache problems.
• Auto-discovery silently fails when the extra.laravel block is malformed. Symptom: provider never runs, config keys are null, no error. Diagnose with php artisan about (Laravel 11+) or php artisan package:discover -v.
• Config caching bites after publishing. vendor:publish then config:cache in the same deploy will serve stale values. Order your deploy as: publish → config:clear → config:cache.
• Publishing overwrites. vendor:publish --force will clobber your edits to published config/migrations. Publish once, commit the result, and never re-publish in CI.
• Migrations from a skeleton can collide with your app's existing tables. Check the published migration filenames and table names before running migrate on anything with data.
• Debugging tip: for a package with sparse release notes, composer why qh-8/skeleton and composer show qh-8/skeleton --all are faster than the README for understanding what pulled it in and what versions are actually available.
• Extension via decoration. If the package binds a concrete class rather than a contract, you can still swap it with $this->app->extend(...) in a late-registered provider — but document it, because it is undocumented-package territory and will not survive a major bump gracefully.