Foundation Laravel Package

Getting Started

overlook/foundation is not a general-purpose community package — it's an internal convention package ("the conventions Overlook Innovations applies to every application it builds") published to Packagist with 0 stars and 0 dependents. That framing should drive how you approach it: treat it as vendor code you must read before you depend on it, not as a library with an ecosystem behind it.

Minimal adoption steps

composer require overlook/foundation
composer show overlook/foundation   # confirm the resolved version is a real tag

Then, before writing a single line against it:

1. Open vendor/overlook/foundation/src/ and list the top-level namespaces. The package name suggests a foundation layer — base classes (models, controllers, form requests), shared traits, and a root service provider. Confirm what exists rather than assuming.
2. Find the service provider and check whether it's registered via extra.laravel.providers (auto-discovery) or needs a manual entry in bootstrap/providers.php. If it's not auto-discovered, register it manually or nothing in the package will work and you'll waste an hour chasing "class not found."
3. Run php artisan vendor:publish --provider="Overlook\\Foundation\\FoundationServiceProvider" --list (adjust the FQCN to the real one) to see exactly which config, migrations, or stubs the package offers. Do not blind-publish; see the Gotchas section.

First use case

The highest-value first step is almost always inheritance substitution: find the one or two base classes or traits the package provides and use them in a single new controller or model, in one branch, with tests running. Do not retrofit existing code on day one. A conventions package succeeds or fails on whether its opinions match yours, and you can only learn that from a small, reversible experiment.

Verification checklist before you commit to it

• composer show overlook/foundation — check required PHP and illuminate/* constraints against your app's versions. A conventions package that pins Laravel to the wrong major is a dead end.
• Check the tag history. The metadata shows a last release of 2026-08-13, which is anomalous relative to typical release cadence — verify the tag exists on the GitHub repository and that the Packagist version matches it. If the tag is missing or mismatched, install from a VCS repositories entry with an explicit commit instead of a version constraint.
• Read the README's install section end-to-end. With no dependents, there are no third-party blog posts or Stack Overflow answers to fall back on; the repository is your entire documentation surface.

Implementation Patterns

Extend, don't modify. The core pattern for a package like this is that your application classes inherit from the package's base classes or compose its traits, and the package's service provider wires the cross-cutting behaviour. The practical rule: if you find yourself editing anything under vendor/overlook/foundation, you've found a missing extension point — override in your own namespace and bind it in the container instead.

Substitute base classes incrementally. Rather than rewriting every model, do it one at a time, with the existing test suite as the guard rail:

// app/Models/Order.php
use Overlook\Foundation\Models\BaseModel; // confirm actual FQCN in vendor

class Order extends BaseModel
{
    // existing body unchanged
}

Run the suite. If it passes, the conventions are compatible; if it fails, the diff tells you exactly which opinion the package imposes (timestamps, UUIDs, soft deletes, casts, global scopes) and whether you can live with it.

Treat the published config as the primary extension point. Conventions packages almost always expose a config file whose keys drive behaviour. Publish it, commit it, and own it:

php artisan vendor:publish --tag=foundation-config

Once published, your copy wins over the package default. Diff your copy against vendor/overlook/foundation/config/foundation.php on every upgrade — that diff is your upgrade notes.

Copy static-analysis and style config rather than referencing it. If the package ships pint.json, phpstan.neon, or a rector.php, copy the file into your project root and adapt paths. Referencing the vendor path directly is brittle: it breaks on upgrade and couples your CI to a package's internal layout.

Use its scaffolding commands for new work only. If the package exposes generator commands (make:* style), use them for new classes and let convention enforcement happen at creation time. Retrofit is where these tools cause churn.

Testing integration. If the package ships a base TestCase, extend it in your tests/TestCase.php once, so a single inheritance point controls its setup. Keep an escape hatch: a second base test case that extends Laravel's plain TestCase for tests that must not inherit package bootstrapping (HTTP tests against routes the package doesn't know about, for example).

Pin and upgrade deliberately. With 0 dependents, you are effectively the only integration test in existence. Use an exact or tilde constraint ("overlook/foundation": "~1.2"), commit composer.lock, and upgrade on a branch with the full suite green. Never let a composer update float this package silently alongside unrelated work.

Gotchas and Tips

You are the first user. Zero stars and zero dependents means no bug reports have been filed, no edge cases have been shaken out by anyone but the authors' own applications. Budget for reading source rather than docs, and expect to file the first issues. This is the single biggest risk factor and it does not go away with time — it goes away with your own test coverage.

Verify the release metadata before trusting it. The last-release date (2026-08-13) is worth a sanity check, and any package whose distribution metadata looks unusual deserves a composer show --all plus a look at the GitHub tags. If the version you install doesn't correspond to a commit on the default branch, treat it as unreviewed code.

Auto-discovery is silent until it isn't. If the provider is auto-discovered, everything works while you develop and can break in a cached-config environment (php artisan config:cache). Always test the cached path in CI:

php artisan optimize && php artisan about

php artisan about is the fastest way to confirm the provider actually booted.

Config merge vs. publish. Published config does not receive new keys added in later versions. After an upgrade, compare your published file to the vendor default and merge in new keys manually — new conventions typically arrive as new config keys, and a missing key means the feature is silently off.

Migrations and seeders are the sharpest edge. If the package publishes migrations, they will collide with an existing app's schema or ordering assumptions. Prefer running them only in fresh installs, or copy the schema into your own migrations so your application owns its database history. A conventions package that controls your migrations makes future removal extremely expensive.

Convention conflicts are migration costs, not bugs. If the package assumes UUID primary keys and your app uses auto-incrementing integers, that's not a defect — but retrofitting it across an existing codebase is a multi-day change. Measure the blast radius on one model before committing.

Static-analysis baselines shipped by the package will hide your errors. If it includes a PHPStan baseline, never let it apply to app/. Your code should be analysed at full strictness; the baseline exists to tolerate the package's own internals.

Debugging entry points, in order of usefulness: (1) composer show overlook/foundation for the installed version and autoload paths, (2) the package's service provider boot() and register() methods, (3) vendor:publish --list, (4) php artisan about to confirm boot, (5) a dd() in the provider's boot() as a last resort. Because there's no community knowledge base, reading these five things will answer nearly every question faster than searching.

Extension points to look for explicitly: container bindings in the provider (interface → implementation pairs are your cleanest override), config keys, protected methods on base classes intended for override, and any Macroable traits. If none of those exist, the package is closed for extension in that area — and that's your signal to fork or isolate rather than fight it.

Isolate the dependency. Keep package-specific glue in a thin layer (app/Support/Foundation/ or a single service provider of your own) so that removing the package later is a directory delete plus an inheritance change, not a codebase-wide refactor. For a zero-dependent package with a single maintainer organisation, that insurance is cheap and worth paying for on day one.