_                           _
  _ ____   _| | __ _ _ __ __ ___   _____| |
 | '_ \ \ / / |/ _` | '__/ _` \ \ / / _ \ |
 | | | \ V /| | (_| | | | (_| |\ V /  __/ |
 |_| |_|\_/ |_|\__,_|_|  \__,_| \_/ \___|_|

      Composable Laravel Generator

Composable project scaffolding CLI for Laravel applications. Enables multi-layered stack combinations with automatic dependency resolution and atomic rollback.

Supported Configuration Layers

nvlaravel scaffolds projects based on composable options across the following domains. All options can be combined freely.

Rendering

Reactivity

JavaScript Frameworks

JavaScript Utilities

CSS Frameworks

UI Libraries

UI Components

Icons & Notifications

Authentication

Authorization

Multi-tenancy & User Management

API

Realtime

Database

Infrastructure

Observability

Packages

Testing & Code Quality

Code Architecture

Installation

You can install and use nvlaravel via three different methods:

Method 1: Standalone Executable (Recommended)

Download the pre-compiled standalone binary to avoid any global Composer conflicts. This is a single, self-contained file that runs anywhere.

For macOS / Linux:

1. Download the executable directly from the terminal:

   curl -sL https://github.com/vall-here/nvlaravel/releases/latest/download/nvlaravel -o nvlaravel
   

2. Make it executable:

   chmod +x nvlaravel
   

3. Move it to your system PATH to use it globally:

   sudo mv nvlaravel /usr/local/bin/
   

4. Run the wizard from anywhere:

   nvlaravel new my-app
   

For Windows:

1. Download the File: Download the nvlaravel executable from the latest GitHub Releases.
2. Create a Dedicated Folder: Create a new folder on your computer where you will store command-line tools. For example: C:\tools\nvlaravel\
3. Move the File: Move the downloaded nvlaravel file into this new folder (C:\tools\nvlaravel\nvlaravel).
4. Create a Batch Wrapper: To run it like a native Windows command, create a new text file in the same folder, name it nvlaravel.bat, and add this exact content:

   @php "%~dp0nvlaravel" %*
   

5. Add to System PATH:
   • Press the Windows Key, type Environment Variables, and select Edit the system environment variables.
   • Click the Environment Variables button at the bottom.
   • Under System variables (or User variables), find the Path variable, select it, and click Edit.
   • Click New and paste the path to your folder: C:\tools\nvlaravel\
   • Click OK on all windows to save.
6. Restart Terminal: Close and reopen your Command Prompt or PowerShell, then test the command from anywhere:

   nvlaravel new my-app
   

Method 2: Global Composer

If your global Composer environment is clean, you can install it globally:

composer global require vall-here/nvlaravel

(Ensure your global Composer bin directory is in your system PATH.)

Method 3: Isolated Composer Project

If you prefer to keep the generator isolated but still use Composer:

composer create-project vall-here/nvlaravel my-generator
cd my-generator
php nvlaravel new my-app

Usage

Create a new Laravel project using the interactive wizard:

nvlaravel new my-app

Using Presets

nvlaravel new my-app --preset=classic

Available presets:

CLI Options

Technical Architecture

The core engine follows a 4-layer execution pipeline:

1. Blueprint (App\Configuration\Blueprint): Registry loading technology definitions, dependencies, and conflict matrices from config/generator.php.
2. RuntimeConfig (App\Configuration\RuntimeConfig): State container holding user selections.
3. Resolver (App\Dependency\Resolver): Dependency resolution using recursive topological sorting and circular dependency detection.
4. ExecutionPlan (App\Planning\ExecutionPlan): Sequence generator ordering task handlers.
5. Executor (App\Engine\Executor): Handler pipeline running composer, npm, and stub transformations.

Safety Mechanisms

• EnvironmentDoctor (App\Services\EnvironmentDoctor): Pre-check for PHP, Composer, and NPM binaries and minimum versions before any execution.
• RollbackManager (App\Services\RollbackManager): Atomic rollback deleting partially created directories upon any failure during scaffolding.

Development & Testing

Run unit tests with Pest:

./vendor/bin/pest

Compile standalone Phar executable:

php -d phar.readonly=0 build_phar.php

Contributing

We welcome contributions from the community! Whether it's a bug fix, a new feature, or an improvement to the documentation, your help is appreciated.

Reporting Issues

If you find a bug or have a feature request, please open an issue on the GitHub Issues page. Include as much detail as possible to help us understand the problem.

Submitting Pull Requests

1. Fork the repository.
2. Create a new branch for your feature or bugfix (git checkout -b feature/your-feature-name).
3. Make your changes and commit them with clear, descriptive messages (git commit -m "Add some feature").
4. Push your branch to your fork (git push origin feature/your-feature-name).
5. Open a Pull Request against the main branch of this repository.

Ensure your code follows the existing style and passes all tests by running ./vendor/bin/pest.

License

MIT License.