Form Bundle Laravel Package

Getting Started

This is an early-stage package (v0.1.1), so start by confirming the exact install name from the release/README, then add it to your Laravel app:

composer require vendor/package

Publish any package assets and run migrations:

php artisan vendor:publish --tag=package-config
php artisan vendor:publish --tag=package-migrations
php artisan migrate

Look first at:

1. README.md — especially the v0.1.1 notes on hidden entities and predefined entity types.
2. The published config file — type definitions, entity discovery, and visibility defaults.
3. The package’s base Entity class/model and migration stubs.
4. The package tests — with a 0.x release, tests are often the most accurate API documentation.

Your first use case should be small: create one entity, confirm that it receives its predefined type automatically, and toggle it between visible and hidden. For example:

$entity = Entity::create([
    'name' => 'Example',
]);

// v0.1.1: every entity gets a predefined type.
$entity->type;        // expected predefined type
$entity->isHidden();  // visibility helper/flag
$entity->hide();      // mark hidden

Do not build a large domain model on top of 0.1.x until you have verified the exact method names, type constants, and persistence behavior in your app.

Implementation Patterns

Treat predefined types as package-owned metadata

v0.1.1 introduces a predefined type for every entity. Prefer reading and filtering by that type rather than setting it manually:

$entities = Entity::query()
    ->where('type', EntityType::ARTICLE) // use the package constant/enum
    ->get();

If your app needs custom categorization beyond the package type, keep that in a separate column or relation. Avoid overloading the predefined type with application-specific semantics; it is likely intended to be stable and package-defined.

Use hidden entities as a presentation concern, not an authorization boundary

“Entity hidden” is useful for excluding entities from default listings, navigation, or public APIs. Implement it consistently through scopes/resources:

// Public listing
$entities = Entity::query()
    ->where('hidden', false)
    ->get();

// Admin listing
$entities = Entity::query()->withHidden()->get();

Wrap visibility rules in a query scope or repository method so hidden behavior does not get duplicated across controllers, API resources, and Blade views. If the package exposes an isHidden() or equivalent helper, use that in policies and resources rather than checking raw attributes directly.

Keep entity creation centralized

Because every entity now receives a predefined type, centralize creation through a service, action, or factory. That gives you one place to adapt if the package changes type assignment behavior in later 0.x releases:

class CreateEntity
{
    public function handle(array $data): Entity
    {
        return Entity::create($data);
    }
}

This is especially useful if you seed data, import records, or create entities from multiple entry points.

Integrate with Laravel’s usual layers

• Form Requests: validate user-supplied fields, but do not accept the predefined type from request input unless the package explicitly supports it.
• API Resources: expose type and hidden deliberately; decide whether hidden entities should be omitted entirely or returned with a visibility flag.
• Policies: use entity visibility in view/viewAny policies where hidden entities should not be visible to certain users.
• Seeders/Factories: assert that seeded entities have the expected predefined type; add tests that cover hidden and visible states.
• Admin tooling: provide an explicit “show hidden” toggle rather than relying on implicit default query behavior.

Test the v0.1.1 behavior explicitly

Add small feature tests around the two new behaviors:

it('assigns a predefined type to every entity', function () {
    $entity = Entity::factory()->create();

    expect($entity->type)->not->toBeNull();
});

it('can hide an entity', function () {
    $entity = Entity::factory()->create();

    $entity->hide();

    expect($entity->fresh()->isHidden())->toBeTrue();
});

These tests will catch breaking changes quickly when upgrading within 0.x.

Gotchas and Tips

Early 0.x API instability

v0.1.1 is a very early release. Method names such as hide(), isHidden(), and type constants may change. Pin the package version in composer.json and review release notes before upgrading. Avoid spreading package-specific calls throughout your codebase; isolate them behind scopes, actions, or a small wrapper service.

Hidden is probably not a security feature

Do not assume “hidden” means “inaccessible.” A hidden entity may still be retrievable by ID, route binding, or an unscoped query. Enforce access control with Laravel policies, middleware, and explicit query scopes. In particular, check whether route model binding respects the hidden flag; if not, add a policy check or a scoped bind.

Predefined types may be immutable or overwritten

If the package assigns a type on creation, manually setting type may be ignored, overwritten, or rejected. Use the package’s predefined constants/enums and avoid writing arbitrary strings into the type column. If you need application-level categorization, add your own column rather than fighting the package’s type system.

Existing data after upgrading

If you are upgrading from an earlier 0.1.x version, entities created before v0.1.1 may not have the new predefined type. Check whether the package ships a migration or backfill command. If not, plan a backfill and add a test that all existing entities have a valid type. Similarly, confirm the default value of the hidden flag for existing rows.

Config and cache quirks

After publishing config or upgrading, clear cached config:

php artisan config:clear
php artisan optimize:clear

If entity discovery or predefined types are config-driven, a stale config cache can make new types appear missing. In production, ensure deploy scripts run config:cache after the new config is in place.

Debugging visibility and type issues

When an entity is unexpectedly visible or hidden, inspect the raw attributes and the package’s query scopes:

dump($entity->getAttributes());
dump(Entity::query()->toSql());

Check for:

• A global scope that filters hidden entities.
• A cast that converts the hidden flag or type incorrectly.
• Route model binding bypassing the package scope.
• Factories or seeders explicitly setting visibility/type.

When a type looks wrong, confirm whether it was assigned by the package or supplied manually, and check the exact predefined type values in the package source or config.

Extension points to prefer

Use package-supported extension points where available: custom entity classes, config-driven type definitions, published migrations, model events, query scopes, and API resources. Avoid modifying vendor files. If the package lacks an extension point for your use case, wrap it in your own service or repository so you can replace it later.

Upgrade checklist for future releases

For each new 0.x release:

1. Read release notes for changes to hidden-entity behavior and predefined types.
2. Run the package test suite plus your own visibility/type tests.
3. Check migrations and backfills for existing entities.
4. Clear config and application caches.
5. Verify public and admin listings, API resources, policies, and route binding.