Installation

Install the NaluzPHP installer (recommended)

The installer is a global Composer package that adds the naluz command, so you can create projects from anywhere:

composer global require naluz/installer

Then check that the command is available:

naluz --version        # NaluzPHP Installer 1.0.0

If you see command not found (or 'naluz' is not recognized), Composer’s global bin folder is not on your PATH. See naluz: command not found below. Update the installer later with composer global update naluz/installer.

Then create a project:

naluz new my-app
cd my-app
php naluz run:server

naluz new creates the project with Composer, generates APP_KEY and JWT_SECRET, creates the default SQLite database file and, if you agree, runs the migrations. Open http://127.0.0.1:8000 and try GET /api/ping.

naluz new shop --name=acme/shop --migrate --git      # set the package name, migrate, git init + first commit
naluz new api --release=^1.2                         # a specific release
naluz new . --dev                                    # the development version, into the current empty directory

See The installer for every option, how commands are forwarded inside a project, and troubleshooting. Update it with composer global update naluz/installer.

naluz: command not found

composer global require puts the naluz file in Composer’s global bin folder. If that folder is not on your PATH, your shell cannot find the command. This is normal after a first global install and is easy to fix. First check that the package is installed and find the folder:

composer global show naluz/installer
composer global config bin-dir --absolute

The second command prints the folder to add to your PATH. Typical locations are listed below; use the exact path it prints.

macOS (zsh)

macOS uses zsh by default. Typical folder: ~/.composer/vendor/bin (or ~/.config/composer/vendor/bin).

echo 'export PATH="$PATH:$HOME/.composer/vendor/bin"' >> ~/.zshrc
source ~/.zshrc
naluz --version

To always follow Composer’s own setting instead of hard-coding the path:

echo 'export PATH="$PATH:$(composer global config bin-dir --absolute 2>/dev/null)"' >> ~/.zshrc
source ~/.zshrc

If you installed PHP and Composer with Homebrew and the folder looks different, use the path that composer global config bin-dir --absolute printed. Bash users (~/.bash_profile) do the same in that file.

Linux (bash, zsh, fish)

Typical folder: ~/.config/composer/vendor/bin (newer Composer) or ~/.composer/vendor/bin.

# bash
echo 'export PATH="$PATH:$HOME/.config/composer/vendor/bin"' >> ~/.bashrc && source ~/.bashrc

# zsh
echo 'export PATH="$PATH:$HOME/.config/composer/vendor/bin"' >> ~/.zshrc && source ~/.zshrc

# fish
fish_add_path ~/.config/composer/vendor/bin

Replace the folder with the one composer global config bin-dir --absolute printed if it is different.

Windows

The Composer installer normally adds the folder to your PATH for you. If naluz is not recognized, the typical folder is %APPDATA%\Composer\vendor\bin (for example C:\Users\you\AppData\Roaming\Composer\vendor\bin). In PowerShell:

composer global config bin-dir --absolute
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:APPDATA\Composer\vendor\bin", "User")

Or use the interface: press Win, search for Edit environment variables for your account, select Path, click Edit, then New, and paste the folder. Click OK on each window. Close and reopen your terminal, then run:

naluz --version

In Git Bash, use the export PATH=... form from the Linux section with a path like /c/Users/you/AppData/Roaming/Composer/vendor/bin.

Check and troubleshoot

• Open a new terminal window after changing your PATH. source ~/.zshrc (or ~/.bashrc) only affects the current one.
• Confirm the file exists: ls "$(composer global config bin-dir --absolute)" should list naluz (on Windows, dir shows naluz and naluz.bat). If the folder is empty, run composer global require naluz/installer again.
• echo $PATH (PowerShell: $env:Path) should contain that folder.
• Run it by full path to confirm it works: ~/.composer/vendor/bin/naluz --version.
• To avoid touching your PATH, you can skip the installer and use Composer directly or the skeleton.

Other ways to create a project

NaluzPHP projects start from the application skeleton, naluzphp-framework. The framework itself arrives in vendor/naluz/framework when you run composer install.

With Composer directly

The skeleton is a normal Composer package, so no extra repository settings are needed:

composer create-project naluz/naluzphp my-app
composer create-project naluz/naluzphp my-app dev-master    # the development version

Clone the skeleton

git clone https://github.com/taliffsss/naluzphp-framework.git my-app
cd my-app
composer install
cp .env.example .env
php naluz key:generate --jwt
touch storage/database.sqlite     # SQLite is the default database
php naluz migrate
php naluz run:server

From inside an existing project

A project also has its own generator, which copies the project it is run in:

php naluz new my-app

Option	Meaning
--name=vendor/package	sets the Composer package name
--no-install	skip composer install
--dir=/parent/dir	create the project in another directory

The development server

php naluz run:server                    # http://127.0.0.1:8000
php naluz run:server --port=8001        # another port
php naluz run:server --host=0.0.0.0 --workers=4

APP_HOST and APP_PORT in .env set the defaults. The command checks that the port is free and validates the host, port and worker count before starting PHP’s built-in server. It is meant for development only.

Configure your environment

Copy .env.example to .env and adjust it. The generated keys are required:

php naluz key:generate           # writes APP_KEY (encryption)
php naluz key:generate --jwt     # also writes JWT_SECRET (token auth)
php naluz key:generate --show    # print the values instead of writing them

See Configuration for the full list.

Choose a database

SQLite works with no setup. For MySQL, PostgreSQL or SQL Server, set the connection in .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=myapp
DB_USERNAME=myapp
DB_PASSWORD=secret

See Database drivers and Read/write connections.

Web server

Point the document root at public/. Only that directory should be web-accessible.

Apache

public/.htaccess is included and needs mod_rewrite.

nginx

root /var/www/my-app/public;

location / {
    try_files $uri /index.php$is_args$args;
}

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root/index.php;
    fastcgi_pass unix:/run/php/php-fpm.sock;
}

Next steps

Build your first feature, or read the production guide before you deploy.