Customising Martis Generators

Every Martis make-command (martis:resource, martis:action, martis:lens, martis:tool and the rest) renders a class from a .stub template in the package. This page shows how a project overrides those templates in stubs/martis/.

The defaults aim for "drop-in" with sane Laravel-style headers and docblocks. Once a project has its own conventions (custom file headers, opinionated docblocks, organisation imports, project-specific traits) the default stubs become a friction point.

martis:stubs publishes every template into stubs/martis/ so consumers can edit them in place.

Stub overrides vs component overrides. This page is about scaffolding — the source code emitted once when you run php artisan martis:resource Foo. It does not affect runtime rendering. To swap a React component the panel uses live, see the Override System (componentRegistry, layoutRegistry).

Quick start

php artisan martis:stubs

Output (truncated; the package ships 60 stubs):

  resource.stub ............................................... PUBLISHED
  action.stub ................................................. PUBLISHED
  action.destructive.stub ..................................... PUBLISHED
  lens.stub ................................................... PUBLISHED
  ...
 
  60 stubs published; 0 skipped. Edit them in stubs/martis/ to customise generator output.

When you re-run with --force, the status column reads OVERWRITTEN instead of PUBLISHED so the overwrite is visible in the log.

The folder is created at base_path('stubs/martis/'). From now on every martis:* make-command reads its template from there first via StubResolver::path(), falling back to the package default only if the override file is missing.

What gets published

martis:component types

martis:component accepts a --type= flag and resolves a dedicated stub per type. The stub-resolver fallback to component-generic.tsx.stub keeps the command working when --type= is omitted or unrecognised.

Install / SSO / Roles stubs

martis:stubs also publishes the templates that martis:install, martis:sso, and martis:roles use to write migrations + helper classes:

Since v1.8.8 these all route through StubResolver::path(), so editing the published copy in stubs/martis/ produces a custom output exactly like the regular generators. Caveats: the migrations describe schema Martis depends on at runtime — change column names or types only if you also update the matching app code, and re-run martis:install after. Because the copies in stubs/martis/ win, an upstream fix to one of these stubs (for example a migration correction) does not reach your installs until you re-publish it with martis:stubs --force or delete your copy. The extension scaffold (stubs/extensions/*: the Vite config, the tsconfig files, index.ts and the shims) is not override-aware: martis:install always reads it from the package (StubResolver::packagePath()).

Editing a stub

php artisan martis:stubs
nano stubs/martis/resource.stub        # edit
php artisan martis:resource Order       # output reflects the edits

No cache to clear, no rebuild, no restart. The generator reads the file from disk every invocation.

Stubs use simple {{ placeholder }} substitution, the same syntax Laravel core uses. Keep the placeholders intact unless you also customise the generator class.

Re-publishing after a package upgrade

When a Martis upgrade adds new generators or changes a stub shape, the new templates ship in the package but are not auto-copied into your stubs/martis/. Two options:

1. Keep your customisations. Run php artisan martis:stubs again; existing files are skipped (output: SKIPPED). New stubs from the upgrade are added. Then manually port any upstream changes you care about.
2. Reset to the latest defaults. Run php artisan martis:stubs --force to overwrite every file with the latest package default. Use a clean working tree so the diff is reviewable in git.

php artisan martis:stubs           # additive: skip existing, copy new
php artisan martis:stubs --force   # destructive: overwrite everything

Internals — Martis\Stubs\StubResolver

Every make-command resolves its stub through:

\Martis\Stubs\StubResolver::path('resource.stub');

The resolver exposes three static methods:

If you ship a custom artisan command of your own, the same resolver gives you the override-aware path:

use Martis\Stubs\StubResolver;
 
protected function getStub(): string
{
    return StubResolver::path('my-custom.stub');
}

You publish your own stubs into stubs/martis/ from your own service provider's boot() if you want them to participate in the same flow.

Removing customisations

Drop the override file from stubs/martis/ and the resolver falls back to the package default on the next run. Removing the entire folder reverts everything.

rm -rf stubs/martis/                   # full reset
rm stubs/martis/resource.stub          # revert just one