ChurchCRM Application Platform Prerequisites

ChurchCRM System Requirements

This is the single source of truth for all ChurchCRM system requirements. All installation and deployment documentation should reference this page.

ChurchCRM has specific platform prerequisites, and a built-in mechanism to ensure that all prerequisites are met. If there are any unmet prerequisites, a message will be displayed during setup and a notification will be displayed during runtime.

Prerequisites are validated at every page load, so if the hosting environment is changed to an incomplete / unsupported model, a notification will appear.

Validation occurs in the getApplicationPrerequisites() function.

Quick Reference

Component	Requirement	Notes
PHP	8.2 or higher	Required for all core functionality
Web Server	Apache 2.4+ with mod_rewrite	nginx may work but not officially supported
Database	MySQL 5.7+ or MariaDB 10.2+	MariaDB 10.2+ or higher recommended
Memory	256MB+ PHP memory limit	512MB+ recommended for larger congregations
Storage	500MB+ available space	Depends on attachments and data size

Detailed Prerequisites

PHP 8.2+

Synopsis

ChurchCRM makes use of many features added with PHP 8.2. Lower versions will not work.

Symptoms of failure## Detailed Prerequisites

PHP 8.2 or Higher

Status: REQUIRED

ChurchCRM makes use of many features added with PHP 8.2. Lower versions will not work.

Symptoms of failure:

• Errors and warnings about missing functions (especially random_bytes())
• Setup process displays a message indicating installation below PHP 8.2 is not possible and will halt

Resolution:

• Shared Hosting (cPanel): Ensure PHP 8.2 or higher is selected for your site
• Self-Hosted Linux: Follow the steps at Install Self Hosted Linux or Self-Hosted on RockyLinux
• Local Development: Install via XAMPP, WAMP, or MAMP Pro

Required PHP Extensions

The following PHP extensions must be installed and enabled:

bcmath

Purpose: Arbitrary precision arithmetic
Installation: php-bcmath package

curl

Purpose: HTTP requests and external API communication
Installation: php-curl package

gd

Purpose: Image manipulation (profile pictures, charts)
Installation: php-gd package

gettext

Purpose: Localization and translation support
Installation: php-gettext package

intl

Purpose: Internationalization and Unicode support
Installation: php-intl package

json

Purpose: JSON encoding/decoding (API responses)
Installation: Usually bundled with PHP

mbstring

Purpose: Multibyte string handling (UTF-8 support)
Installation: php-mbstring package

mysqli

Purpose: MySQL/MariaDB database access
Installation: php-mysql or php-mysqli package

opcache

Purpose: PHP bytecode caching for performance
Installation: php-opcache package (recommended for production)

phar

Purpose: PHP Archive support (installation/updates)
Installation: Usually bundled with PHP

soap

Purpose: SOAP web services support
Installation: php-soap package

sodium

Purpose: Modern cryptography (password hashing, encryption)
Installation: php-sodium package

xml

Purpose: XML parsing and processing
Installation: php-xml package

zip

Purpose: ZIP file handling (imports/exports, backups)
Installation: php-zip package

Web Server

Apache 2.4+ with mod_rewrite

ChurchCRM currently requires Apache's mod_rewrite module for URL routing. While we'd like to deprecate this requirement, it still exists. If you know mod_rewrite is loaded and working on your Apache setup, it is SAFE to ignore this prerequisite during setup.

nginx compatibility: nginx may work but is not officially supported or tested.

Database Server

MySQL 5.7+ or MariaDB 10.2+

• MariaDB 10.2 or higher is recommended for better performance
• Database must support:
  • UTF-8 character set
  • InnoDB storage engine
  • Foreign key constraints

File System Permissions

Config file is writable

The src/Include/Config.php file must be writable during setup

Images directory is writable

The Images/ directory must be writable for:

• Profile picture uploads
• Report generation
• Image cache storage

Temporary directory is writable

PHP must be able to write temporary files for:

• File uploads
• Session storage
• Cache operations

Character Set and Localization

PCRE with UTF-8 Support

Regular expression support with Unicode handling (usually built-in to modern PHP)

UTF-8 Locale Support

System should support UTF-8 locales for proper text handling

Memory and Performance

PHP Memory Limit

• Minimum: 256MB
• Recommended: 512MB or higher
• Larger congregations may need 1GB+

Configuration: memory_limit in php.ini

PHP Max Execution Time

• Minimum: 30 seconds
• Recommended: 60+ seconds for data imports
• Large reports may need higher values

Configuration: max_execution_time in php.ini

See PHP Max Execution Time for detailed tuning guidance.

Hosting Environment Considerations

register_globals

Must be turned OFF (deprecated PHP feature)

File Uploads

Must be enabled and configured:

• file_uploads = On
• upload_max_filesize - recommend 10MB+
• post_max_size - should match or exceed upload_max_filesize