🐾 Lynx CLI - NestJS-like PHP Framework Developer Tool

Lynx CLI is the official, Rust-written, ultra-fast, lightweight, and cross-platform command-line developer tool for your NestJS-syntax PHP backend framework, designed to elevate your developer experience to the highest level.

This tool fulfills all your backend development needs, including project scaffolding, boilerplate generation (controllers, services, entities, modules), a debounced hot-reloader server, and a resilient, real-time log streaming engine.

---

✨ Features

• ⚡ Power of Rust: Blazing fast execution, instantaneous startup times, and minimal memory footprint.
• 📂 Smart Project Scaffolding (new): Generates new projects directly from the main template in seconds, eliminating sluggish directory scanning and subfolder search loops.
• ⚙️ Advanced Code Generation (g):
  • Safe casing conversions (fully Unicode-compliant).
  • Smart, duplication-preventing component registration in AppModule.php or custom sub-modules.
  • Omission of redundant use namespace imports if the generated component resides in the same directory as the target module (self-import prevention).
  • Error-free file and folder creation across Windows and UNIX systems.
• 🔄 Smart Hot-Reloading (run):
  • Intelligently monitors ./Src, ./App, and ./index.php files recursively.
  • Custom path filter that ignores changes inside /Cache/, logger.json, and app.cache.json to prevent redundant restarts and console-clearing.
  • 500 ms debouncing mechanism to prevent rapid duplicate server reloads during quick successive saves.
• 🪵 Seamless Log Streaming: A resilient real-time log streaming engine that reads and prints colorized logs to the terminal, gracefully surviving Windows file-sharing locks (sharing violations) and partial JSON writes without throwing disturbing exception messages.

---

🛠️ Prerequisites

To build and run Lynx CLI, make sure you have the following installed on your system:

1. Rust & Cargo: (Rust 1.70 or higher recommended) -> Install Rust
2. PHP: The php command must be added to your system Environment Variables (PATH) (PHP 8.1+ recommended).

---

📥 Installation and Compilation (Build)

1. Clone the Repository from GitHub

First, open your terminal and clone the project to your local machine:

git clone https://github.com/SignorMassimo/lynx_cli.git
cd lynx_cli

2. Production Release Build

To compile a highly optimized, single executable binary ready for global use:

cargo build --release

After compilation, the binary will be located in the release target directory:

• For Windows: target/release/lynx.exe
• For Linux/macOS: target/release/lynx

---

🌍 Globalizing the CLI System-wide (Global PATH)

To be able to execute Lynx CLI from any directory by simply typing lynx, choose one of the following two global installation methods:

Method A: Automatic Installation via Cargo (Easiest and Recommended Way) 🚀

You can install the CLI globally using Rust's cargo toolchain. Run the following command from the project root directory:

cargo install --path .

• What does this command do? It compiles the CLI in release mode behind the scenes and installs it natively as lynx in your Cargo binary folder (~/.cargo/bin or %USERPROFILE%\.cargo\bin on Windows).
• Note: The Cargo bin path is typically added to your system PATH automatically during the initial Rust installation. If not, follow the terminal output prompt to add it.

Method B: Manually Adding Directory Path to Environment Variables (PATH)

If you prefer to keep the compiled binary at its original location or a custom path:

On Windows:

1. Compile the project with cargo build --release.
2. Open the Start menu, search for "Environment Variables", and select "Edit the system environment variables".
3. Click on the Environment Variables button in the pop-up window.
4. Under "User variables" or "System variables", select the Path variable and click Edit.
5. Click New and enter the absolute path of your project's target/release folder (Example: C:\Users\User\Desktop\Rust\lynx_cli\target\release).
6. Close all panels, and restart your terminal window.

On Linux / macOS:

You can copy the compiled lynx binary to a global bin folder like /usr/local/bin or add its location to your .bashrc / .zshrc profile:

sudo cp target/release/lynx /usr/local/bin/

---

📖 Command Guide (Detailed Commands)

1. lynx new <project_name>

Scaffolds a new Lynx PHP project skeleton inside the specified directory.

lynx new my-awesome-app

• How it works: The CLI copies the full main_templates/lynx_php directory from the executable path straight to the destination directory.
• Once completed, it presents you with a styled Lynx ASCI art banner and next-step onboarding tips.

---

2. lynx run <port>

Spawns the local PHP development server with real-time log streaming and automatic hot-reloading.

lynx run 8000

• How it works:
  • Spawns the PHP built-in server at localhost:<port>.
  • Monitors ./Src, ./App, and ./index.php for modifications.
  • When a file is modified, the watcher pings the PHP application to reload caches and display updated routes instantly.
  • Because the /Cache/ folder and logger.json updates are ignored, your terminal console is never cleared when log entries are written, maintaining a fully scrollable logging history!

---

3. lynx g <type> <name> [module_name]

Generates NestJS-style boilerplate code and registers it cleanly in the target modules.

Available Types:

• controller (HTTP Router Controller)
• service (Provider / Business Logic)
• entity (Database Table Entity)
• module (Module Class)

Example Usages:

A. Generate a UserController:

lynx g controller User

• Result: Generates Src/User/UserController.php.
• Automatically registers UserController::class in the 'controllers' array of Src/AppModule.php (or Src/User/UserModule.php if present) along with its imports.

B. Generate a UserService (with Table Entity Integration):

lynx g service User

• Result: Generates Src/User/UserService.php.
• If UserEntity.php is present in the module folder, it automatically integrates the UserEntity injection boilerplate within the service class and adds it to the 'providers' list in the module.

C. Generating and Registering inside a Specific Sub-module:

By default, components are registered under their own module namespace or AppModule.php. If you want to bind a new component to an alternate module, provide the module name as the third argument:

# Generates UserService inside the Auth module namespace and registers it in AuthModule.php
lynx g service User Auth

---

🤝 Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazingFeature).
3. Commit your changes (git commit -m 'Add: amazing feature').
4. Push to the branch (git push origin feature/amazingFeature).
5. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License.

---

🐾 Have fun building great backends with Lynx!