Download the PHP package dancycodes/flashhalt without Composer

FlashHALT

FlashHALT eliminates route definition overhead for HTMX applications, enabling direct controller method access through intuitive URL conventions - delivering 10x faster development velocity while maintaining Laravel's architectural integrity.

FlashHALT is a Laravel package that transforms how you build HTMX applications by introducing convention-based routing patterns. Instead of defining individual routes for every HTMX interaction, you can access controller methods directly through intuitive URL patterns.

The Problem That FlashHALT Solves

When building HTMX applications in Laravel, you face two major friction points that slow down development and create maintenance headaches.

First, the Route Definition Tax. Every single HTMX interaction requires you to stop what you're doing, switch to your routes file, and manually define a route. Want to add a simple "mark as complete" button to your todo app? You need to write a route. Want to load user details in a modal? Another route. Need to update a comment inline? Yet another route. This constant context switching destroys your flow state and turns simple features into multi-file modifications.

Second, the CSRF Token Nightmare. Laravel's CSRF protection is essential for security, but it creates a painful developer experience in HTMX applications. You must remember to add @csrf to every form, manually include _token in hx-vals for button clicks, or configure X-CSRF-TOKEN headers. Miss any one of these, and your request fails with a cryptic 419 error. This isn't just annoying - it's error-prone and creates security vulnerabilities when developers skip CSRF protection out of frustration.

Here's what typical HTMX development looks like in Laravel:

This approach has several problems. You're constantly switching between files, manually managing CSRF tokens, and the route definitions don't provide any meaningful organization - they're just a flat list of endpoints that grows unwieldy over time.

How FlashHALT Transforms Your Workflow

FlashHALT introduces a fundamentally different approach that eliminates both friction points simultaneously. Instead of defining routes, you use intuitive URL patterns that directly reference your controller methods. Instead of manually managing CSRF tokens, FlashHALT automatically handles them for you.

Here's the same functionality with FlashHALT:

Notice what just happened. We eliminated the entire routes file and removed all manual CSRF token management. The URL patterns like hx/tasks@store directly reference your controller methods, making the code self-documenting. Most importantly, you never have to think about CSRF tokens again - FlashHALT automatically injects them into every non-GET request.

Understanding FlashHALT's URL Convention

FlashHALT uses a simple but powerful URL pattern that maps directly to Laravel's controller structure. Let me walk you through how this works, because understanding this pattern is key to using FlashHALT effectively.

The basic pattern is hx/{controller}@{method}. Think of the hx/ prefix as FlashHALT's namespace - it tells the system "this request should be handled by FlashHALT's dynamic routing." The @ symbol separates the controller from the method, making it clear which method you're calling.

Simple Controller Mapping:

FlashHALT automatically handles Laravel's controller naming conventions. Whether your controller is named Task, TaskController, Tasks, or TasksController, FlashHALT will find it. This flexibility means you don't need to remember exact naming - just use what feels natural.

Namespace Support with Dots: For controllers in subdirectories, use dots to represent folder separators:

This dot notation makes your template code highly readable. When you see hx/admin.users@index, you immediately know you're calling the index method on the UserController in the Admin namespace.

Parameter Passing: FlashHALT works seamlessly with Laravel's route model binding and parameter injection:

Your controller methods receive these parameters exactly as they would with traditional routes:

The CSRF Magic: Never Think About Tokens Again

This is where FlashHALT truly shines and saves you countless hours of frustration. Traditional HTMX development requires you to manually manage CSRF tokens for every single non-GET request. FlashHALT completely eliminates this burden.

The Traditional CSRF Pain:

The FlashHALT Way - Completely Automatic:

How the CSRF Magic Works: When you include @flashhaltCsrf and @flashhaltScripts, FlashHALT installs a JavaScript interceptor that automatically detects FlashHALT requests (those starting with hx/) and intelligently injects CSRF tokens. For form submissions, it adds the token as a form field. For button clicks and other requests, it includes the token in the request headers. This happens completely transparently - you never see it, never think about it, but you're always protected.

This automatic CSRF injection means you can focus entirely on building features instead of wrestling with security boilerplate. It also eliminates a major source of bugs - how many times have you spent minutes debugging a 419 error only to realize you forgot a CSRF token?

Installation and Immediate Setup

Getting started with FlashHALT takes less than two minutes. Let me walk you through each step so you can start building immediately.

