Media Manager Laravel Package

Getting Started

Version 3.0.0 is a UI refresh plus internal cleanup — the public surface is unchanged, so onboarding is the same as any Laravel package with a published config and a web panel.

1. Install the major explicitly so you don't silently resolve to a stale lockfile:

   composer require <vendor>/<package>:^3.0
   

2. Republish config and assets. This is the one step 2.x users must not skip — the frontend was rebuilt from Bootstrap 3 to a modern stack, so old published assets are now dead weight:

   php artisan vendor:publish --provider="<Vendor>\<Package>\ServiceProvider" --force
   php artisan optimize:clear
   

3. Look here first when something is off: the package config file in config/, the published assets directory under public/vendor/, and the package service provider (for the middleware/collector registration order).
4. First use case: enable the package in .env for local only, hit a representative route (one with auth, one query-heavy), and confirm the panel renders with the new UI before wiring it into anything else. If the panel loads with unstyled markup, your assets didn't republish — that's the 3.0 migration failure mode.

Because the release is explicitly "everything else should work as it did before," treat this as a drop-in upgrade with an asset-republish tax rather than a rewrite.

Implementation Patterns

Environment-gated enablement. Keep the package off by default and switch it on per-environment in config rather than in code. This makes CI and production behaviour independent of developer .env files.

Middleware ordering. If you register the package's middleware or collector manually, place it after session/auth middleware but before anything that terminates early (throttling, maintenance-mode checks). A collector that runs before auth sees an unauthenticated user and silently records nothing useful.

Asset strategy in a real app. Two workable approaches:

• Publish to public/vendor/ — simple, but you must remember to --force republish on every major upgrade (exactly the 3.0 case).
• Serve from the package — no republish step, but you lose the ability to tweak the UI. Prefer this for most apps; you only need to publish if you're theming.

Extending rather than forking. Use the package's documented extension points (custom collectors/tabs/panels) registered from a small dedicated service provider — e.g. App\Providers\PackageExtensionsServiceProvider. This survives major upgrades; a forked view does not.

Test-suite isolation. Add an explicit disable in phpunit.xml (<env name="PACKAGE_ENABLED" value="false"/>). The 3.0 UI changes don't affect this, but leaving the package enabled in tests is the most common cause of flaky assertion output and slow suites.

Deploy checklist item. Any release that bumps this package should include an asset republish step in your deploy script. If your deploy runs php artisan vendor:publish --tag=<package>-assets --force idempotently, the 3.0 UI swap is a no-op for you.

Gotchas and Tips

• 3.0.0 is a major bump for a cosmetic-sounding change. Semver-major here signals that published assets and possibly internal config keys changed. Diff your published config against the package's shipped config/<package>.php; if you never published it, you're fine, but confirm with php artisan vendor:publish --help or the package docs.
• Stale published assets are the #1 upgrade bug. Old Bootstrap 3 CSS/JS left in public/vendor/ combined with new markup produces a half-broken panel. Delete the directory and republish rather than merging over it.
• CSS bleed in both directions. If your host app still ships Bootstrap 3, the new UI's styles may collide. Scope it by loading the package assets only on the routes that render the panel, not globally.
• CSP will bite you. A rebuilt frontend usually means new inline styles or scripts. If you run a strict Content-Security-Policy, expect console errors on first load after upgrading — check the browser network/console tab before assuming the package is broken.
• Cached views and compiled assets. php artisan optimize:clear (or at minimum view:clear and config:clear) after the upgrade. On Octane or a long-running worker, restart the workers; they hold the old config in memory.
• Verify it's actually off in production. Check APP_DEBUG and the package's own enable flag together. A package that self-enables on APP_DEBUG is a data-exposure risk if debug is left on.
• Debugging a blank panel: check storage/logs/laravel.log first (collector exceptions are usually swallowed), then confirm the route/middleware is registered via php artisan route:list, then whether assets 404 in the network tab. That order resolves ~90% of cases.
• Extension points over overrides. If you customised 2.x views directly, re-apply those changes against the new markup or, better, migrate to the package's supported extension hooks — the view layer just changed once and will again.