README

Simple. Layered. Harmony in MVC and HMVC.

Site: https://nsyframework.com/ · Docs: OVERVIEW · Libraries · Load & Asset · Helpers · Aliases · Docs Viewer · Router · Migration · Seeder · Model

Codename

Current Release Codename: Gamelan
Inspired by the traditional Indonesian ensemble, Gamelan represents harmony, modularity, and synchronized execution. Just as each instrument in a Gamelan orchestra plays a precise role to create a rich rhythm, NSY brings together lightweight core components and flexible modules (HMVC) into a unified, harmonious workflow.
(Note: Codename evolves with major version releases to honor Indonesian cultural heritage).

Features

MVC & HMVC with Razr templates
Router with groups, typed params, named routes (route('user.show', [5])) and error pages
PSR-4 Autoloading + NSY CLI (nsy make:*, nsy run:migrate, nsy run:seed, nsy down/up)
Asset Manager (Add::link/script/meta) with ?v=filemtime cache-busting
Unified DB (NSY_DB::connect), transactions (DB::transaction()) + Migrations, Seeders & Factories
Maintenance mode (APP_MAINTENANCE / nsy down) with a 503 page

Requirements

PHP >= 8.1, Composer, MySQL/MariaDB/PostgreSQL/SQL Server (optional)
Composer is required: System/Vendor/ is not committed, so dependencies are installed with composer install (use composer install --no-dev in production).

Quick Start

From Packagist — composer create-project installs dependencies and runs the framework's post-install-cmd (autoload dump + NSY CLI) automatically:

composer create-project vikry/nsy my-app
cd my-app
source ~/reloader.sh   # or reopen the terminal, so the `nsy` alias is available
nsy --setup            # creates env.php, .htaccess and system.js for this folder

nsy --setup writes env.php itself and rewrites APP_DIR / dirname to the project folder name (my-app), so the site is immediately reachable at http://localhost/my-app (or via nsy serve).

env.php is never overwritten. nsy --setup creates it from docs/env.example/env.example.php when missing. If you already copied the example yourself, setup still points APP_DIR at this folder — as long as the value is still the example default ('nsy'). A value you changed by hand, including '' for a hosting layout, is left untouched. Edit env.php afterwards for your database and, optionally, APP_URL.

From a release ZIP or git clone — System/Vendor/ is not bundled, so install dependencies first (which also installs the NSY CLI):

composer install
source ~/reloader.sh   # or reopen the terminal
nsy --setup

Configuration

env.php — APP_ENV, PUBLIC_DIR, SITE_TITLE, CSRF_TOKEN, DB_* (see docs/env.example/env.example.php)
System/Config/App.php & Site.php — env-aware with config_env() ?? fallback (no file edit in production)
System/Config/Mimes.php — 182 mime types (modern: webp, avif, woff2, wasm)

File permissions. The NSY CLI rewrites env.php and public/assets/js/config/system.js in place while preserving their mode, so nsy --setup and nsy make:* no longer strip it. If your web server runs as a different user and reports env file not found, make env.php world-readable: chmod 644 env.php.

Documentation

Overview — Composer, Config, Helpers, Routes, MVC/HMVC, Assets, PSR-4, CLI
Deploy to Shared Hosting — System/ outside public_html, writable dirs, mod_rewrite/AllowOverride
Libraries — File, LanguageCode, LoadTime, Request, Validate
JSON — Json::read()/write() (atomic file I/O)
Cookie — Cookie::set()/get() (secure defaults)
Encryption — Encryption::encrypt()/decrypt() (AES-256-GCM)
Session — Session::start()/get()/flash()
Curl — Curl::get()/post() (ext-curl, JSON auto-decode)
Validation — Validator::make()/validate() (rakit/validation)
Load & Asset Manager — Load::view/template/model & Add:: (?v=filemtime)
Helpers Global — base_url(), is_filled(), css_url() etc.
Class Aliases — Route::, Add::, Mig:: short names from App.php:aliases
Docs Viewer — render docs/*.md in-app at /docs/{slug}
CodeIgniter Helpers — stringify_attributes(), directory_map() etc.
Router — Route::get/post/group, middleware
Security Middleware — CSRF, XSS, rate-limit
Logging — PSR-3 JSONL logger: channels, rotation, retention
Migration — Mig::createTable(), quoteIdent/execDDL (DRY)
Seeder — Seeder::run(), factory(), nsy run:seed (data counterpart of migrations)
Maintenance Mode — nsy down/up, APP_MAINTENANCE 503 page
Model & DB — DB::query(), NSY_DB::connect() unified, DB::transaction()
Query Builder — qb('users')->whereIn()->paginate() — minimal lines
Dependencies — every Composer package (runtime, dev, transitive)

License

MIT — see LICENSE.txt

vikry / nsy

Package info

Security

Statistics