Skip to content

Commit 1c22fa5

Browse files
arhiopterecsarhiopterecs
committed
[Doc] Adding new PHP extensions magento#155 
1 parent e2d21ea commit 1c22fa5

File tree

1 file changed

+160
-37
lines changed

1 file changed

+160
-37
lines changed

‎src/cloud/docker/docker-extend.md

Lines changed: 160 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -11,19 +11,19 @@ You can use the built-in extension mechanism of Docker to specify [multiple comp
1111

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

14-
```yaml
15-
version: '2'
16-
services:
17-
deploy:
14+
```yaml
15+
version: '2'
16+
services:
17+
deploy:
1818
environment:
19-
- ENABLE_SENDMAIL=false
19+
- ENABLE_SENDMAIL=false
2020
```
2121
2222
1. Pass both configuration files while executing your commands. For example:
2323
24-
```bash
25-
docker-compose -f docker-compose.yml -f docker-compose-dev.yml run deploy bash
26-
```
24+
```shell script
25+
docker-compose -f docker-compose.yml -f docker-compose-dev.yml run deploy bash
26+
```
2727

2828
## Specify Docker build sources
2929

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

3333
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.
3434

35-
```yaml
36-
version: '2.1'
37-
services:
38-
web:
39-
build:
40-
context: ./vendor/magento/magento-cloud-docker/images/nginx/1.9/
41-
```
35+
```yaml
36+
version: '2.1'
37+
services:
38+
web:
39+
build:
40+
context: ./vendor/magento/magento-cloud-docker/images/nginx/1.9/
41+
```
4242
4343
To update the container configuration and test iteratively, use the `--force-recreate` option to refresh the container build:
4444

45-
```bash
46-
docker-compose up -d --force-recreate --build
47-
```
45+
```shell script
46+
docker-compose up -d --force-recreate --build
47+
```
4848

4949
## Add a new version of existing service
5050

51-
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.
51+
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.
5252

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

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

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

60-
```bash
61-
cd magento-cloud-docker/images/<service-name>
62-
```
60+
```shell script
61+
cd magento-cloud-docker/images/<service-name>
62+
```
6363

6464
1. Create a directory for the new version.
6565

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

7272
1. Run the following command to build the image.
7373

74-
`docker build -t test/<service-name>:<service-version>`
75-
74+
```shell script
75+
docker build -t test/<service-name>:<service-version>
76+
```
77+
7678
1. Once the build succeeds, test the changes by specifying the [Docker build sources].
7779

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

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

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

89-
```bash
90-
cd magento-cloud-docker/src/Compose/Php
91+
```shell script
92+
cd magento-cloud-docker/src/Compose/Php
93+
```
9194

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

94-
For instance the following block adds the GNUPG extension:
95-
96-
```php?start_inline=1
97+
We have divided the extensions into three conditional groups:
98+
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"
99+
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"
100+
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"
101+
102+
For instance, the following block adds the `bcmath` extension:
103+
104+
```php?start_inline=1
105+
'bcmath' => [
106+
'>=7.0' => [self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE],
107+
],
108+
```
109+
110+
In this case `bcmath` extensions will be install from `docker-php-source` for all `PHP` versions starting from `7.0`.
111+
112+
In case of installing an extension from `PECL` which has a dependency on a specific package:
113+
```php?start_inline=1
97114
'gnupg' => [
98115
'>=7.0' => [
99-
self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL,
100-
self::EXTENSION_OS_DEPENDENCIES => ['libgpgme11-dev'],
101-
],],
102-
```
103-
104-
The extension type can be either CORE or PECL, which are defined as `EXTENSION_TYPE_PECL` or `EXTENSION_TYPE_CORE` respectively.
116+
self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL,
117+
self::EXTENSION_OS_DEPENDENCIES => ['libgpgme11-dev'],
118+
],
119+
],
120+
```
121+
For extension types `EXTENSION_TYPE_PECL`\\`EXTENSION_TYPE_PECL`, the following configuration pattern is valid:
122+
123+
```php?start_inline=1
124+
'<extension name>' => [ // this name will be used to identify the extension among other PHP extensions.
125+
'<php version constraint>' => [ // for which PHP versions this config will apply
126+
self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE // or self::EXTENSION_TYPE_PECL
127+
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
128+
self::EXTENSION_PACKAGE_NAME => '<raw extension name>', // if this parameter exists, then this value will be used when generating the installation command
129+
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"
130+
'--option1',
131+
'--option2',
132+
...
133+
]
134+
],
135+
'<php version constraint>' => [
136+
....
137+
]
138+
```
139+
140+
Configuration for extensions `gd`, `geoip` and would be good examples:
141+
142+
```php?start_inline=1
143+
'gd' => [
144+
'>=7.0 <=7.3' => [
145+
self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE,
146+
self::EXTENSION_OS_DEPENDENCIES => ['libjpeg62-turbo-dev', 'libpng-dev', 'libfreetype6-dev'],
147+
self::EXTENSION_CONFIGURE_OPTIONS => [
148+
'--with-freetype-dir=/usr/include/',
149+
'--with-jpeg-dir=/usr/include/'
150+
],
151+
],
152+
'>=7.4' => [
153+
self::EXTENSION_TYPE => self::EXTENSION_TYPE_CORE,
154+
self::EXTENSION_OS_DEPENDENCIES => ['libjpeg62-turbo-dev', 'libpng-dev', 'libfreetype6-dev'],
155+
self::EXTENSION_CONFIGURE_OPTIONS => [
156+
'--with-freetype=/usr/include/',
157+
'--with-jpeg=/usr/include/'
158+
],
159+
],
160+
161+
],
162+
'geoip' => [
163+
'>=7.0' => [
164+
self::EXTENSION_TYPE => self::EXTENSION_TYPE_PECL,
165+
self::EXTENSION_OS_DEPENDENCIES => ['libgeoip-dev', 'wget'],
166+
self::EXTENSION_PACKAGE_NAME => 'geoip-1.1.1',
167+
],
168+
],
169+
```
170+
171+
If the installation requires the execution of special commands, then use the type `EXTENSION_TYPE_INSTALLATION_SCRIPT`.
172+
The template for this type:
173+
174+
```php?start_inline=1
175+
'extension name' => [
176+
'php version constraint' => [
177+
self::EXTENSION_TYPE => self::EXTENSION_TYPE_INSTALLATION_SCRIPT,
178+
self::EXTENSION_INSTALLATION_SCRIPT => <<< BASH
179+
<installation script>
180+
BASH
181+
],
182+
```
183+
184+
Usage example:
185+
```php?start_inline=1
186+
'ioncube' => [
187+
'>=7.0 <=7.3' => [
188+
self::EXTENSION_TYPE => self::EXTENSION_TYPE_INSTALLATION_SCRIPT,
189+
self::EXTENSION_INSTALLATION_SCRIPT => <<< BASH
190+
cd /tmp
191+
curl -O https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
192+
tar zxvf ioncube_loaders_lin_x86-64.tar.gz
193+
export PHP_VERSION=$(php -r "echo PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION;")
194+
export PHP_EXT_DIR=$(php-config --extension-dir)
195+
cp "./ioncube/ioncube_loader_lin_\${PHP_VERSION}.so" "\${PHP_EXT_DIR}/ioncube.so"
196+
rm -rf ./ioncube
197+
rm ioncube_loaders_lin_x86-64.tar.gz
198+
BASH
199+
],
200+
```
201+
1. If you want the extension to be enabled by default, then add it to the array `DEFAULT_PHP_EXTENSIONS`
202+
203+
```php?start_inline=1
204+
/**
205+
* Extensions which should be installed by default
206+
*/
207+
public const DEFAULT_PHP_EXTENSIONS = [
208+
'bcmath',
209+
'bz2',
210+
'calendar',
211+
'exif',
212+
'gd',
213+
'gettext',
214+
'intl',
215+
'mysqli',
216+
'pcntl',
217+
'pdo_mysql',
218+
'soap',
219+
'sockets',
220+
'sysvmsg',
221+
'sysvsem',
222+
'sysvshm',
223+
'opcache',
224+
'zip',
225+
];
226+
```
227+
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.
105228

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

0 commit comments

Comments
 (0)