Core Laravel Package

Getting Started

Know what you're installing. lara-zeus/core is a kernel, not a feature. It ships the base classes, traits, config namespace, service-provider scaffolding, helpers, and publishable assets that the visible Zeus packages (Sky panels, Bolt forms, Rain tables, settings/translation tooling) resolve against. Install it alone and you get a package in composer.lock and nothing observable in the UI. The realistic entry point is: you added a Zeus capability package, and core landed as a transitive dependency.

Minimal steps

1. Confirm provenance before doing anything else:

   composer why lara-zeus/core
   composer show lara-zeus/core
   

   If no requirer shows up, you installed it by hand for no reason — drop it. If a sibling requires it, that sibling is your actual entry point.

2. Read the source first. The release notes for 5.1.1 are literally "Docs" and "update css"; there is no prose documentation worth waiting for. Your docs are:

   vendor/lara-zeus/core/src/           # base classes, contracts, traits, helpers
   vendor/lara-zeus/core/config/        # namespace + defaults
   vendor/lara-zeus/core/resources/     # views, css/js that must enter your build
   

   Start at the service provider. It tells you exactly what registers into the container, which Blade namespaces exist, what migrations load, and what is publishable.

3. Enumerate the real surface in your app, not a generic one:

   php artisan vendor:publish            # lists providers and tags — copy the real FQCN from here
   php artisan about                     # drivers, providers, cache state
   

   Then publish config only and git diff it. That diff is the highest-value ten minutes you'll spend on this package.

First use case to target: a small customization layered on a sibling — a custom form field type, an extra table column, a tweak to a settings page — implemented by extending a core base class or composing a core trait, not by forking the sibling. That is the only thing core is for.

Where to look, in order: service provider → config (namespacing/defaults) → src/ for abstract classes and traits → resources/ for anything that must enter Tailwind/Vite → then the sibling package's usage of core, which is your de facto spec.

Do not add a direct composer require unless you are subclassing core, implementing its contracts, or overriding its views. Promoting an inherited dependency to a declared one is a decision worth writing down.

Implementation Patterns

1. One adapter namespace for everything Zeus. Confine every LaraZeus\* import — models, facades, helpers, config keys — to a single namespace in your app. Domain code never touches Zeus directly.

namespace App\Support\Zeus;

class ZeusBridge
{
    public function field(string $type, array $options = []): mixed
    {
        return app(config('zeus.forms.field_factory'))->make($type, $options);
    }

    public function panel(string $key): mixed
    {
        return config("zeus.panels.{$key}");
    }
}

This is the highest-leverage pattern available to you: core's semantics are defined upstream by packages you don't steward, so a one-file seam turns an exit into a refactor instead of a rewrite.

2. Extend, don't fork. When a sibling behaves almost right, subclass the core base and bind your subclass through config or your own provider.

namespace App\Zeus;

use LaraZeus\Core\...\BaseClass; // resolve the exact path with:
// grep -rn "abstract class" vendor/lara-zeus/core/src

class TenantAwareWidget extends BaseClass
{
    protected function resolveOptions(): array
    {
        return array_merge(parent::resolveOptions(), [
            'tenant' => tenant()->id,
        ]);
    }
}

Then point the relevant Zeus config key at TenantAwareWidget::class. Inherit what works; override one method. Never edit vendor/.

3. Traits are a contract, not a convenience. Core traits assume the host class supplies certain properties/methods. The moment you use one, grep it for $this-> and satisfy every expectation explicitly. Then write an isolation test that exercises the trait against a minimal host class — that test becomes your upgrade canary when core bumps.

4. Publish narrowly and commit the diff. Publish config once and treat every future change as a reviewable event. For views, publish only the single view you're overriding (tag-scoped), never the whole tree — otherwise every core upgrade arrives buried in a diff of files you never touched.

5. Wire the asset pipeline deliberately. Zeus views ship Blade that your Tailwind build must see:

// tailwind.config.js
content: [
  './resources/**/*.blade.php',
  './vendor/lara-zeus/**/resources/views/**/*.blade.php',
],

Verify in a real npm run build, not just npm run dev. If styles appear in dev and vanish in build, the glob is wrong — not the package.

6. Keep Zeus tables out of your domain schema. Run the migrations, but don't FK domain tables into Zeus tables or reference Zeus models from domain services. Read through the adapter; treat that data as third-party-owned.

7. Pin the family to a mutually compatible set. Core, forms, and tables move in lockstep majors. Pin exact versions across all of lara-zeus/*, commit the lockfile, and gate bumps on a branch:

composer update "lara-zeus/*" --with-dependencies --dry-run
git diff composer.lock   # inspect every laravel/framework and livewire/livewire bump it drags in

8. Feature-flag the pilot. Put Zeus-backed screens behind a route group or flag so the first capability can be pulled out without unpicking the app.

9. Test at the Livewire boundary. Whatever core surface you touch, cover it with component tests so the suite runs fast on every lockfile bump:

Livewire::test(YourPanelComponent::class)
    ->assertSee('...')
    ->assertHasNoErrors();

Gotchas and Tips

Config cache is the #1 false alarm. After publishing or editing Zeus config, run php artisan config:clear (or config:cache in the deploy step). A stale cached config makes "my change did nothing" almost every time.

Global surface pollution is the realistic failure mode. Conventional kernel packages register config keys, helpers, and Blade directives globally. Before merging, grep:

grep -rn "function " vendor/lara-zeus/core/src | grep -v "private\|protected"
grep -rn "Blade::directive\|Blade::if" vendor/lara-zeus/core/src

Confirm every key is namespaced (zeus.*, not a bare config('forms')). Naming collisions in an app you also control are far likelier than a hard crash.

Narrow version constraints cause upgrade deadlock. A core bump can force a sibling bump, which forces a Laravel/Livewire bump. Check whether constraints are permissive (^11|^12) or pinned narrow. When a bump refuses to resolve:

composer why-not lara-zeus/core <version>

It names the exact blocking constraint.

Published views silently shadow vendor updates. Once you override a view, upstream fixes stop reaching you. Keep a list of overridden view paths and re-check them on each upgrade.

Zero dependents and five stars means you're the discoverer. There's no peer evidence for edge cases. Budget for writing the test that proves the behaviour yourself, and keep it fast.

Plan for no support contract. No SLA, no security disclosure process, bus factor near one. Decide now, in writing, whether an unpatched defect means patch-and-wait or fork (trivially legal under MIT, operationally expensive). Don't take the fork path until a first production use proves durable.

Extension safety, in descending order: config (safest) → view overrides (safe but diff-heavy) → subclassing core base classes (moderate; depends on protected internals) → implementing core contracts directly (an interface change is a hard break) → fork (last resort). Only move down when the level above genuinely can't express what you need.

Debugging tactics that work here:

• php artisan about and php artisan vendor:publish to enumerate what's actually registered.
• composer why-not on any refusal to resolve.
• Read how the sibling package calls core — the sibling is the spec you don't have.
• Bisect upgrade failures against a pinned branch, never against main.

Keep a one-page dependency note listing the core surface you actually depend on: classes subclassed, traits used, config keys read, views overridden, helpers called. That note is what makes your pinning policy reflect real usage, and it's the first thing you'll want if maintenance stalls.