#Installation

#Prerequisites

Before creating your first Slenix application, make sure your environment meets the following requirements:

Slenix is tested on Linux, macOS, and Windows. On Windows, Laragon is the recommended local environment — it bundles PHP, MySQL, and a web server in a single installer with zero configuration.

#Installing Slenix

The recommended way to create a new Slenix project is via Composer:

composer create-project slenix/slenix my-app

Composer will create the my-app/ directory, install the framework, copy .env.example to .env, and automatically generate a secure APP_KEY for you.

#Starting the Development Server

Navigate into the project directory and start the built-in development server using the Celestial CLI:

cd my-app
php celestial serve

Your application is now running at http://127.0.0.1:8080. Open routes/web.php and you will find your first route already defined:

use Slenix\Http\Request;
use Slenix\Http\Response;
use Slenix\Http\Routing\Router;

Router::get('/', function (Request $req, Response $res) {
    return view('welcome');
});

To specify a custom host or port:

php celestial serve # or 4000

You can also use PHP's built-in server directly, pointing it at the public/ directory:

php celestial serve --host=0.0.0.0 --port=9000

#Project Structure

After installation, your project will have the following layout:

my-app/
├── app/
│   ├── Controllers/        # Application controllers
│   ├── Middlewares/        # Custom middleware classes
│   └── Models/             # Application models
├── public/
│   ├── index.php           # Entry point — all requests go here
│   ├── .htaccess           # Apache rewrite rules
│   └── robots.txt
├── routes/
│   └── web.php             # Route definitions
├── src/
│   ├── Config/
│   │   └── app.php         # Framework configuration
│   ├── Core/               # Kernel, AppFactory, CLI (Celestial)
│   ├── Http/               # Request, Response, Router, Middleware
│   └── Supports/           # Database, Session, CSRF, JWT, Luna, Mail, Upload...
├── views/                  # Luna template files (.luna.php)
├── .env                    # Environment configuration (never commit this)
├── .env.example            # Environment template (safe to commit)
├── celestial               # CLI entry point
└── composer.json

Every HTTP request to your application is handled by public/index.php, which bootstraps the framework and dispatches the request through the router. Your application code lives in app/ and the framework core lives in src/ — the two never mix.

#Environment Configuration

All environment-specific configuration is stored in the .env file at the project root. This file is created automatically during installation. Never commit .env to source control — it contains sensitive credentials such as database passwords and encryption keys. Commit only the .env.example template.

A fresh Slenix .env file looks like this:

# Application
APP_NAME=Slenix
APP_KEY=base64:...            # Generated automatically on install
APP_DEBUG=false
APP_ENV=production            # local | production | testing
APP_VERSION=2.2
APP_BASE_URL=http://localhost
APP_TIMEZONE=UTC
APP_LOCALE=en

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=slenix_db
DB_USERNAME=root
DB_PASSWORD=Root@123
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci

# JWT
JWT_SECRET_TOKEN=

# Mail
EMAIL_METHOD=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_ENCRYPTION=tls
SMTP_AUTH=true
SMTP_TIMEOUT=30

# Security
FORCE_HTTPS=false
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW=60
CONTENT_SECURITY_POLICY=default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'

Access any value in your code using the env() helper. It automatically converts "true" / "false" strings to native PHP booleans and "null" to null:

env('APP_NAME');              // 'Slenix'
env('APP_DEBUG');             // false  (bool, not string)
env('DB_PORT', 3306);         // 3306   (with default fallback)
env('MISSING_KEY', 'default'); // 'default'

You may also use the config() helper, which accepts a lowercase key and converts it to uppercase automatically:

config('app_name');       // reads APP_NAME
config('db_hostname');    // reads DB_HOSTNAME
config('smtp_port', 587); // reads SMTP_PORT with fallback

#Generating an Application Key

If you need to regenerate the application key:

php celestial key:generate

This writes a new 32-byte base64-encoded key to APP_KEY in your .env file. The key is used by encrypt() and decrypt(). Always set it before going to production.

#Database Setup

Slenix supports MySQL (5.7+) and PostgreSQL (13+). Update the DB_* variables in .env:

# MySQL
DB_CONNECTION=mysql
DB_HOSTNAME=127.0.0.1
DB_PORT=3306
DB_NAME=my_database
DB_USERNAME=root
DB_PASSWORD=secret
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_general_ci

# PostgreSQL
DB_CONNECTION=pgsql
DB_HOSTNAME=127.0.0.1
DB_PORT=5432
DB_NAME=my_database
DB_USERNAME=postgres
DB_PASSWORD=secret
DB_CHARSET=utf8

The DB_COLLATION setting is only used with MySQL and is ignored for PostgreSQL.

Once your database is configured, you can start querying immediately using a model or the QueryBuilder:

use App\Models\User;

$users = User::where('active', 1)->orderBy('name')->get();

#App Environments

The APP_ENV variable controls how Slenix behaves. Three values are supported:

During development, set both variables together:

APP_ENV=local
APP_DEBUG=true

In production, always set APP_DEBUG=false to prevent sensitive information from leaking in error responses.

#Web Server Configuration

#Apache

Slenix includes a pre-configured .htaccess in public/ that enables clean URLs via mod_rewrite. Point your virtual host DocumentRoot at the public/ directory:

<VirtualHost *:80>
    ServerName my-app.test
    DocumentRoot /path/to/my-app/public

    <Directory /path/to/my-app/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

#Nginx

server {
    listen 80;
    server_name my-app.test;
    root /path/to/my-app/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

#Laragon (Windows)

Place your project inside the laragon/www/ directory. Laragon will detect it automatically and create a virtual host at my-app.test — no manual configuration required.

#Celestial CLI

Slenix includes a command-line tool called Celestial for common development tasks:

# Start the development server
php celestial serve

# Generate a new APP_KEY
php celestial key:generate

# Scaffold a controller
php celestial make:controller UserController

# Scaffold a model
php celestial make:model User

# Scaffold a middleware
php celestial make:middleware AuthMiddleware

# List all registered routes
php celestial route:list

# Clear the Luna template cache
php celestial view:clear

Read the full CLI reference for all available commands and options.

#Next Steps

With your application running, here is what to explore next:

• Introduction — What Slenix is and what it offers
• Routing — Named routes, parameters, groups, and middleware
• Luna Templates — Layouts, directives, cache, and includes
• Database — ORM, QueryBuilder, relationships, and pagination
• Session & Flash — Fluent state management across requests
• CSRF Protection — Automatic protection and route exclusions
• JWT Authentication — Token generation, validation, and middleware
• Mail — Sending transactional emails via SMTP
• File Uploads — Secure file handling and validation
• HTTP Client — Making outgoing HTTP requests
• Helpers — Full reference of global functions

#Slenix as a Full-Stack Framework

The most common way to use Slenix is as a full-stack framework — routing requests, handling business logic in controllers, and rendering HTML responses via Luna templates. Define your routes in web.php, put your logic in app/Controllers/, and render views with the view() helper.

#Slenix as an API Backend

Slenix is equally well-suited as a lightweight API backend for JavaScript SPAs or mobile applications. Its fast response times, built-in JWT support, and zero-dependency footprint make it ideal for APIs that need to be small, predictable, and easy to deploy. Return JSON from any route or controller using $res->json($data).