User Tag Bundle Laravel Package

Getting Started

This is a 0.0.1 initial release with no changelog beyond the commit link, so treat the first hour as reconnaissance rather than integration. Assume nothing about the API surface until you have read the source.

1. Install and inspect, don't assume:

   composer require tourze/user-tag-bundle
   

   Then immediately read vendor/tourze/user-tag-bundle/composer.json, src/, and any config/, migrations/, or Resources/ directories before writing a single line of application code.

2. Check which framework it actually targets. The -bundle suffix and the tourze/* vendor namespace are conventions from the Symfony ecosystem, not Laravel. Look for:

   • A class ending in Bundle extending Symfony\Component\HttpKernel\Bundle\Bundle → Symfony bundle, not Laravel-native.
   • A ServiceProvider under src/Providers or an extra.laravel.providers key in composer.json → Laravel-native.
   • Symfony\Component\* entries in require → confirms Symfony-first design; you will be wiring things manually.

3. Where to look first, in this order: composer.json (framework + PHP constraints), src/ root (domain model — expect UserTag, UserTagInterface, repository/service classes), migrations/ or Resources/config/doctrine/ (schema shape), tests/ (whether behaviour is pinned down at all).

4. First use case to validate: attach a tag to a user and read it back. If the package ships a UserTag entity/model and a repository, prove that round-trip works inside a Laravel test before building anything on top of it. If the package's persistence layer is Doctrine-based, this round-trip will not work without a bridge — find that out now, not in week two.

5. Have a fallback ready. At 0.0.1, budget for the possibility that a 40-line Eloquent HasTags trait (polymorphic taggables table + Tag model) gets you further than integrating this package. Decide within the first hour.

Implementation Patterns

Wrap the package behind your own contract. Regardless of what it exposes, define App\Contracts\Tagger (or a TagService) and implement it by delegating to the package. Day-to-day code depends on your interface, so a 0.0.2 breaking change or a swap to your own trait is a one-file diff. At this version this is not optional hygiene — it is the main risk control.

Register services explicitly. If there is no Laravel service provider, bind the package's repository/manager in AppServiceProvider:

$this->app->singleton(UserTagRepositoryInterface::class, function ($app) {
    return new UserTagRepository(/* whatever it actually needs */);
});

Prefer explicit constructor wiring over container magic; a 0.0.1 package rarely has sensible defaults.

Publish and own the schema. If the package ships migrations, publish them (php artisan vendor:publish --tag=...) and commit them into database/migrations. Never let a 0.0.x dependency own your production schema silently — you want the table shape reviewable in your own diff, and you want the option of editing it.

Tagging flow for typical features (labels, segments, moderation flags):

• Resolve tags by name through a firstOrCreate-style path so you don't spawn duplicate rows from user input.
• Normalise input (trim, lowercase, slugify) before it reaches the package — do not rely on the package to sanitise.
• Sync semantics: prefer "set the full desired tag list" over incremental add/remove at the call site, so retries and double-submits are idempotent.
• Dispatch tagging in a queued job when a single action touches many users; keep controllers thin.

Read paths: add a query scope or repository method (withAnyTag, withAllTags) in your code that composes the package's filtering. Do not scatter package query API calls across controllers — if the package's filtering is weak or N+1-prone, you want one place to fix it.

Model integration: if the package offers a trait, use it on User; if not, add a thin local relation/trait that calls into your Tagger contract. Either way, keep User free of package-specific method calls in business logic.

Testing pattern: write a single integration test that exercises attach → query → detach against a real (SQLite) database. This is your canary for every future version bump — it will tell you within seconds whether 0.0.2 broke you.

Gotchas and Tips

• 0.0.1 means no backwards-compatibility promise. Pin exactly ("tourze/user-tag-bundle": "0.0.1") and read the diff before every bump. Semver pre-1.0 explicitly permits breakage in patch releases.
• The changelog is empty. The release notes link only to the commit range. There is no stated feature set, no migration guide, and no deprecation policy — all documentation must come from the source and tests.
• "Bundle" ≠ Laravel. If the package is a Symfony bundle, expect DI-extension XML/YAML config, Doctrine entities, and PHP attributes from Symfony — none of which Laravel loads automatically. Auto-discovery will not happen; you are writing the glue. A Doctrine-backed package in an Eloquent app is usually a hard stop.
• Check the dependency tree before committing. composer why tourze/user-tag-bundle and review what it drags in. Auto-generated package families often pull sibling tourze/* packages with their own pins and PHP-version constraints; conflicts with your existing Laravel/Symfony versions surface here, not at runtime.
• Migrations and table prefixes. If the package's migrations use a fixed table name, check it against your existing schema — tags and user_tags are common collision points. Rename on publish.
• Polymorphic type columns. Tag systems usually store a taggable_type. If it stores fully-qualified class names, register Relation::enforceMorphMap() in a service provider before rolling it out, or you will bake FQCNs into rows that break when you refactor namespaces.
• N+1 in tag lists. Any "list users with their tags" screen needs eager loading. Verify the package exposes a relation you can with() on; if it only offers repository calls returning hydrated objects, plan for a manual join or a ->with() on your own model instead.
• Config publishing is worth checking twice. Run php artisan vendor:publish and inspect what appears before editing. A package at this version may publish a config file whose keys don't match what the code reads — the mismatch shows up as silent defaults.
• Debugging approach: when a call returns empty rather than erroring, drop to DB::listen() / query log and confirm the write actually happened. Silent no-ops (missing service binding, unregistered entity, unpublished migration) are the most common failure mode for freshly installed small packages.
• Extension points to prefer: a repository/service interface you can decorate, and an event or two around tag attach/detach. If neither exists, wrap the package so your code has them — that is where audit logging and cache invalidation will need to hook in later.
• Licence and maintenance signal. Confirm the licence file exists and check the repository's test count and last-commit activity. A 0.0.1 with no tests is a prototyping tool, not a dependency to build a core feature on without a fallback plan.