Tag Bag Laravel Package

Getting Started

• Install with composer require setono/tag-bag. Version 2.5.0 requires PHP 8.2+, so it pairs naturally with Laravel 11+ but drops PHP 8.0/8.1 environments still common on Laravel 9/10.
• There is no Laravel service provider in this package. Treat it as a framework-agnostic PHP library and wire it yourself.
• First places to look: TagBagInterface, TagBag, and TagInterface in src/, plus the concrete tag classes shipped by the package. Those define what you can add and how rendering works.
• First use case: collect tags during a request and render them once in your Blade layout. A minimal setup is to bind the bag in AppServiceProvider:

use Setono\TagBag\TagBag;
use Setono\TagBag\TagBagInterface;

public function register(): void
{
    $this->app->scoped(TagBagInterface::class, TagBag::class);
}

Then render it in your layout:

<head>
    {!! app(\Setono\TagBag\TagBagInterface::class)->render() !!}
</head>

If the core API differs slightly, follow the TagBagInterface contract in src/ rather than assuming Symfony bundle docs apply directly.

Implementation Patterns

• Request-scoped bag, not singleton. Bind with scoped() so tags do not leak between requests under Laravel Octane or long-running workers. A singleton is convenient in tests but dangerous in production.
• Blade partial for rendering. Keep raw rendering in one layout partial, e.g. resources/views/partials/tags.blade.php, rather than scattering {!! ... !!} calls across views. This makes it easy to add position-specific rendering later if the bag supports separate sections or priorities.
• Facade or helper for ergonomics. If you add tags from many controllers/services, create a small facade or helper around TagBagInterface so application code does not depend directly on the package namespace.
• Custom tags via TagInterface. When built-in Script, Style, Meta, or similar tag classes do not cover your markup, implement TagInterface for your own tag type and add it to the bag. This is the main extension point.
• Deduplication by key. If tags expose keys or identifiers, use them to avoid injecting the same analytics or tracking script twice when multiple components add tags.
• Testing pattern. In feature tests, resolve TagBagInterface from the container, add a tag, perform the request, and assert the rendered markup with assertSee(..., false). For unit tests, instantiate TagBag directly and assert its rendered output.
• Middleware pattern. If different parts of the app contribute tags conditionally, a middleware can resolve the bag after the response and verify/collect state. Keep this simple; most apps only need controller/service-level additions.

Gotchas and Tips

• PHP 8.2+ is a hard break in v2.5.0. The release is mainly a tooling/runtime upgrade: PHP 8.2 minimum, code-quality-pack 3.1, and PHPStan. There are no new runtime features, but projects on PHP 8.0/8.1 must stay on v2.4.x or upgrade PHP first.
• No Laravel integration is provided. You are responsible for container binding, facade/helper wiring, and Blade rendering. Do not expect Symfony bundle configuration, Twig extensions, or auto-registration to work here.
• Raw output means escaping is your responsibility. Rendering tags with {!! !!} is intentional, but never place untrusted user input into a Script/Style tag. Treat tag content as trusted application markup.
• Watch for duplicate tags. Analytics scripts, meta tags, and pixel snippets are easy to add from multiple places. Use keys, a renderer wrapper, or application-level guards to prevent duplication.
• Octane and queue workers. Because the bag accumulates state, always use a scoped binding. If you resolve it as a singleton, clear it between requests/jobs or tags will bleed across executions.
• Debugging rendering issues. Resolve the bag in tinker or dump it before the layout renders:

dump(app(\Setono\TagBag\TagBagInterface::class));

If tags are missing, confirm the bag is resolved from the container in both the adding code and the Blade layout, and that the layout partial is actually included.

• Dev dependencies are noise for runtime. code-quality-pack and PHPStan changes in v2.5.0 affect package development, not your application. Do not pin or install those just to use the library.
• Version pinning. If your app must support PHP 8.1, constrain setono/tag-bag to ^2.4. For PHP 8.2+ projects, ^2.5 is fine.