Weave Code
Fusion Laravel Package
hi-folks/fusion
Fusion is a Laravel package by hi-folks for merging multiple Laravel applications into one. It helps combine routes, views, migrations, and configs so you can build a modular monolith while keeping each application organized.
Laravel package that enhances Eloquent models to facilitate the management of structured, database-free content through Markdown files with Frontmatter.
Frequently asked questions about Fusion
- How do I install hi-folks/fusion in a Laravel application?
- Install it with Composer from your Laravel project root: composer require hi-folks/fusion. The package is Laravel-native and registers its Artisan commands and configuration through package discovery, so no manual service provider registration is required. After installing, review or publish the package configuration if you want to change defaults such as the content directory or cache TTL, and set any environment-specific values in your .env file. Commit the composer.json and composer.lock changes so every environment installs the same version.
- What does hi-folks/fusion actually do?
- Fusion is a Laravel package for consolidation work. It can merge duplicate Eloquent models by reassigning relationships onto a target model and combining attributes with configurable conflict resolution, and it ships Artisan tooling (fusion:start, fusion:check, fusion:check-model) for consolidating Laravel applications and their content. The merge API is transaction-safe and supports custom callbacks so you can encode domain-specific rules. Which part you lean on depends on whether you are deduplicating database records or combining codebases into a modular monolith.
- How does Fusion handle conflicting attribute values when merging two models?
- Overlapping columns are resolved through configurable conflict handling rather than a single hard-coded rule, so you decide which record wins per attribute or per merge. Sensible defaults apply when you configure nothing, which keeps simple merges to a single call. For anything nuanced, custom merge callbacks let you apply domain logic such as summing counters or preferring the most recently updated record. Review the defaults before merging models where a column has legal, financial, or audit significance.
- Is the model merge transaction-safe, and what happens if it fails partway?
- Fusion exposes a Laravel-native, transaction-safe API for deduplicating records, so relationship reassignment and attribute updates run inside a database transaction. If something throws mid-merge, the changes roll back instead of leaving relationships half-moved between two records. For larger operations, wrap the merge in your own transaction or queue job so the whole unit of work succeeds or fails together. Test on a copy of production data before running it at scale.
- What are the fusion:start, fusion:check, and fusion:check-model Artisan commands for?
- fusion:start bootstraps the Fusion setup for a project, fusion:check performs deep validation over your content with optional JSON output, and fusion:check-model inspects Eloquent models to confirm they are compatible. The commands share a configurable content directory and honor a --dir option where it applies. In v1.2.1 fusion:check-model also returns a non-zero exit status when a model is incompatible, which makes it usable as a gate in CI rather than a manual review step.
- How does Fusion cache parsed Markdown, and how do I control staleness with FUSION_CACHE_TTL?
- Parsed Markdown rows are cached using Laravel's configured cache store, so Fusion reuses your existing file, Redis, or database cache instead of adding a second caching layer. FUSION_CACHE_TTL controls freshness and defaults to one hour, which means content edits may not appear until the TTL expires unless invalidation runs explicitly. If editors expect instant updates, lower the TTL or flush the relevant keys when content changes. Because behavior varies by store, especially around eviction and deploy-time flushing, validate it in each environment including CI and ephemeral previews.
- Can I run fusion:check in CI and consume the output as JSON?
- Yes. fusion:check supports JSON output, so results can be piped into CI logs, pull request annotations, or dashboards. Reports are concise by default and --include-valid is opt-in, which keeps output readable on large content sets while still allowing a full listing when you need it. If your automation parses the JSON, treat that shape as a de facto contract and pin the package version until you confirm the schema is documented as stable. For large content sets, scope the check to changed files where possible so deep validation stays fast.
- Why did fusion:check-model start failing my pipeline after upgrading to 1.2.1?
- In v1.2.1, fusion:check-model returns a non-zero exit status when it detects an incompatible model. Previously a pipeline could stay green even when a model was incompatible, so jobs that passed before may now fail. This is an intentional quality gate rather than a regression, so schedule the upgrade and treat it as a deliberate change. Run the command locally against your models first and tell whoever owns the pipeline that previously green builds may turn red.
- Does the --dir option support multi-tenant setups, and are cache keys namespaced?
- The --dir option is available on fusion:start and fusion:check-model so teams with non-standard model layouts can point Fusion at a custom directory, and the content root is configurable as well. If one application and one cache store serve multiple content roots or tenants, confirm that cache keys are namespaced by directory or tenant before you rely on it. A key collision would serve one tenant's content to another, so verify this explicitly for any multi-brand or multi-tenant use. This is the single most important thing to check before sharing a cache store across content roots.
- Which Laravel and PHP versions does Fusion support?
- The v1.2.1 release did not change Laravel or PHP version constraints, so the support matrix from v1.2.0 still applies. Check the require block in composer.json and the README for the exact Laravel and PHP ranges before upgrading, particularly if you are evaluating newer framework releases or PHP 8.4 and 8.5. If you need a version outside the declared constraints, test in a branch and watch for conflicts during composer update.
Weaver
How can I help you explore Laravel packages today?