Download the PHP package xuple/evolayer-base without Composer

EvoLayer Base

EvoLayer Base is a Composer package that adds an AI / ontology / React-block substrate to a Laravel 13 + React + Inertia application.

Installing it adds zero routes and no active request surface by default. Shared props and feature pages are host opt-in via flags and publish tags.

For the strict rules on what the framework owns vs what the host app owns, and how updates work, see the EvoLayer Framework Contract.

For tutorials, how-to guides, and the public reference, start at evodevops.com/evolayer-base/docs.

EvoLayer Base is also the intended foundation for future EvoLayer sibling packages — Commerce (product sales), SaaS (subscriptions / tenants), and RLS (PostgreSQL row-level security) — but those layers ship as separate packages and are not part of this one. EvoDevOps is the teaching/site brand for the family.

Start here

What you get

• Structured AI streaming built on laravel/ai, with ThreadStudio, PRD generation, text assist, evolayer:ai:smoke-test, evolayer:ai:probe, and evolayer:ai:stream-check.
• A small ontology compiler and TypeScript contract generator for describing app entities, routes, and blocks.
• React blocks and example pages that publish into the host app without taking over the starter.
• Admin and lineage primitives (AdminGate, ChangeEvent, AI invocation ledger) intended for reuse by Commerce, SaaS, and RLS packages.

Quick start

EvoLayer migrations auto-load from the package via Laravel's package migration loader. Do not publish them by default; vendor:publish --tag=evolayer-base-migrations is only for hosts that intentionally want to own and customise the schema.

After step 4 the package is installed but does nothing yet — php artisan route:list shows no new routes. You opt in to features via env flags + per-feature publish tags (see below).

EvoLayer Base targets the Laravel React starter shape. Existing Inertia apps that have renamed routes, layouts, components, or aliases may need adapter edits after publishing frontend stubs.

For a one-shot install into an existing app, use:

Then run php artisan evolayer:doctor to verify the package bindings, ontology cache, and AI patch state from the CLI runtime. doctor does not prove that a separate web-server or PHP-FPM user can write Laravel cache or storage paths; hosted filesystem permissions belong to the host application or starter deployment docs.

Enabling a feature (two coupled steps)

Each opt-in feature is two things that must match: an env flag (registers its routes) and a frontend publish tag (drops its pages). Do both together — a published page whose route isn't registered will fail tsc, and an enabled route with no page is a dead link.

voice_input and ai_text_field are blocks consumed by other pages (ThreadStudio, PRD), not standalone pages. Enabling their flags registers their endpoints; the consuming page receives the endpoint URL as a server prop and shows the relevant control only when the flag is on — so no cross-feature compile-time dependency exists.

To publish everything at once (demo / kitchen-sink), use the meta tag evolayer-base-frontend and enable all flags.

Host apps that have deliberately modified the public landing page at resources/js/pages/evolayer/base.tsx should use evolayer-base-frontend-preserve-overrides for forced frontend resyncs. It publishes core plus the non-marketing feature page sets, but does not touch that landing page. The normal evolayer-base-frontend and evolayer-base-frontend-marketing-pages tags remain unchanged for package consumers that want the package defaults. The starter still keeps its _STARTER_OWNED_PAGE_ sentinel check as a defensive guard, not as the primary resync strategy. The authenticated /home launcher is host-owned by the starter (resources/js/pages/home.tsx, route home) and is not a package surface.

Standard features (installed once, always on)

These ship as part of the package's frontend stubs and don't need a flag. They're "table-stakes" UX that every starter should have.

Opt-in features (enable per env flag)

Every feature defaults to off. Set the corresponding env flag to true to enable. Each flag also gates the route file for that feature — the routes only appear in route:list when their flag is on.

After enabling, run php artisan route:list to confirm only the routes you asked for are registered.

Opt-in extras (composer packages)

Base requires spatie/laravel-permission and spatie/laravel-activitylog as core dependencies. The other two Spatie packages are optional and only required when you enable the related features:

To enable contact attachments:

Set EVOLAYER_BASE_FEATURE_CONTACT_ATTACHMENTS=true in .env. The package's FormSubmission model loads either way — a compat polyfill in Xuple\EvoLayer\Base\Compat\* shadows the Spatie interfaces and traits when the Spatie packages aren't installed.

If you use Spatie activitylog, tags, or medialibrary with EvoLayer ULID models, make the related morph id columns ULID/string-compatible before migrating on PostgreSQL:

