CryptoMañana Documentation

The Object-Oriented PHP Cryptography Framework

Installation and Setup

    The CryptoMañana (CryptoManana) cryptography framework is easy to install and configure. The framework does not require any third-party dependencies or extensions for production usage. The following sections give more detailed information about the framework installation and requirements.

System Requirements

    To use the CryptoManana framework, you must have a PHP version between 5.5 and 8.3 with the default built-in set of extensions. Note that some operating systems may come with faulty a compilation of PHP or with some extensions disabled via configuration. For example, a lot of Unix unmaintained distributions sometimes forget to compile the ‘libsodium’/’ sodium’ extensions or even built extensions that are with 4 years older version than the current PHP. This happens a lot in the CentOS universe, Vagrant images or in some CI/CD build images that are recompiled daily or weekly. In most Windows or macOS based machines, the provided project may have disabled extensions in the ‘php.ini’ that should be by default enabled, so please check the configuration before you run any project.

    Do not forget to look both at your CLI and Web configuration files. Most official Docker images come pre-configured as they should, but sometimes certain extensions are faulty because of the chosen distribution or operating system library version. The framework is developed to correctly support all algorithms under both x86 and 64x machines. In addition, it correctly processed Unicode information, but keep in mind that older versions of PHP require the extra extension ‘mbstring’ to fully support that.

    The minimum system specification would require:

    The optional requirements include:

    The suggested dependencies or tools are:

Framework Installation Methods

    There are two supported methods for the framework’s installation that are described in the next sections.

    To integrate the CryptoManana framework in your project via the Composer Dependency Manager, just require the package from Packagist as follows:

# Install the package at your project via Composer
composer require karavasilev/cryptomanana

Note: The best practices suggest that you should specify a version like 1.* or ^1.0, but this is entirely up to your taste.

    As an optional procedure, if you are not entirely sure that the system is supported or configured correctly, you can call the preinstalled system checker script to scan for problems and give you suggestions:

# Optionally, check if your system is well-configured
php vendor/karavasilev/cryptomanana/check.php

# Or: ./vendor/karavasilev/cryptomanana/check

Note: This check script can flag certain missing system requirements or wrongly configured extensions, for example, the OPENSSL_CONF environmental variable may not be pointing to the openssl.cnf file or your PHP version may need an upgrade.

Manual Autoloading (Legacy)

    If you in to integrate the framework in a legacy project that does not use require and utilizes manual autoloading, then you must either integrate it manually via the src/autoloader.php autoloader or you own one, as follows:

# Download the project
wget https://github.com/TonyKaravasilev/CryptoManana/archive/master.zip

# Decompress the archive
unzip master.zip
cd CryptoManana-master

# if your project is at '/home/tony/project', then copy the framework
# source code inside a separate folder, for example 'dependencies'
mkdir –p /home/tony/project/dependencies
cp –r src/ /home/tony/project/dependencies/cryptomanana

    If your project’s entry point or autoloading point is at /home/tony/project/public/index.php, then add the following at the beginning of your autoloading code:

// Somewhere where you do your autoloading
require '../dependencies/cryptomanana/autoloader.php';

Note: The place, way or autoloading technique depends entirely on your project’s codebase, but make sure you are correctly loading the CryptoManana namespace.

Advanced Configuration Tuning

    There are more advanced configuration options supported by the framework, which will likely not be used by most developers. The next sections will explain them in detail and specify a usual use case example.

Backward Compatibility Polyfill

    By default, the CryptoManana Framework provides compatibility for different older PHP versions (polyfill script). If you would like to write your own logic or use another package for the polyfill logic, for example the famous Symfony Polyfill package, then you can disable the compatibility check (located at src/compatibility.php) via a global constant definition for CRYPTO_MANANA_COMPATIBILITY_OFF. The global constant must be defined before autoloading or before the first class usage (object call/access), as follows:

define('CRYPTO_MANANA_COMPATIBILITY_OFF', true);
// or -> const CRYPTO_MANANA_COMPATIBILITY_OFF = 1;

Note: In most cases, you should not need to do this. It will not affect your performance in any way because the built-in polyfill script is called only once per HTTP request (or CLI execution). To avoid conflicts with multiple polyfill scripts, ensure the inclusion order is correct.

Support Various Encodings

    The newest version of PHP support by default UTF-8 and ASCII processing at the function level. This was not always the case at older versions or for all available internal functions. In addition, your application may need to support another type of encoding instead, like ‘Windows-1251’. It is important to say that the HTTP protocol (at the moment) does not support any encoding bigger than UTF-8 for visualization. Still, in some cases you may be required to write a CLI script that connects to a database in a UTF-16 based collation for processing, then you would need to process those strings accurately. Because of this, a lot of the existing web frameworks have added the mbstring extension as a requirement for their installation. This extension is not built-in and may cause a lot of performance issues, but because of the functionality it provides, a lot of distributions bundle it to their PHP distribution package by default.

    The CryptoManana framework does not require the mbstring extension. If you install it on your platform, then you can tell the framework to utilize it for all the internal string processing features. To configure this, you must do something like this in your project’s entry point:

// Autoload packages via Composer class autoloader
require 'vendor' . DIRECTORY_SEPARATOR . 'autoload.php';

// Configure PHP internal encoding (default is `UTF-8` for PHP >= 5.6)
ini_set('default_charset', 'UTF-8');

// Configure `mbstring` to use your favourite UTF-8 encoding
mb_regex_encoding('UTF-8');
mb_internal_encoding('UTF-8');
mb_http_output('UTF-8');

// Enable the `mbstring` support for CryptoManana components
CryptoManana\Core\StringBuilder::useMbString(true);

// Start coding hard...

Note: The framework works without the extension and does not enable the usage of it by default for performance reasons.

Framework Integration Tips

    When integrating the components inside your project’s framework, there are many approaches that you can choose and it is all up to you (your taste, style and imagination), for example, you can:

Previous Next