Step 1: Install the Package

Laravel's auto-discovery automatically registers FlashHALT's service provider, so no manual configuration is needed.

Step 2: Add HTMX and FlashHALT to Your Layout

That's it! FlashHALT is now active and every FlashHALT request will automatically include CSRF protection.

Step 3 (Optional): Publish Configuration

This creates config/flashhalt.php where you can customize security settings, but the defaults work perfectly for most applications.

Your First FlashHALT Feature: A Complete Example

Let me show you how to build a complete feature using FlashHALT. We'll create a simple task manager that demonstrates all the key concepts. This example will help you understand how FlashHALT transforms your development workflow.

Create the Controller (Standard Laravel)

Create the Views

Load the Task List in Your Main Page

That's It - No Routes Needed!

Notice what we didn't have to do. We never touched the routes file. We never manually added CSRF tokens. FlashHALT automatically resolved our URL patterns to the controller methods and handled all the security concerns transparently.

The URLs hx/@index, hx/task@store, hx/task@toggle, and hx/task@destroy automatically map to the corresponding methods in TaskController. The CSRF protection is automatically applied to all the POST, PATCH, and DELETE requests.

Understanding FlashHALT's Two Operating Modes

FlashHALT is designed to optimize your workflow in both development and production environments. Understanding these two modes will help you get the maximum benefit from the package.

Development Mode: Instant Feedback and Maximum Flexibility

In development mode (which is the default), FlashHALT uses dynamic routing. When a request comes in with the hx/ pattern, FlashHALT's middleware intercepts it, analyzes the URL pattern, and dynamically resolves it to the appropriate controller method. This happens in real-time for every request.

The beauty of development mode is that changes are instant. You can add a new method to your controller, reference it in your template with hx/controller@newMethod, and it works immediately - no route definitions, no cache clearing, no build steps. This instant feedback loop keeps you in a flow state and eliminates the friction that normally slows down HTMX development.

Development mode also provides detailed error messages when something goes wrong. If you reference a controller that doesn't exist, or a method that's not allowed, FlashHALT gives you clear, actionable error messages that help you fix the problem quickly.

Production Mode: Maximum Performance and Security

In production mode, FlashHALT takes a completely different approach optimized for performance and security. Instead of dynamically resolving routes at runtime, FlashHALT analyzes all your Blade templates during deployment and generates traditional Laravel route definitions for every FlashHALT pattern it finds.

This compilation process means that in production, your FlashHALT routes perform exactly the same as manually defined routes - there's zero runtime overhead, zero dynamic resolution, and zero performance penalty. Your application runs at full speed while still giving you the development experience benefits.

The compilation process also serves as a security validation step. FlashHALT checks every route it finds against your security configuration, ensuring that only safe controller methods are exposed. If it finds any problematic patterns, it fails the compilation and alerts you to the issue.

Switching Between Modes

To compile for production:

To return to development:

The key insight is that you get the best of both worlds: the incredible developer experience of dynamic routing in development, and the performance and security of static routes in production.

Security: Designed to Be Secure by Default

Security in FlashHALT isn't an afterthought - it's built into every layer of the system. Let me explain how FlashHALT protects your application without limiting your flexibility.

Controller Whitelisting: Only What You Allow

By default, FlashHALT only allows access to controllers in your main App\Http\Controllers namespace. This means that even if someone discovers FlashHALT is running on your site, they can't arbitrarily call methods on internal classes or framework components.

This whitelist approach means you're secure by default, but you can easily expand access as needed. If you have controllers in other namespaces that should be accessible via FlashHALT, simply add them to the whitelist.

Method Validation: Preventing Dangerous Operations

FlashHALT validates every method call against both a whitelist of allowed methods and a blacklist of dangerous patterns. The default configuration allows standard RESTful methods while blocking potentially dangerous operations.

This dual-layer approach ensures that sensitive methods are never accidentally exposed while still giving you the flexibility to add custom methods to the whitelist as needed.

Automatic CSRF Protection: Always On, Never Forgotten

The automatic CSRF protection in FlashHALT isn't just convenient - it actually improves your application's security posture. Because CSRF protection is automatic and invisible, there's no temptation to skip it or disable it for "just this one request." Every state-changing request is protected, always.

Integration with Laravel's Authorization System

FlashHALT doesn't replace Laravel's authorization system - it enhances it. Your existing authorization policies, gates, and middleware work exactly as they would with traditional routes.

