README

Lyre Facet is a lyre/lyre add-on for tagging and organizing records with reusable facets and facet values.

It provides three core models:

Facet: the taxonomy group, such as Blog Category, Task Categories, or Subscription Plan Category
FacetValue: a concrete value inside a facet, such as Free or Main
FacetedEntity: the polymorphic pivot that links any facetable model to a facet value

How It Works

Tagging models

Any model can become facetable by using Lyre\Facet\Concerns\HasFacet.

That trait adds:

facetedEntities() morph-many relation to the pivot table
facetValues() has-many-through relation to attached values
attachFacetValues($ids) helper to replace all current facet assignments

This is how Aspire tags exams, assessments, tasks, subscription plans, and articles.

Hierarchies

Both Facet and FacetValue support optional parent/child hierarchy through parent_id.

The package exposes:

parent()
children()
ancestors()
descendants()
roots() scope

Repositories for Facet and FacetValue use HasHierarchy, which powers:

GET /api/facets/hierarchy/{facetId?}
GET /api/facetvalues/hierarchy/{facetValueId?}

facetvalues/hierarchy also accepts a facet query parameter so clients can scope root values to a specific facet.

Resource behavior

Facet uses slug as ID_COLUMN
FacetValue uses slug as ID_COLUMN
both expose lightweight computed fields such as parent_name and facet_name
hierarchy endpoints return nested arrays with a depth field

Installation

composer require lyre/facet

Publish assets:

php artisan vendor:publish --provider="Lyre\Facet\Providers\LyreFacetServiceProvider"

If you use Filament, register the plugin:

use Lyre\Facet\Filament\Plugins\LyreFacetFilamentPlugin;

$panel->plugins([
    new LyreFacetFilamentPlugin(),
]);

Example Usage

Add the trait to a model:

use Lyre\Facet\Concerns\HasFacet;

class Article extends Model
{
    use HasFacet;
}

Attach facet values:

$article->attachFacetValues([$newsId, $featuredId]);

Query tagged models through normal Lyre relation filters:

GET /api/articles?relation=facetValues,featured

Or scope dynamic section data in lyre/content using the facet filter, which resolves all values under a named facet and constrains the target model to those values.

Aspire Usage Notes

In Aspire, the package is used for:

blog article categories
exam categories
task categories, including the Free task flow
subscription plan categories, including the Main plan flow

Good examples to inspect:

app/Models/Assessment.php
app/Models/Exam.php
database/seeders/FacetSeeder.php
database/seeders/TaskSeeder.php
app/Filament/Resources/AssessmentResource.php
app/Filament/Resources/ExamResource.php

Limits To Keep In Mind

attachFacetValues() is a replace-all helper, not an additive sync helper
facet-based filtering depends on models exposing the facetValues relation
hierarchy support is implemented only where the repository explicitly uses HasHierarchy

lyre / facet

Maintainers

Package info

Statistics

Security