Tag Manage Bundle Laravel Package

Getting Started

tourze/tag-manage-bundle 1.1.0 is a minor release (1.0.2 → 1.1.0), so semver says you can upgrade in place — but the 1.1.0 notes consist only of a changelog link (compare/1.0.2...1.1.0), with no described features, deprecations, or breaking changes. Treat the diff as the source of truth before you plan around anything new.

Minimal steps:

1. Read the actual diff first: https://github.com/tourze/tag-manage-bundle/compare/1.0.2...1.1.0 — scan composer.json for changed constraints (php, symfony/*, doctrine/*) and look for new/renamed classes in src/. For a Tourze bundle, most real behaviour lives in DI extensions and Doctrine entities, not in docs.
2. Install: composer require tourze/tag-manage-bundle:^1.1.
3. Check the framework before anything else. Tourze packages are almost universally Symfony bundles (auto-registered via *Bundle class + DependencyInjection/Extension), not Laravel packages. Confirm with grep -r "Symfony\\\\Component" vendor/tourze/tag-manage-bundle/src | head. If it's Symfony-only, a Laravel integration is a bridging exercise (see Gotchas) — decide that before writing code.
4. Where to look first: src/ for the taggable contract/interface and the tag entity, config/ (or Resources/config/) for the service wiring and the table/pivot names, and README.md for the one usage snippet most Tourze bundles ship.
5. First use case: attach tags to an existing model/entity and read them back — create a tag, associate it via the package's taggable interface or pivot table, then query "all records with tag X". That single flow exercises the contract, the join table, and any repository/service the bundle registers.

Implementation Patterns

Verify before adopting a pattern. Because 1.1.0 ships no notes, diff the public surface (git diff 1.0.2..1.1.0 -- src/) and check whether new methods are additive or whether an interface gained a method (that silently breaks your implementations).

Common shapes for a bundle of this kind:

• Taggable contract on your entities/models. Implement the package's taggable interface (or add its trait) so the bundle's services can read/write tags. Keep the trait on a base model if you have many taggable types.
• Sync vs. append semantics. Tag APIs in this space usually offer both addTag/removeTag and a syncTags(array $names). Prefer an explicit sync in form/API handlers, and normalize tag names (trim, lowercase, collapse whitespace) before they hit the package so you don't get Laravel / laravel duplicates.
• Resolve through the container, don't new. Symfony bundles expect their services (tag manager, repository, form type) to come from the container so the injected EntityManager/connection is correct. Constructor-inject the manager into your own services and let the container wire it.
• Repository-level filtering. Query by tag through the package's repository or a join on its pivot table (typically tag + <entity>_tag). Keep that join behind a query scope/repository method rather than repeating it in controllers.
• Tag input handling. Use the bundle's form type/validator if one exists; otherwise a custom request validator plus a "find or create" step. Wrap tag creation in a transaction when saving a record and its tags together.
• Tag cloud / counts. If you need counts, aggregate in SQL (GROUP BY tag_id) instead of hydrating tags per record. Cache the result (Cache::remember / Symfony cache pool) with short TTL — counts go stale fast and are read far more than written.
• Bulk operations. For imports/re-indexing, batch tag attaches in chunks and flush once per chunk; per-row flush in a bundle that manages its own UnitOfWork is where import jobs die.
• API surface. Expose tags as a separate resource (/tags, /posts/{id}/tags) and accept tag names on write, IDs on read. Keeps clients decoupled from IDs and matches how the package likely stores names.

Gotchas and Tips

• The biggest gotcha is framework mismatch. "Bundle" in the name plus a tourze vendor strongly implies Symfony/Doctrine. In a Laravel app that means no config/tag-manage.php, no facade, and Eloquent models that won't satisfy the taggable contract without an adapter. Options: (a) use it only for a Doctrine-backed sub-domain, (b) write a thin adapter implementing the contract over Eloquent, (c) pick a Laravel-native tagging package instead. Do this triage before estimating the work.
• Doctrine, not Eloquent. Expect entities + EntityManager, migrations generated via doctrine:migrations:diff. In Laravel you won't get php artisan migrate entries for the package tables — replicate the schema (tag, pivot, indexes) by hand and keep it in your own migrations so drift is visible.
• Silent no-op upgrades. With only a changelog link, a minor bump can still change default tag separators, table names, or normalisation. Pin ^1.1 (not *), upgrade in a branch, and diff the schema and DI config after composer update.
• Interface additions break implementors. If 1.1.0 added a method to the taggable interface or a tag-manager contract, your classes fatal at container compile time, not at runtime — which surfaces as a vague "cannot instantiate" or cache-warm failure. Run cache:clear/cache:warmup (or php artisan optimize:clear if bridged) right after upgrading.
• Missing unique constraint = duplicate tags. Confirm a unique index on the tag name and a composite unique on (tag_id, taggable_id, taggable_type). Without them, concurrent requests create duplicates and syncTags quietly doubles rows. Fix in your own migration if the bundle doesn't.
• N+1 on listings. Rendering tags for a list of records is the classic N+1. Eager-load/JOIN FETCH the tag association, or pre-fetch tag maps for the page in one query.
• Tag deletion is a policy decision. Cascading pivot rows vs. blocking deletion of in-use tags — check what the bundle's delete path does (it may leave orphans) and enforce your policy at the service layer, not in controllers.
• Debugging: with a Symfony bundle, debug:container | grep tag (or the bundle's service id prefix) is the fastest way to see what 1.1.0 actually registered; compare that output between 1.0.2 and 1.1.0. For query behaviour, log SQL during a sync and confirm row counts match expectations.
• Extension points worth knowing: the taggable interface/trait (your own taggable types), the repository or manager service (override via a container alias/service decoration rather than editing vendor code), and the form type/validator (swap for your own normalisation rules). If 1.1.0 introduced events or a normaliser hook, that's the cleanest place to centralise slug/case handling.