Platform Laravel Package

Getting Started

Install the package with Composer, publish its config and migrations, then run migrations:

composer require norialabs/platform
php artisan vendor:publish --tag=platform-config
php artisan vendor:publish --tag=platform-migrations
php artisan migrate

Start by reading config/platform.php, the package service provider, and the rebuild entry point (php artisan list will show the exact command name, commonly something like platform:rebuild). Your first use case should be a disposable local environment: define one platform resource in config, run the rebuild command, inspect the created records, then change the definition and rebuild again. In v0.1.13, the second rebuild is the important one—removed definitions are retired and their prior records are archived rather than hard-deleted.

Implementation Patterns

Treat platform definitions as declarative source code and the rebuild command as the reconciliation step. Keep definitions in config or a dedicated service provider, commit them, and run the rebuild as part of deployment after migrations.

Typical workflow:

1. Add or change a definition.
2. Run the rebuild command in local/CI.
3. Verify created, updated, and archived records.
4. Run the same rebuild in staging/production as a deploy step.

Use the package’s managed records as read-only from application code. If you need extra metadata, store it in a separate table or a custom field that the rebuild will not overwrite. For queries against platform-managed models, explicitly decide whether archived records should be included. Prefer a package-provided scope if one exists; otherwise filter on the archive column (for example whereNull('archived_at')).

Integration tips:

• Run rebuild inside a transaction where possible, and take a database backup before the first production rebuild.
• Add a rebuild smoke test using RefreshDatabase: define a resource, rebuild, remove it from the definition, rebuild again, and assert the record is archived rather than missing.
• If your admin UI lists platform records, add an “archived” filter or exclude archived rows by default so retired definitions do not appear as active.
• Use events or model observers if the package emits them on archive; otherwise poll the archive column in cleanup jobs.

Gotchas and Tips

The v0.1.13 behavior is the main pitfall: a rebuild no longer deletes records that are absent from the new definition—it archives them. Code that assumed hard deletion may now find stale rows. Audit unique indexes and lookups that do not account for archived records.

Common issues:

• Unique constraints: an archived record may still occupy a unique key. Check whether the package restores the archived row or expects you to include the archive column in the index.
• Foreign keys: archived records may still be referenced. Do not add cascading deletes that bypass the package’s archive behavior.
• Stale references: menus, permissions, roles, or settings that point at an archived platform record may resolve unexpectedly. Add explicit “active only” filters where needed.
• Idempotency: rebuilds should be safe to rerun. Test a no-change rebuild and confirm it does not archive or duplicate records.
• Ordering: definitions with dependencies may need deterministic rebuild order; check the package docs or command options.
• Debugging: inspect the archive column and package logs after a rebuild. If the command supports --dry-run, use it in production first.
• Extension points: publish and override config, custom archive handling, model scopes, or command options rather than patching vendor code.

Before upgrading existing environments, review any code that queries platform tables and add archive-aware scopes. Then run a rebuild in staging and compare active versus archived counts.