Download the PHP package offload-project/laravel-hoist without Composer

Laravel Hoist

Feature discovery and management extension for Laravel Pennant. Automatically discover, manage, and serve feature flags with custom metadata, tags, and routing.

Features

• Automatic discovery — Drop a class into your Features directory; it's picked up without manual registration
• PHP attributes — Declarative metadata via #[Label], #[Description], #[Route], #[Tags], #[FeatureSet]
• Rich FeatureData payload — Structured DTO with label, description, href, active status, tags, and metadata
• Per-user resolution — Hoist::forModel($user) returns every feature with its active status for that scope
• Tag-based filtering — Filter features by single tag, ALL tags (AND), or ANY tag (OR)
• Feature sets — Group related features under a named set
• Route integration — Generate an href from a named route, safely handling missing routes
• Pennant compatible — Works alongside Pennant's native Feature::active(), @feature Blade directive, and middleware
• Customizable stubs — Publish and customize the hoist:feature generator template

Table of Contents

• Requirements
• Installation
• Configuration
• Quick Start
  • Create a Feature
  • Use Features
  • Filter by Tags
• Attributes
• Feature Discovery Service
• Feature Data Structure
• Integration with Laravel Pennant
• Use Cases
• Advanced Usage
• AI Coding Assistant Skill
• Testing
• Contributing
• Security
• License

Requirements

• PHP 8.3+
• Laravel 11/12/13
• Laravel Pennant 1+

Installation

Configuration

Publish the configuration file:

Edit config/hoist.php:

The configuration uses an associative array where keys are directory paths and values are their corresponding namespaces.

Optionally, publish the stub files for customization:

Quick Start

1. Create a Feature

This creates a new feature class in your configured feature directory (default: app/Features).

Features can define metadata using PHP attributes (recommended) or class properties. Attributes take precedence over properties when both are present.

Note: The Feature interface is optional but recommended. Features are discovered based on having a resolve() method, but implementing the interface provides better IDE support and type safety.

2. Use Features

3. Filter by Tags

Attributes

PHP attributes provide a clean, declarative way to define feature metadata directly on the class. All attributes are optional and target the class level.

When an attribute is present, it takes precedence over the equivalent class property. You can mix both approaches — for example, use attributes for static metadata and properties for values that need to be computed.

Feature Discovery Service

The FeatureDiscovery service (accessed via the Hoist facade) provides several methods for working with features:

Feature Data Structure

The FeatureData class provides a structured way to access feature information:

Integration with Laravel Pennant

This package extends Laravel Pennant by providing:

1. Automatic Discovery — No need to manually register features
2. PHP Attributes — Declarative metadata using native PHP attributes
3. Rich Metadata — Add custom metadata to features
4. Route Integration — Link features to routes automatically
5. Structured Data — Get features as structured data objects
6. Bulk Operations — Get all features and their status in one call

Using with Pennant's Native Features

You can still use all of Laravel Pennant's native features:

Use Cases

Building a Feature Dashboard

API Endpoint for Frontend

Returns:

Dynamic Navigation

Advanced Usage

Custom Feature Directories

You can configure multiple feature directories, each mapped to its namespace:

Each directory is mapped to its corresponding namespace, allowing you to organize features across different modules or domains while maintaining proper class resolution.

Feature Organization

Organize features by category:

Route Handling

The href property in FeatureData is generated from the feature's route value (via the #[Route] attribute or $route property). The package safely handles routes:

• If no route is defined, href will be null
• If the route name doesn't exist, href will be null (no exception thrown)
• If the route name is valid, href will contain the generated URL

The Feature Interface

The package provides an optional Feature interface for better type safety. Features are discovered if they either:

1. Implement the Feature interface, OR
2. Have a resolve() method (for backward compatibility with plain Pennant features)

Metadata Best Practices

Use metadata for:

• Categorization — Group features by category
• UI Elements — Icons, colors, badges
• Permissions — Access levels, roles
• Versioning — Track feature versions
• Analytics — Track feature usage

AI Coding Assistant Skill

This package ships a Laravel Boost skill so coding assistants (Claude Code, Cursor, etc.) follow the package's conventions when generating code. Install it in your app with:

The skill source lives at skills/SKILL.md.

Testing

Contributing

Contributions are welcome! Please see the documents below before getting started.

• Contributing Guide — setup, workflow, commit conventions, and PR process
• Code of Conduct — expectations for participation in this project

Security

• Security Policy — how to report a vulnerability privately

License

The MIT License (MIT). Please see License File for more information.