Getting Started

Installation

Complete guide to installing and setting up Glueful

This guide will walk you through installing Glueful and setting up your development environment.

System Requirements

Minimum Requirements

  • PHP: 8.2 or higher
  • Composer: 2.0 or higher
  • Memory: 512MB RAM minimum, 1GB+ recommended
  • Database: SQLite 3.8+ (built into PHP) or PostgreSQL 12+, MySQL 5.7+

Required PHP Extensions

Glueful requires these PHP extensions (most are included by default):

# Core extensions (usually pre-installed)
- json          # JSON handling
- mbstring      # Multi-byte string functions
- openssl       # Encryption and security
- PDO           # Database abstraction
- curl          # HTTP client functionality
- xml           # XML processing
- zip           # Archive handling

# Database extensions (at least one required)
- pdo_sqlite    # SQLite support (default, included with PHP)
- pdo_mysql     # MySQL/MariaDB support (optional)
- pdo_pgsql     # PostgreSQL support (optional)

# Recommended for enhanced functionality
- redis         # Redis caching support
- gd            # Image processing
- intl          # Internationalization
- bcmath        # Precise decimal calculations

Checking Your System

Verify your system is ready:

# Check PHP version
php -v

# Check required extensions
php -m | grep -E "(json|mbstring|openssl|PDO|curl|xml|zip)"

# Check Composer
composer --version

# Check memory limit
php -r "echo 'Memory Limit: ' . ini_get('memory_limit') . PHP_EOL;"

Installation Methods

Prerequisites

Before installing Glueful, you need to have PHP and Composer installed on your system.

Installing PHP (8.2 or higher)

# Using Homebrew
brew install php

# Verify installation
php -v

Installing Composer

# Using Homebrew
brew install composer

# Manual installation
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'e21205b207c3ff031906575712edab6f13eb0b361f2085f1f1237b7126d785e826a450292b6cfd1d64d92e6563bbde02') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

Method 1: API Skeleton (Recommended)

The fastest way to get started is with the pre-configured API skeleton:

# Create a new Glueful project from the API skeleton (recommended)
composer create-project glueful/api-skeleton my-project
cd my-project
# Start the development server

Your API will be available at http://127.0.0.1:8080

Method 2: Framework Only

Install just the framework into an existing project:

# Install via Composer
composer require glueful/framework

# Create minimal bootstrap (optional)
mkdir -p config public routes

Then create a basic public/index.php:

<?php
declare(strict_types=1);

use Glueful\Framework;
use Symfony\Component\HttpFoundation\Request;

require __DIR__ . '/../vendor/autoload.php';

$framework = Framework::create(dirname(__DIR__))
    ->withConfigDir(__DIR__ . '/../config')
    ->withEnvironment($_ENV['APP_ENV'] ?? 'development');

$app = $framework->boot();


$request = Request::createFromGlobals();
$response = $app->handle($request);
$response->send();
$app->terminate($request, $response);

And create routes/api.php for your routes:

<?php

use Glueful\Http\Response;

/** @var \Glueful\Routing\Router $router */

$router->get('/', function() {
    return new Response(['status' => 'ok']);
});

Initial Setup

Environment Configuration

  1. Copy the environment file:
cp .env.example .env
  1. Generate application keys:
php glueful generate:key

This will automatically generate secure keys for APP_KEY, JWT_KEY, and TOKEN_SALT.

  1. Configure your database (if not using SQLite):
# For PostgreSQL
DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

# For MySQL
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

Database Setup

# Run migrations to set up database tables
php glueful migrate:run

# Optional: Seed with sample data
php glueful migrate:seed

System Validation

Verify your installation:

# Comprehensive system check
php glueful system:check

# Detailed diagnostics
php glueful system:check --verbose

# Production readiness check
php glueful system:check --production

Development Server

Start the built-in development server:

# Default (127.0.0.1:8080)
php glueful serve

# Custom host and port
php glueful serve --host=0.0.0.0 --port=3000

# With automatic reloading
php glueful serve --reload

Testing Your Installation

Visit these endpoints to verify everything works:

  • Welcome: http://127.0.0.1:8080/
  • Health Check: http://127.0.0.1:8080/health
  • System Info: http://127.0.0.1:8080/health/system (development only)

IDE Setup

VS Code

Install recommended extensions:

  1. PHP Intelephense - Advanced PHP language support
  2. PHP Debug - Debugging support
  3. REST Client - API testing

Create .vscode/settings.json:

{
    "php.validate.executablePath": "/usr/local/bin/php",
    "php.suggest.basic": false,
    "intelephense.files.maxSize": 3000000,
    "files.associations": {
        "*.php": "php"
    }
}

PhpStorm

Glueful works out of the box with PhpStorm. Configure:

  1. Set PHP version to 8.2+
  2. Enable Composer support
  3. Configure code style to PSR-12

Environment-Specific Setup

Development

# .env
APP_ENV=development
APP_DEBUG=true
API_DOCS_ENABLED=true

Production

# .env
APP_ENV=production
# APP_DEBUG automatically set to false
# API_DOCS_ENABLED automatically set to false
FORCE_HTTPS=true

# Set strong, unique keys
APP_KEY=your_secure_32_character_key_here
JWT_KEY=your_secure_jwt_key_base64_encoded

Common Installation Issues

Memory Limits

If you encounter memory issues:

# Increase PHP memory limit temporarily
php -d memory_limit=512M glueful install

# Or permanently in php.ini
memory_limit = 512M

Extension Missing

Install missing PHP extensions:

# Ubuntu/Debian
sudo apt install php8.2-{mbstring,xml,curl,zip,sqlite3}

# macOS with Homebrew
brew install [email protected]

# CentOS/RHEL
sudo yum install php82-{mbstring,xml,curl,zip,sqlite}

Composer Issues

# Clear Composer cache
composer clear-cache

# Update Composer itself
composer self-update

# Install with verbose output
composer install --verbose

Permission Issues

# Set proper permissions for storage
chmod -R 755 storage/
chmod -R 755 bootstrap/cache/

# On some systems, you may need:
sudo chown -R www-data:www-data storage/ bootstrap/cache/

Next Steps

Once installed, you're ready to:

  1. Configure your application - Set up databases, caching, and more
  2. Follow the tutorial - Build your first API
  3. Learn the core concepts - Understand Glueful's core building blocks

Getting Help

If you encounter issues:

Introduction

Overview, quickstart, project structure, and FAQs

Quickstart

Build your first API