Current SqueHub versionv2.0.0
Getting started · v2.x

Install SqueHub

SqueHub v2.0.0 is available as a stable GitHub Release and Packagist package. The recommended Composer command below creates a new application and installs its dependencies. If you already downloaded or cloned the source, use the separate…

SqueHub v2.0.0 is available as a stable GitHub Release and Packagist package. The recommended Composer command below creates a new application and installs its dependencies. If you already downloaded or cloned the source, use the separate source-checkout steps instead. The v1.x documentation covers older applications.

Requirements

  • PHP 8.2 or newer and Composer. Check the active CLI with php -v and composer --version.
  • The PHP extensions required by Composer and the services you select. Check the active installation with php -m and php squehub doctor.
  • A PDO driver for your database: pdo_sqlite for SQLite or pdo_mysql for MySQL/MariaDB.
  • A writable session path for browser sessions and writable private runtime directories for selected services.
  • For Crypt, sodium or OpenSSL. CRYPT_DRIVER=auto prefers sodium and falls back to OpenSSL AES-256-GCM.
  • cURL for real outgoing HTTP Client calls. PHP zip or another supported extractor for Composer archives; backup:dev specifically requires the PHP zip extension.

Redis, SMTP, Queue workers, and an OS scheduler are optional until your application enables the corresponding capability. See Deployment for service-specific requirements.

Install Composer

Install PHP first, then follow the official Composer download instructions. On Windows, use the Composer Windows installer and open a new PowerShell window after installation. On Linux or macOS, follow the official Unix/macOS instructions, including installer verification. Use the current checksum from Composer's download page.

BASH
php -v
composer --version

If Composer is installed locally as composer.phar, substitute php composer.phar for composer in the commands below.

Run this from the parent directory in which you want the application. The version constraint selects the stable v2 line; Composer creates my-app and installs its dependencies:

BASH
composer create-project squehub/squehub my-app "^2.0"
cd my-app

There is no second composer install step after a successful create-project: Composer has already installed the dependencies. To install exactly the initial release instead of accepting later compatible 2.x updates, use "2.0.0" in place of "^2.0". If you use a different application directory name, use that name in the cd command and all later steps.

An unversioned composer create-project squehub/squehub my-app follows the package's current default resolution; it is not an exact-version instruction. Record the selected version in your deployment and use a deliberate constraint for reproducible setup.

Install from a source checkout or release archive

For framework development or a full source checkout, select the published v2.0.0 tag explicitly:

BASH
git clone --branch v2.0.0 https://github.com/squehub/squehub.git my-app
cd my-app
composer install

For a v2.0.0 release archive, extract it into my-app, change into that directory, and run composer install. Source checkouts and archives normally do not include vendor/; use the distributed composer.lock to install recorded dependencies. Avoid composer update during initial setup because it may resolve different package versions. A plain git clone https://github.com/squehub/squehub.git my-app selects the repository's current default branch, which is not an exact release selection.

Keep the source files required by the application, including composer.lock and the public Documentation/ guides. The private local Docs/ development tree is not part of the published release.

All remaining commands run inside my-app, whether you used Composer, Git, or an archive.

Configure the environment

There are two setup paths. Option A is the complete manual path. Option B uses the optional SqueHub Setup command to inspect and propose configuration changes. Both start from the application directory created or checked out above.

Option A — Manual setup

Copy the distributed template into your private configuration file.

Windows PowerShell:

POWERSHELL
Copy-Item .example.env .env

Linux or macOS:

BASH
cp .example.env .env

Generate a private 256-bit key:

BASH
php squehub key:generate

The command prints a new value; it does not edit .env. Paste the complete output into the APP_KEY line:

DOTENV
APP_KEY=base64:your-generated-key-here

Replace the placeholder with your own value. Do not commit .env, send the key to a log, or reuse another application's key. Set APP_ENV and APP_DEBUG deliberately, then review database, Cache, Session, Queue, Mail, Redis, and Storage settings you plan to use. The template's APP_KEY is blank. Comments, key order, and line endings do not count as changed configuration if parsed values still match .example.env.

Missing or unchanged .env settings trigger the SqueHub setup required page on web requests and a safe CLI notice. After changing parsed values, the next browser request sees the update without restarting php squehub start. An empty APP_KEY can leave Crypt unavailable even if another changed setting clears the setup page.

Option B — SqueHub Setup

From the v2 project root, run:

BASH
php squehub setup

SqueHub Setup inspects the application and presents a reviewable plan for required configuration changes. It preserves existing settings and does not rotate an existing key or run Migrations, Seeders, or Package operations automatically. Review its plan before applying changes, then inspect the Doctor result. See the Setup guide for its security and verification boundaries. You can return to the manual steps above at any time.

When SQLite is selected, Setup can plan creation of a missing Storage/ directory and an empty Storage/Database.sqlite file. That relative path resolves from the application root even if the shell starts elsewhere; it is not a migration and creates no application tables. Existing unsafe or unwritable Storage paths fail instead of being replaced.

In a non-interactive shell, a fresh application needs an explicit environment and database choice. For example, review a local SQLite plan before choosing to apply it:

BASH
php squehub setup --environment=local --database=sqlite --preview

--preview writes nothing and does not run Doctor. The Setup guide explains confirmation and --yes for deliberate non-interactive application.

Verify and run

BASH
php squehub --version
php squehub doctor
php squehub route:list
php squehub start

Doctor reports required failures and optional warnings separately. A warning about unused Redis or SMTP does not mean the basic application failed. start serves only public/, tries an available port in 8000–8099 when no port is supplied, and prints its chosen local URL. For Apache or Nginx, set the document root to public/; never serve the repository root, which contains source and .env.

For a coordinated local session after setup, you may instead run php squehub dev. SqueHub Dev performs Doctor preflight and starts the same development server; an existing persistent Queue worker can be selected explicitly with --queue. The standalone start workflow remains available. Neither command installs dependencies or runs Migrations or Seeders.

Continue with First application. For production preparation, use Deployment and Health.