FlashHALT operates at the routing layer, so all of Laravel's security features continue to work exactly as expected.

Configuration: Customizing FlashHALT for Your Needs

While FlashHALT works great with the default configuration, understanding the available options helps you tailor it to your specific requirements.

Basic Mode Configuration

Security Configuration

Advanced Features: Going Beyond the Basics

Parameter Binding and Model Injection

FlashHALT works seamlessly with Laravel's powerful parameter binding system. You can use route model binding, custom resolution logic, and dependency injection exactly as you would with traditional routes.

Custom Response Headers for HTMX

FlashHALT doesn't interfere with HTMX's response header system. You can use all of HTMX's powerful response headers to create sophisticated interactions.

Middleware Integration

FlashHALT routes respect all your existing middleware. Authentication, authorization, rate limiting, and custom middleware all work exactly as expected.

Console Commands: Managing Your FlashHALT Installation

FlashHALT provides two console commands that help you manage the compilation process and troubleshoot issues.

The Compile Command: Preparing for Production

The flashhalt:compile command analyzes all your Blade templates, finds FlashHALT patterns, validates them against your security configuration, and generates optimized Laravel route definitions.

The compile command provides detailed feedback about what it finds:

The Clear Command: Cleaning Up

The flashhalt:clear command removes compilation artifacts and cache entries, which is useful when switching between modes or troubleshooting issues.

Troubleshooting: Solving Common Issues

"Controller not whitelisted" Error

This error means you're trying to access a controller that's not in your allowed_controllers configuration. This is a security feature - FlashHALT only allows access to explicitly permitted controllers.

Solution: Add your controller to the whitelist in config/flashhalt.php:

CSRF Token Mismatch (419 Error)

If you're getting 419 errors, it usually means the automatic CSRF injection isn't working properly.

Solution: Ensure you've included @flashhaltCsrf and @flashhaltScripts in your layout:

Method Not Found or Not Allowed

This error occurs when you reference a method that doesn't exist or isn't in the method whitelist.

Solution: Check that your method exists and add it to the whitelist if needed:

Routes Not Working in Production

If FlashHALT routes stop working after deployment, you likely forgot to compile the routes.

Solution: Compile routes as part of your deployment process:

Getting Detailed Debug Information

Enable debug mode for detailed error messages and logging:

With debug mode enabled, FlashHALT logs detailed information about route resolution attempts, which you can find in your Laravel logs.

Testing Your FlashHALT Applications

FlashHALT routes can be tested exactly like traditional Laravel routes. Here are some patterns that work well:

Best Practices: Getting the Most from FlashHALT

Organize Controllers by Feature, Not by HTTP Method

Since FlashHALT eliminates route files, organize your controllers around business logic rather than HTTP semantics:

Use Descriptive Method Names

Since your method names appear in URLs, make them descriptive and intention-revealing:

Return Partial Views for HTMX

Structure your views to support partial updates:

Leverage HTMX Response Headers

Use HTMX's response headers to create sophisticated interactions:

Performance: Making FlashHALT Fast

Development Mode Optimizations

FlashHALT caches controller resolution results to minimize filesystem operations:

Production Mode: Zero Overhead

In production mode, FlashHALT-generated routes perform identically to hand-written routes. There's no runtime overhead, no dynamic resolution, and no performance penalty.

Compilation Best Practices

Include compilation in your deployment pipeline:

Contributing and Getting Help

FlashHALT is actively maintained and we welcome contributions. Whether you've found a bug, have a feature request, or want to contribute code, we'd love to hear from you.

Reporting Issues

When reporting issues, please include:

• Laravel version
• FlashHALT version
• Configuration settings (without sensitive data)
• Steps to reproduce the issue
• Expected vs actual behavior

Contributing Code

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all tests pass
5. Submit a pull request

Getting Help

• Check the troubleshooting section above
• Review the configuration options
• Enable debug mode for detailed error messages
• Check the GitHub issues for similar problems

License

FlashHALT is open-sourced software licensed under the MIT license.

Stop writing routes. Start building features.

FlashHALT eliminates the friction that slows down HTMX development in Laravel. With automatic CSRF protection, intuitive URL patterns, and production-ready compilation, you can focus on building great user experiences instead of wrestling with routing boilerplate.

Built with ❤️ by DancyCodes and the open-source community.