Fsmaker Laravel Package

Getting Started

• Install the package as a dev dependency (composer require --dev <vendor>/<package>) and run php artisan vendor:publish --tag=<package>-config so you can inspect and override defaults before generating anything.
• Start with php artisan list filtered by the package namespace — the v2.3 release adds several new commands (workflow management/execution, AI-agent documentation, calculators update), so the command list is the fastest way to see what is now available.
• First real use case: generate a package/app ZIP and confirm .zipignore is respected. Create a .zipignore at the project root, add an obvious exclusion (/node_modules, /vendor, .env), run the generation command, and unzip the result to verify. This exercises the headline feature of v2.3 and the Windows ZIP fix in one pass.
• Look next at the templates directory and Init.php stub. Templates were refreshed in this release (tab()->addButton(), extends, deprecation cleanups), so reviewing them tells you what generated code will look like before you commit to a scaffold.

Implementation Patterns

• .zipignore as the canonical exclusion mechanism. Keep one .zipignore per project (or per generated artefact) rather than passing ad-hoc exclude flags. It now supports glob patterns properly, so patterns like **/*.log, storage/framework/**, and *.sqlite behave as expected. Use negative patterns (!important.log) sparingly and place them after the broad exclusion they re-include.
• Treat warnings as a first-class signal. The new warnings system surfaces problems during generation instead of silently producing a broken ZIP or stale scaffold. Wire it into CI (non-zero exit or a grep over output) so a warning fails the build before a bad artefact ships.
• CI-first workflow commands. With dedicated commands to manage and run GitHub Actions workflows, the pattern is to let the package own .github/workflows/*.yml rather than hand-editing. Manage the workflow set from the package, run it locally to validate, then let GitHub execute it — this keeps local and CI definitions from drifting.
• Generate AI agent docs alongside code. Run the AI-agent documentation command whenever the scaffold structure changes (new command, new template, new config key). Regenerating docs in the same PR as the structural change prevents the agent-facing instructions from describing a package that no longer exists.
• Keep calculators in sync deliberately. The calculators updater is a migration mechanism for the calculator definitions. Run it after upgrading the package, review the diff, and commit — do not let it run implicitly at boot, or upgrades become non-reproducible.
• Template forking pattern. If you need to diverge from the shipped templates, publish them into your own namespace and keep the override minimal. The v2.3 template refresh means a heavily customised copy will drift fast; prefer small, targeted overrides of individual stubs over wholesale copies.

Gotchas and Tips

• Regenerate, don't patch, stale scaffolds. v2.3 updates templates to drop tab()->addButton() in favour of the current API and removes deprecated extends usage. Any project generated before v2.3 will still contain the obsolete calls — regenerate into a scratch directory and diff against your existing code rather than hand-porting blind.
• Windows ZIP creation was broken and is now fixed. If your pipeline previously produced malformed or empty archives on Windows runners, remove any workarounds (shelling out to a system zip, WSL steps) before upgrading, or you will double-apply the fix and mask regressions.
• .zipignore glob semantics changed. The glob matching fix can alter which files are included. Compare the file list of a ZIP produced before and after the upgrade on a representative project — silent inclusion of .env or vendor/ is the failure mode worth catching.
• Init.php indentation fix is cosmetic but diff-noisy. Regenerating will reformat empty function bodies. Isolate that change in its own commit so it does not obscure real logic changes in review.
• Warnings are advisory unless you make them fatal. By default they likely report and continue. Decide explicitly per project whether a warning should abort generation, and configure that rather than relying on developers reading scrollback.
• Extension points: config file for paths and exclusions, publishable templates for generated output, and the warnings system for custom validation hooks. Prefer hooking validation into the warnings system over post-processing the generated ZIP.
• Debugging a bad archive: unzip to a temp directory and list contents (unzip -l) rather than opening the generated ZIP in an editor — the most common issues are path separators (Windows legacy) and glob over-matching, both visible immediately in the listing.