Weave Code
Generate PHP mixin interfaces from class namespaces
Frequently asked questions about Fluentgen
- What is Respect\FluentGen used for?
- Respect\FluentGen generates PHP mixin interfaces from a class namespace so IDEs can autocomplete __call-based fluent builder chains. It scans concrete classes, reflects their constructors, and writes Builder and Chain interfaces with matching method signatures and return types. You then reference the generated interface from a builder class via a @mixin docblock. It is a development-time code generation tool, not a runtime fluent-interface implementation.
- How do I install Respect\FluentGen in a Laravel project?
- Install it as a dev dependency with composer require --dev respect/fluentgen. The package requires PHP 8.5+ and has no Laravel-specific dependencies. In a Laravel app, wire generation into a custom Artisan command or a Composer script and point the Config at your source and output directories. Generated interfaces are additive, so existing application code stays unchanged.
- Does FluentGen work with Laravel Eloquent or query builders?
- FluentGen is framework-agnostic and can generate interfaces for any namespace of classes that your builder resolves dynamically through __call. It is most useful for custom query builders, repository wrappers, or domain-specific fluent APIs where Eloquent's built-in methods do not already provide IDE visibility. It does not replace Eloquent or add runtime behavior; you still implement the fluent methods. If Eloquent already gives you the fluent API you need, FluentGen may not add much value.
- Which PHP and Laravel versions are supported?
- The package itself requires PHP 8.5 or newer and does not depend on Laravel. The technical assessment notes Laravel 9+ compatibility at the framework level, but your Laravel version must also support the PHP version you run. Because FluentGen is just a dev-time generator, it should work in any Laravel project that satisfies the PHP requirement. Always verify the PHP constraint in Composer before adopting it.
- How does FluentGen generate interfaces from a namespace?
- You define a Config with sourceDir, sourceNamespace, outputDir, and outputNamespace. A NamespaceScanner reflects every concrete class in the source directory, optionally filtered by an interface and excluding specific classes. FluentGen then writes a Builder interface with static starter methods and a Chain interface with instance methods for continuing chains. Each generated method mirrors the constructor signature and doc comments of the underlying class.
- Do generated interfaces add runtime overhead?
- No meaningful runtime overhead is expected because the generated files are static PHP interfaces. The scanning and generation work happens during development or build time, not on every request. At runtime PHP only autoloads the interface declarations when they are referenced. You can treat generated interfaces like any other source file in your autoload path.
- Can I use FluentGen with Laravel service providers, facades, or macros?
- Yes, but FluentGen only generates interfaces; you still wire implementations and container bindings yourself. Generated interfaces can be referenced in @mixin docblocks on builder classes that Laravel resolves through the container. If you expose fluent builders through facades or macros, bind the concrete implementation explicitly and keep the generated interface as the IDE-facing contract. This keeps autocompletion working without changing Laravel's runtime behavior.
- How should I integrate FluentGen into CI/CD or deployment?
- Add generation to a Composer script or a custom Artisan command that runs during development and in CI. Make the process idempotent so the same input namespace always produces the same output, and decide whether to commit generated interfaces or generate them before deployment. Running generation in CI helps catch namespace or signature changes early. Avoid generating interfaces on every web request.
- What are the limitations or risks of using FluentGen?
- FluentGen is purely a code generation tool and does not enforce or implement runtime fluent behavior. You must manually implement the methods declared by the generated interfaces, and generated interfaces can complicate mocking or testing if not scoped carefully. Namespace collisions are possible, so validate output namespaces against PSR-4 and exclude builder classes where needed. The main discipline is keeping generated contracts in sync with the underlying classes.
- Are there alternatives to FluentGen for fluent builder autocompletion?
- Alternatives include hand-written @mixin interfaces, Laravel IDE Helper for facades and models, and static-analysis stubs for PHPStan or Psalm. Respect/Fluent can help when you need runtime composable behavior, while FluentGen focuses on generating interface declarations from namespace conventions. Eloquent's built-in fluent methods may be enough for standard query building. Choose FluentGen when you have custom __call-based builders and want automated IDE contracts.
Weaver
How can I help you explore Laravel packages today?