Download the PHP package aliziodev/laravel-taxonomy without Composer

Laravel Taxonomy

Laravel Taxonomy is a flexible and powerful package for managing taxonomies, categories, tags, and hierarchical structures in Laravel applications. Features nested-set support for optimal query performance on hierarchical data structures.

📖 Documentation

• 🇺🇸 English Documentation
• 🇮🇩 Dokumentasi Bahasa Indonesia

📋 Table of Contents

• Overview
• Key Features
• Requirements
• Installation
• Configuration
• Quick Start
• Basic Usage
• Hierarchical Data & Nested Sets
• Metadata Support
• Bulk Operations
• Caching & Performance
• Custom Taxonomy Types
• Real-World Usage Scenarios
• Advanced Features
• Best Practices
• Custom Slugs and Error Handling
• Troubleshooting
• Security
• Testing
• License

Overview

This package is ideal for:

• E-commerce category management
• Blog taxonomies
• Content organization
• Product attributes
• Dynamic navigation
• Any hierarchical data structure

Key Features

Core Functionality

• Hierarchical Terms: Create parent-child relationships between terms
• Metadata Support: Store additional data as JSON with each taxonomy
• Term Ordering: Control the order of terms with sort_order
• Polymorphic Relationships: Associate taxonomies with any model
• Multiple Term Types: Use predefined types (Category, Tag, etc.) or create custom types
• Composite Unique Slugs: Slugs are unique within their type, allowing same slug across different types
• Bulk Operations: Attach, detach, sync, or toggle multiple taxonomies at once
• Advanced Querying: Filter models by taxonomies with query scopes

Nested Set Features

• Tree Navigation: Efficient ancestor and descendant queries
• Tree Manipulation: Move, insert, and reorganize tree nodes
• Depth Management: Track and query by hierarchy depth
• Tree Validation: Maintain tree integrity automatically
• Efficient Queries: Optimized database queries for hierarchical data

Performance & Scalability

• Caching System: Improve performance with built-in caching
• Database Indexing: Optimized indexes for fast queries
• Lazy Loading: Efficient relationship loading
• Tree Structure: Get hierarchical or flat tree representations
• Pagination Support: Paginate results for better performance

Developer Experience

• Intuitive API: Clean and expressive syntax
• Comprehensive Documentation: Detailed guides and examples
• Type Safety: Full support for Laravel's type system
• Testing Support: Built-in testing utilities

Requirements

• PHP 8.2+
• Laravel 11.0+ or 12.0+
• Composer 2.0+

Installation

Via Composer

Publish Configuration and Migrations

You can publish the configuration and migrations using the provided install command:

Or manually:

Run Migrations

⚙️ Configuration

After publishing the configuration file, you can customize it in config/taxonomy.php. Here's a detailed explanation of each option:

Configuration Options Explained

Table Names

Customize database table names if you need to avoid conflicts or follow specific naming conventions:

Morph Type

Choose the appropriate morph type based on your model's primary key:

Custom Types

Extend or replace the default taxonomy types:

Slug Configuration

Control slug generation behavior:

Important: Composite Unique Constraint

Starting from version 2.3.0, slugs are unique within their taxonomy type, not globally. This means:

• ✅ You can have slug: 'featured' for both Category and Tag types
• ✅ Better flexibility for organizing different taxonomy types
• ⚠️ Breaking Change: If upgrading from v2.2.x, see UPGRADE.md for migration instructions

🚀 Quick Start

Get up and running with Laravel Taxonomy in minutes:

1. Create Your First Taxonomy

2. Associate with Models

3. Query and Filter

📖 Basic Usage

Working with the Taxonomy Facade

The Taxonomy facade provides a clean, expressive API for all taxonomy operations:

Working with Model Relationships

Once you've added the HasTaxonomy trait to your models, you get access to powerful relationship methods:

Query Scopes for Filtering

Filter your models using powerful query scopes:

Scope Chaining vs Single Scope with Type

With the composite unique constraint, you have two approaches for filtering:

Pagination Support

The package supports pagination for search and find methods:

Complete Controller Example

Here's a comprehensive example of using Laravel Taxonomy in a controller:

🌳 Hierarchical Data & Nested Sets

Laravel Taxonomy uses the Nested Set Model for efficient hierarchical data management:

Understanding Nested Sets

The nested set model stores hierarchical data using lft (left) and rgt (right) values, along with depth for each node. This allows for efficient querying of hierarchical relationships.

