Magic Starter Laravel Laravel Package

Getting Started

Start by installing the package and publishing only what you need:

composer require fluttersdk/magic-starter-laravel
php artisan vendor:publish --tag=magic-starter-config
php artisan vendor:publish --tag=magic-starter-migrations
php artisan migrate

Look first at:

1. The package README and composer.json for supported Laravel/PHP versions.
2. The published config file, usually config/magic-starter.php, for feature flags, AI quota settings, history/storage settings, and cache token weighting options.
3. The package service provider for publish tags, bindings, scheduled jobs, and extension points.
4. Any install/scaffold command exposed by the package.

A practical first use case is enabling support-attachments, wiring the published support routes/models into your app, and verifying an authenticated user can upload and retrieve a support attachment from the configured disk. Then exercise the AI desk: send a support conversation through the package’s AI endpoint, confirm the quota consumption reflects cache tokens, and verify a stored history summary is created and retrievable for that conversation.

Version 0.0.38 adds two support/AI-desk features: cache tokens are now weighed in the AI quota, and a stored history summary is available for the AI desk. There are no new migration steps called out in the release notes, but confirm this against the full changelog for 0.0.34–0.0.37, which are not detailed in the provided notes.

Implementation Patterns

Treat the package as a feature-flagged starter layer rather than code you edit in vendor/.

• Enable features explicitly. Keep config flags such as support-attachments and any AI-desk flags enabled only in environments where the feature is actually used. This avoids accidental attachment reads and unexpected AI quota consumption.
• Extend published code. Publish and customize views, routes, models, policies, and config. Do not modify vendor files, because patch releases like 0.0.33 and minor feature releases like 0.0.38 can change internal behavior.
• Use the package’s storage abstraction. Upload support files through the package’s configured disk and retrieve them through its controller/action rather than building ad hoc file paths. This keeps feature gating and authorization consistent.
• Gate attachment access in your own code too. If you add custom support endpoints, check the same feature flag before reading support files, and authorize access to the related support record.
• Integrate with your auth and policies. Bind package models to your existing user model and policies where supported. For attachments, verify ownership or ticket/support-record access before serving files.
• Plan AI quota accounting around weighted tokens. Since 0.0.38, cache tokens count toward the AI quota. If you display usage, enforce limits, or estimate cost in your own UI, read the package’s quota values rather than recomputing from raw prompt/completion tokens—otherwise cached prompts will appear “free” in your numbers while the package still charges them.
• Use the stored history summary as the canonical conversation context. Instead of resending full transcripts or building your own summarizer, retrieve the package’s stored summary for the AI desk and pass it forward where the package exposes that hook. Keep any custom summary format separate from the package’s stored one to avoid drift.
• Test with the feature on and off. Use Storage::fake() and set the relevant flags in test config. Assert that attachment reads work when enabled and are skipped or rejected when disabled, and assert quota behaviour with and without cached tokens.
• Keep configuration cache-friendly. After changing feature flags or quota settings, run php artisan config:clear locally and ensure deployment scripts rebuild config cache.

Gotchas and Tips

• 0.0.33 behaviour change: support files are read only when support-attachments is enabled. If your app previously relied on reading support files while that feature was off, enable the flag or guard those reads explicitly.
• AI quota math changed in 0.0.38. Cache tokens now weigh into quota consumption. Re-check any dashboards, tests, or customer-facing usage counters that assumed cache hits were free; expect higher reported usage for cache-heavy conversations.
• Stored history summaries are real persisted data. The 0.0.38 history summary is stored, not computed on the fly. Decide retention, purge, and privacy handling deliberately—summaries may contain user content and will outlive the request that created them. Do not assume the package cleans them up when a ticket is deleted.
• Check the flag and config key names. Confirm whether support-attachments and the AI quota/history settings are top-level config keys or nested under a features/support array. Use the published config as the source of truth.
• Clear caches after config changes. php artisan config:cache can hide flag and quota changes until cleared. This is a common source of “the fix didn’t apply” confusion.
• Storage disk and permissions matter. Verify the configured disk exists, is writable, and is not publicly exposed unless intended. Check queue/worker environments use the same disk and quota configuration, since summary generation and quota accounting may run in jobs.
• Handle orphaned files and orphaned summaries. If support records are deleted, ensure attachment cleanup—and now history-summary cleanup—is handled by your app or the package’s events/jobs. Do not assume the package cleans up every derived record.
• Do not serve raw paths. Use package routes/controllers or signed URLs for attachment downloads so authorization and feature gating remain in effect.
• Pin and review patch releases. Pin the version in composer.json and review changelogs before upgrading. The provided notes cover only 0.0.37–0.0.38; review the full diff from your installed version, as earlier releases between 0.0.33 and 0.0.38 may also affect behaviour.
• Use extension points before forking. Prefer published config, views, route overrides, policies, events, and container bindings. Forking vendor code makes future patch releases harder to apply.