Filament Tweaks Laravel Package

Getting Started

Install and verify the source first. The composer name (dowhile/filament-tweaks) and the repository owner (zvizvi) differ, so confirm you are pulling the intended code before adopting it:

composer require dowhile/filament-tweaks
composer show dowhile/filament-tweaks   # confirm repo URL, version, and Filament constraint

Where to look first, in order:

1. README.md — the tweak list is the actual API surface; treat it as the spec.
2. composer.json — the filament/filament version constraint tells you whether this targets Filament v2 or v3. Match it to your app before anything else.
3. config/filament-tweaks.php (if shipped) — most "tweaks" packages are config-flag driven; the config file is the map of every behavior you can flip.
4. src/ — look for ServiceProvider, traits, and any Macroable::mixin() calls. That tells you whether tweaks are global (config), per-panel (provider), or per-resource (trait).

Publish the config if one exists:

php artisan vendor:publish --tag="filament-tweaks-config"

First real use case: pick one low-risk, visible tweak from the README — for example a navigation or UI default you'd otherwise override by hand in every panel — enable only that flag, and confirm it in the browser. Starting with a single toggle makes it obvious whether the package's boot logic is actually running in your panel.

Implementation Patterns

Config-flag toggling (the common case). Most tweak collections expose each behavior as a boolean in the published config. Keep changes centralized and documented:

// config/filament-tweaks.php
return [
    'disable_sidebar_collapse' => true,
    'compact_tables'           => env('FILAMENT_TWEAKS_COMPACT', false),
];

Gate environment-specific tweaks with env() so local and production diverge intentionally, not accidentally.

Panel-provider integration. If the package exposes a plugin or a static setup call, register it inside your AdminPanelProvider::panel() rather than in AppServiceProvider. This keeps the tweak scoped to the panel that needs it and avoids surprising other panels (e.g., a customer-facing panel) that share the app.

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentTweaksPlugin::make())
        // ...
}

Resource-level opt-in via traits. When tweaks affect forms/tables, the package will likely ship traits you apply per resource. Prefer this over global config when only a handful of resources should change — it keeps blast radius small and makes git grep audits trivial.

use Dowhile\FilamentTweaks\Concerns\CompactTable;

class OrderResource extends Resource
{
    use CompactTable;
}

Macro registration. If the package registers macros on Filament components, treat them like any other macro: call them from resource/table definitions and assert their presence in a test (Table::hasMacro('...')). Macros are the safest integration point because they don't require subclassing.

Wrap, don't fork. For a package this young (1 star, 0 dependents), the durable pattern is to consume its public config/macros and keep your own thin base classes (App\Filament\Resources\BaseResource) where you re-apply the behavior. If the package stalls, you delete one line and your base class still carries the logic.

Test the behavior, not the package. Add a Livewire/Filament test that asserts the user-visible outcome (e.g., a column is hidden, a button is absent). That test survives a package swap.

Gotchas and Tips

• Treat maturity as a risk, not a detail. One star and zero dependents means almost no community vetting. Read src/ end to end before production; pin the exact version in composer.json and avoid ^ ranges until you've reviewed the diff of the next release.
• Filament major-version mismatch is the #1 failure mode. Filament v3 changed panel/provider APIs substantially from v2. If the package's constraint doesn't match your app's, expect silent no-ops rather than errors — the tweak simply never registers.
• Config and view caches hide changes. After editing the config or publishing views:

  php artisan config:clear
  php artisan view:clear
  php artisan filament:assets   # if the package ships assets
  

  A tweak that "doesn't work" in staging but works locally is almost always config:cache.
• Boot-order conflicts. Tweaks that hook the same Filament lifecycle event (navigation, render hooks) can fight with other packages or your own boot() overrides. If a tweak stops working after adding another package, check provider registration order and whether both mutate the same singleton.
• Debugging registration. Confirm the service provider is discovered (php artisan about lists it), then dump inside its boot() or check Macroable::hasMacro() to see whether the macro path is live. For config-driven tweaks, config('filament-tweaks') in tinker immediately reveals whether the file is published and loaded.
• Don't rely on undocumented flags. If the README doesn't describe a key in the config file, it may be a leftover or internal. Only enable documented options; anything else is an unversioned private API.
• Extension points that stay safe: published config, published views (override in resources/views/vendor/...), and macros. Avoid subclassing package internals — those classes are the most likely to change without notice.
• Exit strategy. Because the surface area is small, keep the tweaks you actually depend on listed in your project README with the file/line that implements them. That list is your migration plan if the package goes unmaintained.