Framework Laravel Package

Getting Started

The package is a thin foundation layer used across HynMe packages (hyn/multi-tenant, hyn/package, tenant-aware apps). It ships a base Eloquent model, a repository abstraction, a package/version registry, and the hyn config namespace. The repository is effectively dormant (zero dependents, no stars), so treat it as a reference implementation to fork or vendor rather than something you upgrade freely — pin to a specific commit in composer.json.

Minimal setup:

composer require hyn-me/framework

Laravel's package discovery should pick up the service provider. If you're on an older Laravel or have discovery disabled, register it manually:

// config/app.php
Hyn\Framework\Providers\HynFrameworkServiceProvider::class,

Then publish the config so you have something to edit:

php artisan vendor:publish --provider="Hyn\Framework\Providers\HynFrameworkServiceProvider"

This drops config/hyn.php. Read that file first — it's the map of everything else. After that, look at src/Contracts/ (the intended seams) and, in this order, src/Eloquent/, src/Repositories/, src/Providers/. The Contracts directory is small and tells you what the package actually promises; everything else is implementation.

First use case: take one model in your app and change it from Illuminate\Database\Eloquent\Model to Hyn\Framework\Eloquent\Model, then write a matching migration with a uuid primary key (see Gotchas). This is the lowest-risk entry point and validates that the rest of the package is even installed correctly.

Implementation Patterns

Base model for tenant-scoped entities. Extending Hyn\Framework\Eloquent\Model gives you UUID primary keys, route binding by non-incrementing IDs, and cache hooks. The idiomatic pattern is one abstract App\Models\TenantModel extends Hyn\Framework\Eloquent\Model that sets $connection and $table conventions per tenant, then concrete models extend that. Don't have concrete models extend the vendor class directly — you lose the single place to adjust connection resolution when tenancy changes.

Repository + interface binding. The repository layer is only useful if you commit to it. Define App\Contracts\UserRepository, extend Hyn\Framework\Repositories\BaseRepository (or implement the interface directly), and bind it in a per-module service provider:

$this->app->bind(UserRepository::class, EloquentUserRepository::class);

Inject the interface into controllers, jobs, and commands. The payoff is that swapping the implementation for a cache-backed one later doesn't touch call sites. If you inject the concrete class, the abstraction is decoration — this is the most common way teams use this package badly.

Version and package contracts. Hyn\Framework\Contracts\Version and the package registry exist for one reason: surfacing what's deployed. Wire them into a /health or /about endpoint. In multi-tenant deployments this is how you distinguish "the app is up" from "the app is up on the right release." Resolve from the container rather than new-ing anything, since the provider binds these as singletons.

Provider extension as the integration point. Add your own bindings in a provider that runs after HynFrameworkServiceProvider. Use mergeConfigFrom for package defaults and only override keys you actually need in config/hyn.php. If you find yourself editing the vendor config in place, stop — you'll lose it on the next composer update.

Package development with testbench. If you're building a HynMe package, orchestra/testbench is the standard harness; boot the framework provider in getPackageProviders() and assert against the config it merges. This is also the fastest way to understand the package — write one test per contract and read the failures.

Gotchas and Tips

UUID migrations must match the model. The base model expects a string UUID primary key, not an auto-incrementing integer. A migration using $table->id() will appear to work until insert time, then fail with an unsaved-model exception. Use $table->uuid('id')->primary() and set $keyType = 'string' / $incrementing = false if you override anything.

Config publishing order matters. mergeConfigFrom means the package defaults always lose to your published file. If a value seems ignored, check whether config/hyn.php exists at all — an unpublished config silently falls back to defaults that may not be what the docs imply. php artisan config:clear after every change; cached config is the single most common cause of "my change did nothing."

Repository queries bypass model events. If BaseRepository builds queries directly, saving/saved observers on your model won't fire. Anything relying on observers (audit logs, slug generation, search indexing) must be handled in the repository or moved to explicit model methods. Don't mix DB:: and Eloquent calls in the same repository without documenting which layer owns side effects.

Cache tagging is driver-dependent. The cacheable helpers depend on tag support. Redis and Memcached support tags; the file and database drivers do not, and will either throw or silently degrade. Pin CACHE_DRIVER to a tag-capable store in any environment where the caching trait is active, and add a test that asserts invalidation actually happens — this is the bug that reaches production.

Route binding assumptions. resolveRouteBinding in the base model resolves by primary key. Models keyed by slug or a composite need that method overridden explicitly; otherwise 404s look like routing bugs. This is a ten-minute fix that people usually find after an hour of blaming the router.

Debugging. php artisan tinker and resolve contracts directly (app(Hyn\Framework\Contracts\Version::class)) to confirm the container is wired. The package is quiet — it rarely throws on misconfiguration, it just behaves differently. Log::debug() inside your provider's register() is often faster than reading the source.

Extension points, not inheritance. The contracts and the service provider are the supported seams. Extending concrete vendor classes (BaseRepository, the base model) couples you to internals that will never receive a fix — the repository is unmaintained. If you need behavior beyond what the contracts offer, fork the package and point your composer.json at the fork with a vcs repository entry. That's cheaper than working around a frozen dependency.

Assume abandonment. No stars, no dependents, no recent activity. Audit the transitive dependencies against your Laravel version before committing, and budget for replacing the UUID model base with a first-party trait when you next touch the schema.