Evolution CMS Installer

CLI tool for creating new Evolution CMS projects.

Installation

Global Installation

Install globally using Composer:

composer global require evolution-cms/installer

Important: After installation, make sure the Composer global bin directory is in your system PATH so the evo command is accessible from anywhere.

Linux / macOS

Add to your shell configuration file (~/.bashrc, ~/.zshrc, or ~/.profile):

export PATH="$HOME/.composer/vendor/bin:$PATH"
# or for newer Composer installations:
export PATH="$HOME/.config/composer/vendor/bin:$PATH"

Then reload your shell configuration:

source ~/.bashrc  # or source ~/.zshrc

Windows

1. Find your Composer global directory (usually C:\Users\YourName\AppData\Roaming\Composer\vendor\bin)

2. Add it to your system PATH:

   • Press Win + R, type sysdm.cpl, press Enter
   • Go to "Advanced" tab → "Environment Variables"
   • Under "System variables", find Path and click "Edit"
   • Add the Composer bin directory path
   • Click "OK" to save

3. Restart your terminal/command prompt

Verify Installation

After setting up PATH, verify the installation:

evo --version

If you see the version, installation was successful!

Usage

Create a new Evolution CMS project

evo new my-project

This command will:

• Validate PHP version compatibility
• Prompt you for database configuration (with connection testing)
• Prompt you for admin user credentials and directory
• Prompt you for installation language
• Download and install Evolution CMS (latest compatible version or from specific branch)
• Configure the database connection
• Run migrations and seeders
• Create the admin user

Command Options

evo new my-project --preset=evolution
evo new my-project --db-type=mysql
evo new my-project --db-host=localhost --db-name=evo_db
evo new my-project --admin-username=admin --admin-email=admin@example.com
evo new my-project --admin-directory=manager
evo new my-project --language=en
evo new my-project --branch=develop  # Install from specific Git branch
evo new my-project --git  # Initialize a Git repository
evo new my-project --force  # Force install even if directory exists

Available Options

• --preset: The preset to use (default: evolution)
• --db-type: Database type (mysql, pgsql, sqlite, or sqlsrv)
• --db-host: Database host (default: localhost, not used for SQLite)
• --db-port: Database port (defaults: 3306 for MySQL, 5432 for PostgreSQL, 1433 for SQL Server)
• --db-name: Database name (for SQLite: path to database file, default: database.sqlite)
• --db-user: Database user (not used for SQLite)
• --db-password: Database password (not used for SQLite)
• --admin-username: Admin username
• --admin-email: Admin email
• --admin-password: Admin password
• --admin-directory: Admin directory name (default: manager)
• --language: Installation language (default: en)
• --branch: Install from specific Git branch (e.g., develop, nightly, main) instead of latest release
• --git: Initialize a Git repository and create initial commit
• --force: Force install even if directory exists

Presets

Evolution Preset (Default)

Standard Evolution CMS installation with all core features.

evo new my-project
# or
evo new my-project --preset=evolution

Custom Presets

You can create custom presets by extending the Preset class. See the src/Presets/ directory for examples.

Features

Automatic Version Resolution

• PHP Compatibility Check: Automatically finds the latest Evolution CMS version compatible with your PHP version
• Version Validation: Validates PHP version requirements before installation starts
• Smart Version Selection: Checks GitHub releases and composer.json requirements to determine compatibility
• Latest Compatible Version: Always installs the newest version that works with your PHP setup
• Branch Installation: Install from specific Git branches (develop, nightly, main) for development or testing

Smart Database Configuration

• Multiple Database Support: Supports MySQL/MariaDB, PostgreSQL, SQLite, and SQL Server
• Automatic Port Detection: Automatically uses correct default ports (3306 for MySQL, 5432 for PostgreSQL, 1433 for SQL Server)
• Connection Testing: Tests database connection before proceeding with installation, with retry option
• Collation Resolution: Intelligently handles database collations, including those not in the server's collation list
• Install Type Detection: Automatically detects if this is a fresh install or an update
• Secure Configuration: Creates database config files with proper permissions (read-only)

Inspired by Docker Implementation

This installer incorporates best practices from the Evolution CMS Docker implementation, including:

• Database configuration file generation
• Install type detection
• Proper handling of MySQL and PostgreSQL differences

Development

Requirements

• PHP 8.3+
• Composer
• Database: MySQL 5.7+ / MariaDB 10.3+, PostgreSQL 10.0+, SQLite 3.26.0+, or SQL Server 2017+

Installation for Development

git clone https://github.com/evolution-cms/installer.git
cd installer
composer install

Running Tests

Install dependencies first:

composer install

Then run tests:

composer test

Run tests with coverage:

composer test-coverage

Note: Code coverage requires either Xdebug or PCOV PHP extension to be installed:

• Xdebug: pecl install xdebug or install via your OS package manager
• PCOV: pecl install pcov (faster alternative to Xdebug for coverage only)

After installing, restart PHP-FPM or your web server.

Legacy Installer

The old install.php file is still available in this repository for backward compatibility and quick installations.

License

GPL-3.0-or-later

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Documentation: https://docs.evo.im
• Issues: https://github.com/evolution-cms/installer/issues
• Community: https://t.me/evolutioncms