Modules Laravel Package

Getting Started

1. Install and pin the version. This is a 0.1.x package, so treat the API as unstable. Require it with a tight constraint (^0.1.1) and read the changelog before every minor bump.

2. Publish the config first. Run the package’s publish command (typically php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" or a specific --tag=config). Release 0.1.1 fixes config publishing, so if a previous publish silently produced no config file, upgrade and republish before debugging anything else.

3. Read config/<package>.php before writing code. The important knobs are the stub path, migration settings, and tenant connection/identifier options. This file tells you what the package expects more reliably than the README.

4. Pick one first use case. Either:

   • Customize a stub and generate a file, or
   • Run the package’s migration command with --tenant=<identifier> against a single tenant.

   The tenant migration path is the fastest way to confirm the package is wired to the right database connection.

Implementation Patterns

Stub customization as a first-class workflow. With the more flexible stub system in 0.1.1, publish stubs into your app (e.g. stubs/vendor/<package>) and point the config’s stub path there. Keep customized stubs in version control. Only override the stubs you actually change; let the package defaults handle the rest so upgrades stay small.

Config publishing per environment. Publish the config into config/ and drive values through .env. Do not edit files under vendor/. In CI, run the publish step during build/setup, then php artisan config:clear so the new file is picked up.

Tenant migrations in deploy scripts. Use the new --tenant option to migrate one tenant at a time. A typical deploy loop creates or selects a tenant, runs the package migration command with --tenant=<id>, checks the exit code, and moves on. Run central/shared migrations before tenant migrations. For local development, provision a single test tenant and migrate just that one rather than looping all tenants.

Custom artisan wrappers. If the package’s command signature is still settling, wrap it in your own command (e.g. tenants:migrate-all) that enumerates tenants and calls the package command per tenant. That isolates your deploy scripts from future signature changes.

Testing. Use the package’s test stubs if provided, assert generated files after running generators, and migrate a dedicated test tenant in setUp(). Keep central and tenant database setup separate so failures point to the right connection.

Provisioning integration. Trigger tenant migrations from your tenant-created/provisioned event or job, not only from manual CLI runs. That keeps new tenants consistent with existing ones.

Gotchas and Tips

• vendor:publish does not overwrite existing files. If you published a broken/partial config before 0.1.1, the fixed version will not replace it. Delete the old config (or use --force deliberately) and diff before committing.
• Config cache hides published changes. After publishing or editing config, run php artisan config:clear (and config:cache in production). A stale cache looks exactly like “the publish bug is still there.”
• Stub changes are not retroactive. Editing a stub only affects files generated afterward. Regenerate and diff; don’t expect existing generated files to update.
• Tenant option semantics matter. Confirm whether --tenant expects an ID, slug, or domain, and whether it validates existence. Migrating a non-existent tenant can fail late or, worse, fall back to the central connection.
• Watch the connection. Tenant migrations must run on the tenant connection, not the central one. If migrations appear in the wrong database, inspect the config’s connection mapping before touching the command.
• Production safety. Migration commands often prompt for confirmation; use the package’s --force equivalent in deploy scripts and guard against running tenant migrations against the wrong environment.
• Pre-1.0 churn. The stub system and command signatures are the most likely things to change. Pin the version, keep custom stubs minimal, and wrap commands you depend on.
• Extension points. Prefer published stubs and config over subclassing package classes. Stub overrides survive upgrades better than inheritance from internal classes.