Skip to content

Installation

Phexium adopts a Copy-Based Framework distribution model. Unlike traditional package-based frameworks installed in vendor/, this model copies framework code directly into your project, enabling local customization while maintaining synchronization capabilities.

See Copy-Based Framework for the full benefits and workflow.

Quick Start

mkdir my-project && cd my-project
git init
git fetch https://gitlab.com/phexium/framework.git/
git checkout FETCH_HEAD -- installer.php
php installer.php

The bootstrap script downloads the CLI tools, then delegates to the interactive installer which guides you through template selection, database configuration, and environment setup. The bootstrap script self-destructs after successful installation.

After installation, access your application at http://localhost:8080.

Contributing to Phexium? If you want to test or contribute to the framework itself, see the Contributor Installation.

Installation Process

The bootstrap script (installer.php) initializes a Git repository if needed, fetches the upstream repository, and downloads the tools/ directory. It then delegates to php tools/phexium.php install, which runs five phases:

1. Preparation

Verifies prerequisites, fetches upstream, and selects a template:

  • Checks PHP 8.4+, Git, Task (task runner), Docker
  • Fetches the upstream repository (git fetch)
  • Prompts for template choice:
  • starter - Minimal skeleton with Homepage module only
  • demo - Complete library management application

2. Download

Downloads framework files from upstream via git checkout FETCH_HEAD:

  • Framework core (src/)
  • Tests (tests/Phexium/, tests/*.php)
  • Configuration files (taskfile.yaml, composer.json, phpunit.xml, behat.yml, php-cs-fixer.php, rector.php, deptrac.yaml, sonar-project.properties, .gitignore)
  • Docker environment (docker/)
  • Database schemas (database/)
  • Selected template files (app/{template}/ → app/, tests/{AppDemo|AppStarter}/ → tests/App/)

3. Transformation

Adapts downloaded files to the selected template:

  • Removes references to the non-selected template from configuration files (composer.json, taskfile.yaml, phpunit.xml, behat.yml)
  • Rewrites Nginx configuration (docker/nginx/) for the selected template
  • Replaces paths (app/demo or app/starter → app) and fixes directory depth references
  • Transforms namespaces (AppDemo/AppStarter → App)

4. Configuration

  • Creates app/.env from app/.env.sample
  • Prompts for database type (SQLite, MySQL, PostgreSQL)
  • Starts Docker environment (task dev:environment:install, then task dev:environment:start)
  • Waits for database readiness (MySQL/PostgreSQL only)
  • Installs Composer dependencies

5. Finalization

  • Initializes database schema and fixtures (demo template only)
  • Saves upstream commit SHA to .phexium-version for future update tracking

Template Choices

Starter Template

The starter template (upstream app/starter/, installed as app/) provides minimal setup for new projects:

  • Homepage module with welcome message
  • Basic configuration
  • Minimal tests

Demo Template

The demo template (upstream app/demo/, installed as app/) provides a full-featured example application:

  • Library module (full CRUD with events)
  • Loan module (borrowing management)
  • User module (authentication)
  • Complete REST API
  • Comprehensive tests

Database Options

  • SQLite: Single-file database, recommended for development
  • MySQL: Production-ready RDBMS
  • PostgreSQL: Advanced RDBMS with strong ACID compliance

Database type is configured via database.type in .env.

After Installation

# Verify installation
http://localhost:8080

# Run tests
task tests:all

# Commit initial state
git add . && git commit -m "Initial Phexium setup"

Troubleshooting

Installation logs are saved to install.log for troubleshooting.