• activity_log.subject_id must support ULID subjects (nullableUlidMorphs('subject', 'subject')).
• taggables.taggable_id must support ULID taggables (ulidMorphs('taggable')).
• media.model_id must support ULID media owners (ulidMorphs('model')).
• activity_log.causer_id may stay integer when causers are integer-keyed users.

The EvoLayer Base starter commits corrected Spatie migrations for this. Package-only installs that publish upstream Spatie migrations must make the same edits before running migrate against PostgreSQL.

Host integration steps

A handful of host-owned files need small edits the package cannot publish over. They are small and stable.

If you start from xuple/evolayer-base-starter, these edits are already applied.

1. Apply the laravel/ai patch

Until upstream lifts the structured-output streaming guard, structured streaming requires patching vendor/laravel/ai/src/Providers/Concerns/StreamsText.php. The patch ships at patches/laravel-ai-structured-streaming.patch after vendor:publish --tag=evolayer-base-patches:

The recommended production setup is to declare this patch in your starter template's composer.json so it survives every composer install. See patches/README.md for the revisit policy.

2. Wire EvoLayer shared props into Inertia

In app/Http/Middleware/HandleInertiaRequests.php:

The package's pages access evolayer via the published useEvoLayerProps() hook — it throws a helpful error if the shared prop is missing, so misconfigurations surface immediately.

3. Map EvoLayer public pages onto PublicLayout (if you enable MARKETING_PAGES)

In resources/js/app.tsx:

4. Surface EvoLayer nav entries in your sidebar

In resources/js/components/app-sidebar.tsx:

useExampleNavItems() filters items by the EVOLAYER_BASE_EXAMPLE_* flags so disabled features don't appear.

Invariant contracts (for variant authors)

These are the stable surfaces sibling EvoLayer packages (Commerce, SaaS, RLS) and host apps can depend on. Breaking changes are versioned.

Namespacing convention

SSE streaming vocabulary

Stable event names emitted by Base streaming endpoints:

Reserved for future Base / variant use (documented now to prevent collision): tool_call, tool_result, thinking_delta, usage.

Toast / flash contract

Payload shape: {type: 'success'|'error'|'warning'|'info', message: string, ...}.

Schema invariants

The following columns are guaranteed on Base's prefixed tables/models for variant/RLS compatibility:

• evolayer_base_ai_invocations (AiInvocation): nullable subject_type/subject_id polymorph, tenant_id, prompt_tokens, completion_tokens, cost_cents, cost_currency.
• evolayer_base_change_events (ChangeEvent): nullable string-compatible polymorphic actor_type/actor_id (User by default; variants may record Customer/Tenant/System), nullable tenant_id.

AdminGate contract

Default impl (SpatieAdminGate) routes evolayer.admin through hasRole('admin') and arbitrary abilities through Laravel's Gate facade. Replace via container binding to plug in a different model.

Ontology multi-file architecture

The package's OntologyCompiler supports merging multiple ontology files keyed by namespace. Variant packages register their ontology.yaml during boot:

The compiler reads the registry plus the host's own ontology.yaml and produces a namespace-keyed merged output.

Pluggable admin gate

The package ships an AdminGate contract with a default SpatieAdminGate implementation (hasRole('admin')). To plug in a different authorisation model, bind your own implementation in AppServiceProvider:

Known constraints for 0.1

• Assumes laravel/fortify for authentication when using the default SpatieAdminGate. Other auth setups require a custom AdminGate binding.
• Assumes the host users table uses the default Laravel convention (integer PK, table name users).
• Structured-output streaming requires the manual laravel/ai patch above until upstream lands the fix. Tracked in patches/README.md.
• The package does not automatically declare its patch in the host's composer.json — the cweagans/composer-patches plugin v2 cannot resolve dependency-relative patch paths at install time. The starter template (or your composer.json) handles this.

Development

composer install automatically applies the laravel/ai patch to the package's own vendor copy so the test suite has structured streaming available. The npm checks only guard the published resources/js frontend stubs against format-only drift before host apps run composer evolayer:resync.

The package's own test suite runs against require-dev Spatie packages (medialibrary, tags) — meaningful "no Spatie installed" CI verification needs a separate composer install without dev deps. The compat layer's no-op stubs are independently asserted in tests/Unit/CompatNoopStubsTest.php.

Support and project status

EvoLayer is pre-1.0. Breaking changes are expected until 1.0. See DECISIONS.md for durable architecture decisions.

License

MIT. See LICENSE.