Taxonomy Laravel Package

Getting Started

Because amethyst/taxonomy has no stars, no dependents, and essentially no community footprint, treat your first hour as due diligence rather than integration.

1. Verify it actually exists and installs. Run composer require amethyst/taxonomy against a throwaway Laravel app before touching anything real. If the package isn't on Packagist, you'll need a VCS repository entry:

   "repositories": [{ "type": "vcs", "url": "https://github.com/amethyst-php/taxonomy" }]
   

2. Read the source before the README. With a zero-star package, the code and tests are the documentation. Look at, in order:

   • composer.json — what it actually depends on (the Amethyst ecosystem is closer to framework-agnostic PHP + a bundled Eloquent-style ORM than to Laravel itself, so you may need bridging code).
   • src/ — the term/taxonomy model classes, the polymorphic relation, and any service provider.
   • tests/ — whether there are meaningful tests at all. If not, assume nothing is guaranteed.

3. Publish and inspect migrations/config (assuming standard Laravel packaging):

   php artisan vendor:publish --provider="Amethyst\Taxonomy\ServiceProvider"
   

   Read the generated migration before running it. Confirm table names won't collide with your own terms, taxonomies, or taggables tables, and check whether foreign keys and indexes are sane for your DB engine.

4. First use case: tag a Post with terms. Wire up the trait/model as the package intends, create a couple of terms, attach them to a model, and read them back. This one smoke test tells you whether the polymorphic relation, the pivot table, and the ORM adapter all work in your Laravel version.

If step 1 or step 4 fails and there's no issue tracker activity to lean on, stop here — you're now maintaining a fork, not adopting a dependency.

Implementation Patterns

Treat the package as a term store, not a category page. The realistic day-to-day pattern is: you own the domain objects (Post, Product, Article), and the package supplies terms, hierarchical organization, and the polymorphic link between them.

• Define taxonomies as data, not code. Create a TermType/taxonomy row per vocabulary (category, tag, topic) rather than separate tables or classes. This keeps querying uniform:

  $categoryTerms = Term::where('taxonomy', 'category')->get();
  $post->terms()->attach($termId);
  

• Guard the polymorphic attach behind a small repository/service. Don't scatter attach() calls through controllers. One TaxonomyService with syncTerms($model, array $ids, string $taxonomy) gives you a single place to validate term-vs-taxonomy membership and to invalidate caches.

• Hierarchy traversal: if terms carry a parent_id, recursive loading is where performance dies. Fetch the whole term set for a taxonomy once (they're usually small), build an in-memory tree, and resolve children there instead of recursing through the ORM.

• Seeding: seed your vocabularies in a dedicated seeder and make it idempotent (updateOrCreate on a slug per taxonomy). Term IDs must be stable across environments if they leak into URLs or config.

• API/form integration: expose terms as slugs/IDs, not display names. When syncing from a form, resolve names→IDs in your service and reject cross-taxonomy IDs before the pivot write.

• Eager loading: whatever the relation method is called, eager-load it on listing pages (->with('terms')) and constrain by taxonomy in the closure to avoid dragging every vocabulary into every response.

• Adapters: because this sits in the Amethyst ecosystem, be prepared to write a thin adapter between its model/collection base classes and Laravel's Eloquent if they aren't the same thing. Keep that adapter in one file so an upstream change is a one-file fix.

Gotchas and Tips

• The zero-star/zero-dependent signal is the headline gotcha. There is no crowd-sourced bug surface, no Stack Overflow corpus, no upgrade path. Budget for reading and patching the source, and consider whether a handful of your own tables plus a HasMany/BelongsToMany would cost less than adopting it.

• Amethyst is not Laravel. Most amethyst-php packages are part of a framework-agnostic stack with their own ORM layer. Eloquent-specific features (accessors, casts, whereHas on the package's relations, model events) may not behave as you expect. Test the exact queries you plan to ship.

• Migration collisions. Generic table names (terms, taxonomies, termables, taggables) are prime conflicts. Rename tables in the published migration up front rather than after data exists.

• Polymorphic integrity. Pivot tables in small packages often lack a taxonomy_id/type discriminator or FK constraints. Add them if you rely on referential integrity, and enforce the "term belongs to the taxonomy I'm attaching under" rule in application code.

• Hierarchy edge cases. Watch for: orphaned parents after deletion, cycles from a bad parent_id update, and depth caps. Deleting a parent term may cascade or may silently orphan — read the delete path before enabling hard deletes.

• Caching. Term sets are read-heavy. Cache terms-by-taxonomy and bust on write through your service layer, not via model events scattered around (you'll miss the package's own writes otherwise).

• Debugging: with no docs, drop into the service provider's boot() and dump the container bindings/aliases it registers. That usually reveals the intended entry points faster than reading classes.

• Extension points: prefer composing around the package (your own service, your own presenter) over subclassing its models. If you must subclass and it ships a service provider with hardcoded class bindings, check whether those bindings are overridable in config; if not, you've found a fork-worthy limitation.

• Exit criteria for abandoning it. Define them now: no tests on the code path you depend on, an unmerged critical bug, or an incompatibility with your Laravel/PHP version you can't patch in a day → replace with a first-party implementation. A package this small is cheap to reimplement; a silent taxonomy bug is not.