Skip to content

Commit

Permalink
[Doc] Adding new PHP extensions magento#155
Browse files Browse the repository at this point in the history
  • Loading branch information
@arhiopterecs
arhiopterecs committed Sep 24, 2020
1 parent e2d21ea commit 1c22fa5
Showing 1 changed file with 160 additions and 37 deletions.
197 changes: 160 additions & 37 deletions src/cloud/docker/docker-extend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,19 @@ You can use the built-in extension mechanism of Docker to specify [multiple comp

1. Create a `docker-compose-dev.yml` file inside your project root directory and add the following content:

```yaml
version: '2'
services:
deploy:
```yaml
version: '2'
services:
deploy:
environment:
- ENABLE_SENDMAIL=false
- ENABLE_SENDMAIL=false
```

1. Pass both configuration files while executing your commands. For example:

```bash
docker-compose -f docker-compose.yml -f docker-compose-dev.yml run deploy bash
```
```shell script
docker-compose -f docker-compose.yml -f docker-compose-dev.yml run deploy bash
```

## Specify Docker build sources

Expand All @@ -32,34 +32,34 @@ by adding the `build:context` configuration to the `docker-compose.override.yml`

The following example defines the build context for the Web container. You can use the same technique to build from any of the images in the `vendor/magento/magento-cloud-docker` directory or any other Docker image, including local images that are resourced outside the project.

```yaml
version: '2.1'
services:
web:
build:
context: ./vendor/magento/magento-cloud-docker/images/nginx/1.9/
```
```yaml
version: '2.1'
services:
web:
build:
context: ./vendor/magento/magento-cloud-docker/images/nginx/1.9/
```

To update the container configuration and test iteratively, use the `--force-recreate` option to refresh the container build:

```bash
docker-compose up -d --force-recreate --build
```
```shell script
docker-compose up -d --force-recreate --build
```

## Add a new version of existing service

In {{site.data.var.mcd}} package the available [service versions] are determined by the Docker service images configured in the {{site.data.var.mcd}} `images` directory. You can add a new service version by creating a directory for the version and adding a `Dockerfile` and other files to configure the new version.
In `{{site.data.var.mcd-package}}` package the available [service versions] are determined by the Docker service images configured in the `{{site.data.var.mcd-package}}` `images` directory. You can add a new service version by creating a directory for the version and adding a `Dockerfile` and other files to configure the new version.

{:.procedure}
To add a new service version using a `Dockerfile`:

1. Clone the `{{site.data.var.mcd}}` project to your local environment if necessary.
1. Clone the `{{site.data.var.mcd-package}}` project to your local environment if necessary.

1. On the command line, change to the directory that contains the existing service version configurations.

```bash
cd magento-cloud-docker/images/<service-name>
```
```shell script
cd magento-cloud-docker/images/<service-name>
```

1. Create a directory for the new version.

Expand All @@ -71,8 +71,10 @@ To add a new service version using a `Dockerfile`:

1. Run the following command to build the image.

`docker build -t test/<service-name>:<service-version>`

```shell script
docker build -t test/<service-name>:<service-version>
```

1. Once the build succeeds, test the changes by specifying the [Docker build sources].

## Add a new PHP extension
Expand All @@ -82,26 +84,147 @@ In addition to built-in extensions, you can add PHP extensions to the PHP contai
{:.procedure}
To add a new PHP extension:

1. Clone the `{{site.data.var.mcd}}` project to your local environment if necessary.
1. Clone the `{{site.data.var.mcd-package}}` project to your local environment if necessary.

1. On the command line, navigate to the PHP directory.

```bash
cd magento-cloud-docker/src/Compose/Php
```shell script
cd magento-cloud-docker/src/Compose/Php
```

1. Open the `ExtensionResolver.php` file, define the required extension inside the `getConfig` method by specifying the extension type and dependency.

For instance the following block adds the GNUPG extension:

```php?start_inline=1
We have divided the extensions into three conditional groups:
1. `EXTENSION_TYPE_CORE` - Extension that exists in the `docker-php-source` More details [https://hub.docker.com/_/php][PHP, Docker Official Images], the part "How to install more PHP extensions"
1. `EXTENSION_TYPE_PECL` - Extensions that can be installed from [https://pecl.php.net/][PECL]. More details [https://hub.docker.com/_/php][PHP, Docker Official Images], the part "PECL extensions"
1. `EXTENSION_TYPE_INSTALLATION_SCRIPT` - For extensions that can be installed by running a number commands. More details [https://hub.docker.com/_/php][PHP, Docker Official Images], part "Other extensions"

For instance, the following block adds the `bcmath` extension:

```php?start_inline=1
'bcmath' => [
'>=7.0' => [self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE],
],
```

In this case `bcmath` extensions will be install from `docker-php-source` for all `PHP` versions starting from `7.0`.

In case of installing an extension from `PECL` which has a dependency on a specific package:
```php?start_inline=1
'gnupg' => [
'>=7.0' => [
self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL,
self::EXTENSION_OS_DEPENDENCIES => ['libgpgme11-dev'],
],],
```

The extension type can be either CORE or PECL, which are defined as `EXTENSION_TYPE_PECL` or `EXTENSION_TYPE_CORE` respectively.
self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL,
self::EXTENSION_OS_DEPENDENCIES => ['libgpgme11-dev'],
],
],
```
For extension types `EXTENSION_TYPE_PECL`\\`EXTENSION_TYPE_PECL`, the following configuration pattern is valid:

```php?start_inline=1
'<extension name>' => [ // this name will be used to identify the extension among other PHP extensions.
'<php version constraint>' => [ // for which PHP versions this config will apply
self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE // or self::EXTENSION_TYPE_PECL
self::EXTENSION_OS_DEPENDENCIES => ['<name dependency package 1>', <name dependency package 2>, ... ] // Linux packages, they will be installed in the order of indication before extantion
self::EXTENSION_PACKAGE_NAME => '<raw extension name>', // if this parameter exists, then this value will be used when generating the installation command
self::EXTENSION_CONFIGURE_OPTIONS => [ // options to be applied when configuring a PHP extension using the command `docker-php-ext-configure`. More details [https://hub.docker.com/_/php][PHP, Docker Official Images], part "PHP Core Extensions"
'--option1',
'--option2',
...
]
],
'<php version constraint>' => [
....
]
```

Configuration for extensions `gd`, `geoip` and would be good examples:

```php?start_inline=1
'gd' => [
'>=7.0 <=7.3' => [
self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE,
self::EXTENSION_OS_DEPENDENCIES => ['libjpeg62-turbo-dev', 'libpng-dev', 'libfreetype6-dev'],
self::EXTENSION_CONFIGURE_OPTIONS => [
'--with-freetype-dir=/usr/include/',
'--with-jpeg-dir=/usr/include/'
],
],
'>=7.4' => [
self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE,
self::EXTENSION_OS_DEPENDENCIES => ['libjpeg62-turbo-dev', 'libpng-dev', 'libfreetype6-dev'],
self::EXTENSION_CONFIGURE_OPTIONS => [
'--with-freetype=/usr/include/',
'--with-jpeg=/usr/include/'
],
],
],
'geoip' => [
'>=7.0' => [
self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL,
self::EXTENSION_OS_DEPENDENCIES => ['libgeoip-dev', 'wget'],
self::EXTENSION_PACKAGE_NAME => 'geoip-1.1.1',
],
],
```

If the installation requires the execution of special commands, then use the type `EXTENSION_TYPE_INSTALLATION_SCRIPT`.
The template for this type:

```php?start_inline=1
'extension name' => [
'php version constraint' => [
self::EXTENSION_TYPE => self::EXTENSION_TYPE_INSTALLATION_SCRIPT,
self::EXTENSION_INSTALLATION_SCRIPT => <<< BASH
<installation script>
BASH
],
```

Usage example:
```php?start_inline=1
'ioncube' => [
'>=7.0 <=7.3' => [
self::EXTENSION_TYPE => self::EXTENSION_TYPE_INSTALLATION_SCRIPT,
self::EXTENSION_INSTALLATION_SCRIPT => <<< BASH
cd /tmp
curl -O https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar zxvf ioncube_loaders_lin_x86-64.tar.gz
export PHP_VERSION=$(php -r "echo PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION;")
export PHP_EXT_DIR=$(php-config --extension-dir)
cp "./ioncube/ioncube_loader_lin_\${PHP_VERSION}.so" "\${PHP_EXT_DIR}/ioncube.so"
rm -rf ./ioncube
rm ioncube_loaders_lin_x86-64.tar.gz
BASH
],
```
1. If you want the extension to be enabled by default, then add it to the array `DEFAULT_PHP_EXTENSIONS`

```php?start_inline=1
/**
* Extensions which should be installed by default
*/
public const DEFAULT_PHP_EXTENSIONS = [
'bcmath',
'bz2',
'calendar',
'exif',
'gd',
'gettext',
'intl',
'mysqli',
'pcntl',
'pdo_mysql',
'soap',
'sockets',
'sysvmsg',
'sysvsem',
'sysvshm',
'opcache',
'zip',
];
```
Otherwise, to enable, you will need to specify the name of the extension in the file `magento.app.yaml` of your projects and restart docker container.

1. Add any required `.ini` files to the PHP FPM container configuration.

Expand Down

0 comments on commit 1c22fa5

Please sign in to comment.