ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2024-12-20 21:33:07 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

DVL-012 Documentation: How to load custom PHP modules

Browse Source
This commit is contained in:
cytopia 2017-08-13 13:36:24 +02:00
parent d6bf969212
commit e2c724ce23
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
4 changed files with 110 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -192,6 +192,7 @@ The devilbox has everything setup for you. The only thing you will have to insta
* **Email catch-all** (Internal postfix with catch-all)
* **Log files** (available on host computer)
* **Config overwrites** (`my.cnf`, `nginx.conf`, `httpd.conf` or `php.ini`)
* **Custom PHP modules**
* **Self-validation** (projects and configured options are validated and marked in the intranet)
* **Xdebug**
@ -226,6 +227,10 @@ The devilbox is a development stack, so it is made sure that a lot of PHP module
> *apc, apcu, bcmath, bz2, calendar, Core, ctype, curl, date, dom, ereg, exif, fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv, igbinary, imagick, imap, intl, json, ldap, libxml, magickwand, mbstring, mcrypt, memcache, memcached, mhash, mongodb, msgpack, mysql, mysqli, mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, phalcon, Phar, posix, pspell, readline, recode, redis, Reflection, session, shmop, SimpleXML, soap, sockets, SPL, sqlite3, standard, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, uploadprogress, wddx, xdebug, xml, xmlreader, xmlrpc, xmlwriter, xsl, Zend OPcache, zip, zlib*
** Custom PHP Modules**
You can also copy any custom modules into `mod/(php-fpm|hhvm)-<VERSION>` and add a custom `*.ini` file to load them. See [Custom PHP Modules](docs/Configure.md#425-custom-php-modules) in the Configuration documentation for how to do that in two simple steps.
#### Supported Frameworks
As far as tested there are no limitations and you can use any Framework or CMS just as you would on your live environment. Below are a few examples of extensively tested Frameworks and CMS:

76
docs/Configure.md
View File

@ -21,8 +21,10 @@ Configure |
1. [Overview](#1-overview)
1. [The devilbox `.env` file](#11-the-devilbox-env-file)
2. [The devilbox `cfg/` directory](#12-the-devilbox-cfg-directory)
3. [The operating system `hosts` file](#13-the-operating-system-hosts-file)
4. [The operating system `resolv.conf` file](#14-the-operating-system-resolvconf-file)
3. [The devilbox `mod/` directory](#13-the-devilbox-mod-directory)
1. [Custom PHP module example](#134-custom-php-module-example)
4. [The operating system `hosts` file](#14-the-operating-system-hosts-file)
5. [The operating system `resolv.conf` file](#15-the-operating-system-resolvconf-file)
2. [Devilbox general settings](#2-devilbox-general-settings)
1. [Verbosity](#21-verbosity)
2. [Devilbox base path](#22-devilbox-base-path)
@ -40,6 +42,7 @@ Configure |
2. [Xdebug](#422-xdebug)
3. [php.ini](#423-phpini)
4. [HHVM](#424-hhvm)
5. [Custom PHP modules](#425-custom-php-modules)
3. [Apache / Nginx](#43-apache--nginx)
1. [Select Httpd version](#431-select-httpd-version)
2. [Host port](#432-host-port)
@ -103,7 +106,7 @@ You can get more information here:
#### 1.2 The devilbox `cfg/` directory
Inside the devilbox root directory you will find a foder called `cfg/`. This will contain subdirectories in the form of `<SERVICE>-<VERSION>`. Those folders will be mounted into the appropriate location into the respective docker container in order to overwrite service configuration.
Inside the devilbox root directory you will find a folder called `cfg/`. This will contain subdirectories in the form of `<SERVICE>-<VERSION>`. Those folders will be mounted into the appropriate location into the respective docker container in order to overwrite service configuration.
Currently only MySQL/MariaDB and PHP/HHVM overrides are supported.
@ -141,13 +144,45 @@ Only files which have the correct file extensions will be read, all others such
* Valid PHP config extension: `.ini`
* Valid MySQL config extension: `.cnf`
#### 1.3 The operating system `hosts` file
#### 1.3 The devilbox `mod/` directory
Inside the devilbox root directory you will find a folder called `mod/`. This will contain subdirectories in the form of `(php-fpm|hhvm)-<VERSION>`. Those folders will be mounted into the appropriate location into the respective PHP docker container under `/usr/lib64/php/custom-modules/` in order to provide custom PHP modules.
The folder structure looks like this:
```
cfg/
hhvm-latest/
php-fpm-5.4/
php-fpm-5.5/
php-fpm-5.6/
php-fpm-7.0/
php-fpm-7.1/
php-fpm-7.2/
```
Each of the folders are empty by default. Place any PHP modules (`*.so`) inside the versioned folder of your choice.
Modules placed in the above folders are not loaded by default. You will also have to enable them via your custom configuration as described in the above section.
##### 1.3.4 Custom PHP module example
The following example will add a custom [ioncube](https://www.ioncube.com) module for PHP 7.0:
1. Copy `ioncube_loader_lin_7.0.so` to `mod/php-fpm-7.0/ioncube_loader_lin_7.0.so`
2. Create custom config to enable ioncube in: `cfg/php-fpm-7.0/00-ioncube.ini`
```shell
zend_extension = /usr/lib64/php/custom-modules/ioncube_loader_lin_7.0.so
```
**Note:** PHP configuration files are loaded by file names in alphabetical order and the ioncube zend extension needs to be loaded before any other zend extension. This is the reason why its configuration file name starts with `00-`.
#### 1.4 The operating system `hosts` file
On Linux and OSX your hosts file is located at `/etc/hosts` on Windows it will be at `C:\Windows\System32\drivers\etc`. Use this file to setup custom DNS entries if you are not using Auto-DNS.
Read up on it below at `/etc/hosts` or `Auto-DNS` section.
#### 1.4 The operating system `resolv.conf` file
#### 1.5 The operating system `resolv.conf` file
This file is used to add the devilbox DNS server for Auto-DNS.
@ -378,6 +413,37 @@ By default, HHVM is using **PHP-7** mode, you can change this setting to **PHP-5
**Note:** You must then also copy the file to something that ends by `*.ini`.
##### 4.2.5 Custom PHP modules
The devilbox supports to load custom PHP modules for each version without having to rebuild the PHP containers. There are only two things to be done in order to load them:
1. Copy your custom module to `mod/(hhvm|php-fpm)-<VERSION>/*.so`
2. Create a config file that loads the module in `cfg/(hhvm|php-fpm)-<VERSION>/*.ini`
As you will need to state the Path of the module to be loaded in your configuration file (`*.ini`), you will need to know where those modules are placed inside the docker container. Have a look at the following table to find out:
| Docker | Module host path | Path inside Docker container |
|---------|----------------------------|------------------------------------------|
| PHP 5.4 | `mod/php-fpm-5.4/<mod>.so` | `/usr/lib64/php/custom-modules/<mod>.so` |
| PHP 5.5 | `mod/php-fpm-5.5/<mod>.so` | `/usr/lib64/php/custom-modules/<mod>.so` |
| PHP 5.6 | `mod/php-fpm-5.6/<mod>.so` | `/usr/lib64/php/custom-modules/<mod>.so` |
| PHP 7.0 | `mod/php-fpm-7.0/<mod>.so` | `/usr/lib64/php/custom-modules/<mod>.so` |
| PHP 7.1 | `mod/php-fpm-7.1/<mod>.so` | `/usr/lib64/php/custom-modules/<mod>.so` |
| PHP 7.2 | `mod/php-fpm-7.2/<mod>.so` | `/usr/lib64/php/custom-modules/<mod>.so` |
| HHVM | `mod/hhvm-latest/<mod>.so` | `/usr/lib64/php/custom-modules/<mod>.so` |
As you can see from the above table, modules are always available in `/usr/lib64/php/custom-modules/` and you can just copy/paste your configuration files for each PHP version.
The following will show an example how to load [ioncube](https://www.ioncube.com) module for PHP 7.0:
1. Copy `ioncube_loader_lin_7.0.so` to `mod/php-fpm-7.0/ioncube_loader_lin_7.0.so`
2. Create custom config to enable ioncube in: `cfg/php-fpm-7.0/00-ioncube.ini`
```shell
zend_extension = /usr/lib64/php/custom-modules/ioncube_loader_lin_7.0.so
```
**Note:** PHP configuration files are loaded by file names in alphabetical order and the ioncube zend extension needs to be loaded before any other zend extension. This is the reason why its configuration file name starts with `00-`.
#### 4.3 Apache / Nginx
##### 4.3.1 Select Httpd version

55
docs/FAQ.md
View File

@ -27,36 +27,36 @@ FAQ
## 1. General
**Are there any differences between Linux, Windows and OSX?**
#### Are there any differences between Linux, Windows and OSX?
Yes, have a look at **[OS](OS.md)** to read up about the differences.
**Why are mounted MySQL data directories separated by version?**
#### Why are mounted MySQL data directories separated by version?
This is just a pre-caution. Imagine they would link to the same datadir. You start the devilbox with mysql 5.5, create a database and add some data. Now you decide to switch to mysql 5.7 and restart the devilbox. The newer mysql version will probably upgrade the data leaving it unable to start with older mysql versions.
**Why are mounted PostgreSQL data directories separated by version?**
#### Why are mounted PostgreSQL data directories separated by version?
See: *Why are mounted MySQL data directories separated by version?*
**Why are mounted MongoDB data directories separated by version?**
#### Why are mounted MongoDB data directories separated by version?
See: *Why are mounted MySQL data directories separated by version?*
**Why do the user/group permissions of log/ or cfg/ directories show 1000?**
#### Why do the user/group permissions of log/ or cfg/ directories show 1000?
Uid and Gid are set to 1000 by default. You can alter them to match the uid/gid of your current user. Open the `.env` file and change the sections `NEW_UID` and `NEW_GID`. When you start up the devilbox, the php-container will use these values for its user.
**Can I not just comment out the service in the `.env` file?**
#### Can I not just comment out the service in the `.env` file?
No, don't do this. This will lead to unexpected behaviour (different versions will be loaded).
The `.env` file allows you to configure the devilbox, but not to start services selectively.
**Are there any required services that must/will always be started?**
#### Are there any required services that must/will always be started?
Yes. `http` and `php` will automatically always be started (due to dependencies inside `docker-compose.yml`) if you specify them or not.
**What PHP Modules are available?**
#### What PHP Modules are available?
The devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks.
@ -72,26 +72,30 @@ There will however be slight differences between the versions and especially wit
[PHP 7.2](https://github.com/cytopia/docker-php-fpm-7.2) |
[HHVM](https://github.com/cytopia/docker-hhvm-latest)
#### Can I load custom PHP modules without rebuilding the Docker container?
Yes. You can load custom PHP modules for each PHP version separately. See [Custom PHP Modules](Configure.md#425-custom-php-modules) in the Configuration documentation.
## 2. Configuration
**Can I change the MySQL root password?**
#### Can I change the MySQL root password?
Yes, you can change the password of the MySQL root user. If you do so, you must also set the new password in your `.env` file. See **[Configure](Configure.md)** for how to change the values.
**Can I add other PHP Modules?**
#### Can I add other PHP Modules?
Yes, if there are any PHP modules you require that are not yet available in the PHP Docker container, you can install it during run-time, or create your own container. See **[Hacking](Hacking.md)** for more information.
**Can I change php.ini?**
#### Can I change php.ini?
Yes, php.ini directives can be changes on a per PHP version base. Go to `./cfg/` inside devilbox git diretory. There you will find configuration directories for each php version. Just put a \*.ini file there and restart the devilbox.
**Can I change my.cnf?**
#### Can I change my.cnf?
Yes, my.cnf directives can be changes on a per MySQL version base. Go to `./cfg/` inside devilbox git diretory. There you will find configuration directories for each MySQL version. Just put a \*.cnf file there and restart the devilbox.
**Can I switch HHVM between PHP 5.6 and PHP 7 mode?**
#### Can I switch HHVM between PHP 5.6 and PHP 7 mode?
Yes, this can be done by adding a \*.ini file to `./cfg/hhvm-latest/` with the following content to disable PHP 7 mode:
@ -100,7 +104,7 @@ hhvm.php7.all = 0
```
The default is to use PHP 7 mode.
**Can I change the project virtual host domain `.loc`?**
#### Can I change the project virtual host domain `.loc`?
Yes, the `.env` variable `TLD_SUFFIX` can be adjusted with whatever domain or subdomain your require. A few examples to get you started:
@ -111,52 +115,53 @@ Yes, the `.env` variable `TLD_SUFFIX` can be adjusted with whatever domain or su
| project1 | dev | http://project1.dev |
| project1 | work.loc | http://project1.work.loc |
**Can I just start PHP and MySQL instead of all container?**
#### Can I just start PHP and MySQL instead of all container?
Yes, every Docker container is optional. The devilbox allows for selective startup. See **[Run: selective start](Run.md#13-selective-start)** for more detail.
**Do I always have to edit `/etc/hosts` for new projects?**
#### Do I always have to edit `/etc/hosts` for new projects?
You need a valid DNS entry for every project that points to the Httpd server. As those records don't exists by default, you will have to create them. However, the devilbox has a bundled DNS server that can automate this for you. The only thing you have to do for that to work is to add this DNS server's IP address to your `/etc/resolv.conf`. See **[Configure: AutoDNS](Configure.md#62-auto-dns)** for instructions.
## 3. Usage
**Does it work with CakePHP?**
#### Does it work with CakePHP?
Yes, see **[How to setup CakePHP](Examples.md#2-setup-cakephp)**.
**Does it work with Drupal?**
#### Does it work with Drupal?
Yes, see **[How to setup Drupal](Examples.md#3-setup-drupal)**.
**Does it work with Laravel?**
#### Does it work with Laravel?
Yes, see **[How to setup Laravel](Examples.md#4-setup-laravel)**.
**Does it work with PhalconPHP?**
#### Does it work with PhalconPHP?
Yes, see **[How to setup Phalcon](Examples.md#5-setup-phalcon)**.
**Does it work with Symfony?**
#### Does it work with Symfony?
Yes, see **[How to setup Symfony](Examples.md#6-setup-symfony)**.
**Does it work with Wordpress?**
#### Does it work with Wordpress?
Yes, see **[How to setup Wordpress](Examples.md#7-setup-wordpress)**.
**Does it work with Yii?**
#### Does it work with Yii?
Yes, see **[How to setup Yii](Examples.md#8-setup-yii)**.
**Does it work with Zend Framework?**
#### Does it work with Zend Framework?
Yes, see **[How to setup Zend](Examples.md#9-setup-zend)**.
## 4. Troubleshooting
**`Invalid bind mount spec` after changing the path of MySQL, PgSQL, Mongo or the Data dir.**
#### `Invalid bind mount spec` after changing the path of MySQL, PgSQL, Mongo or the Data dir.
When you change any paths inside `.env` that affect Docker mountpoints, the container need to be *removed* and re-created during the next startup. *Removing* the container is sufficient as they will always be created during run if they don't exist.

4
docs/README.md
View File

@ -79,6 +79,7 @@ New folders can be created, deleted and removed during run-time and correspondin
| **Configuration** | |
| HHVM | You can choose between PHP 5.6 and PHP 7 mode for HHVM |
| php.ini | You an overwrite PHP settings for each PHP version. |
| Custom PHP modules | You can add any custom PHP modules without having to rebuild the Docker container. |
| my.cnf | You an overwrite MySQL settings for each MySQL version. |
| **Intranet** | |
| phpMyAdmin | Manage your MySQL databases here. |
@ -171,6 +172,9 @@ There will however be slight differences between the versions and especially wit
[PHP 7.2](https://github.com/cytopia/docker-php-fpm-7.2) |
[HHVM](https://github.com/cytopia/docker-hhvm-latest)
** Custom PHP Modules**
Apart from asking for new modules to be bundled with each Docker container, you can simply also just place any missing modules into `mod/(php-fpm|hhvm)-<VERSION>` and add a custom `*.ini` file to load them. See [Custom PHP Modules](Configure.md#425-custom-php-modules) in the Configuration documentation for how to do that in two simple steps.
## 9. Supported Frameworks and CMS