Tree Operations

📊 Metadata Support

Store additional data with each taxonomy using JSON meta:

🔄 Bulk Operations

Efficiently manage multiple taxonomy relationships:

Basic Bulk Operations

Advanced Bulk Management

⚡ Caching & Performance

Laravel Taxonomy includes intelligent caching for optimal performance:

Automatic Caching

Manual Cache Management

Performance Tips

🏷️ Custom Taxonomy Types

While the package comes with predefined taxonomy types in the TaxonomyType enum (Category, Tag, Color, Size, etc.), you can easily define and use your own custom types.

Defining Custom Types

There are two ways to use custom taxonomy types:

1. Override the types configuration

You can override the default types by modifying the types array in your config/taxonomy.php file:

2. Use custom types directly

You can also use custom types directly in your code without modifying the configuration:

Creating a Custom Type Enum

For better type safety and organization, you can create your own enum for custom types:

Then use it in your code:

🎯 Real-World Usage Scenarios

For comprehensive examples of how to use Laravel Taxonomy in real-world applications, please refer to our detailed scenario documentation:

Available Scenarios

1. E-commerce Product Catalog - Building a comprehensive e-commerce platform with hierarchical categories, product tags, dynamic navigation, and advanced filtering.

2. Content Management System - Creating a flexible CMS with content categorization, tagging, filtering, and SEO optimization.

3. Learning Management System - Developing an educational platform with courses, skills, difficulty levels, and personalized learning paths.

4. Multi-tenant Business Application - Building a SaaS platform with tenant-specific taxonomies, project management, and customizable workflows.

5. Analytics and Reporting - Implementing comprehensive analytics, reporting dashboards, and automated insights using taxonomy data.

Each scenario includes:

• Complete code examples
• Database setup and migrations
• Controller implementations
• Service layer patterns

🚀 Advanced Features

🔄 Nested Set Model

Laravel Taxonomy uses the Nested Set Model for efficient hierarchical data management:

Performance Optimization

Caching Strategies:

Eager Loading for Performance:

Advanced Querying

Complex Taxonomy Filters:

Data Import/Export

Import/Export Functionality:

📋 Best Practices

1. Taxonomy Design Principles

2. Metadata Best Practices

3. Performance Optimization

4. Error Handling and Validation

5. Testing Strategies

Custom Slugs and Error Handling

The package provides robust error handling for slug generation and uniqueness:

Manual Slug Management

When slugs.generate is set to false in the configuration, you must provide slugs manually:

Slug Uniqueness (Composite Unique)

Starting from v3.0, slug uniqueness is enforced within the same taxonomy type (composite unique constraint):

Duplicate Slug Detection

Exception Handling

The package provides the following exceptions:

• MissingSlugException: Thrown when a slug is required but not provided
• DuplicateSlugException: Thrown when a slug already exists and a unique slug is required

You can catch these exceptions to provide custom error handling:

Troubleshooting

Common Issues

Taxonomy Not Found

If you're having trouble finding a taxonomy by slug, make sure the slug is correct and consider using the exists method to check if it exists:

Relationship Issues

If you're having trouble with relationships, make sure you're using the correct morph type in your configuration. If you're using UUIDs or ULIDs for your models, make sure to set the morph_type configuration accordingly.

Cache Issues

If you're not seeing updated data after making changes, you might need to clear the cache:

Security

The Laravel Taxonomy package follows good security practices:

• It uses prepared statements for all database queries to prevent SQL injection
• It validates input data before processing
• It uses Laravel's built-in protection mechanisms

If you discover any security issues, please email the author at [email protected] instead of using the issue tracker.

Testing

The package includes comprehensive tests. You can run them with:

📝 Automatic Changelog

This package uses automated changelog generation based on Conventional Commits and Semantic Versioning.

How It Works

• Commit Analysis: Every commit message is analyzed to determine the type of change
• Automatic Versioning: Version numbers are automatically determined based on commit types
• Changelog Generation: CHANGELOG.md is automatically updated with release notes
• GitHub Releases: Releases are automatically created with detailed release notes

Commit Message Format

Examples:

Release Types

Automated Workflows

• Auto Changelog: Triggered on every push to main branch
• Commitlint: Validates commit messages on PRs and pushes
• Release Creation: Automatically creates GitHub releases with changelogs

Contributing

Please see CONTRIBUTING for details on our automated changelog system and development workflow.

License

The Laravel Taxonomy package is open-sourced software licensed under the MIT license.